NAME
DBIO::PostgreSQL::InflateColumn::TSVector - Auto-inflate/deflate PostgreSQL tsvector columns to/from Perl data structures
VERSION
version 0.900007
SYNOPSIS
package MyApp::DB::Result::Doc;
use base 'DBIO::Core';
__PACKAGE__->load_components('PostgreSQL::Result'); # loads this component
__PACKAGE__->add_columns(
body_search => { data_type => 'tsvector' },
);
Then treat the column as a Perl data structure:
# store: hashref of lexeme => [ positions ]
$row->update({ body_search => { cat => [3], fat => [2, 4], rat => ['5A'] } });
# stored as 'cat':3 'fat':2,4 'rat':5A
# or a bare list of words (positionless lexemes)
$row->update({ body_search => [qw( cat dog )] }); # stored as 'cat' 'dog'
# read back: hashref of lexeme => [ positions ]
my $tsv = $row->body_search; # { cat => ['3'], fat => ['2','4'], rat => ['5A'] }
DESCRIPTION
This component translates tsvector column data between PostgreSQL's text input/output format and a Perl data structure, following the DBIO::InflateColumn::DateTime pattern: a register_column hook that calls "inflate_column" in DBIO::InflateColumn for the columns it recognises.
It is loaded automatically by DBIO::PostgreSQL::Result, so declaring a tsvector column is the whole opt-in (ADR 0006 — declaring the column is the whole opt-in) — no user glue. The mapping:
inflate (fetch): the tsvector output form
'cat':3 'fat':2,4 'rat':5A— sorted, distinct lexemes, each optionally followed by:and a comma-separated position list — becomes a HashRef{ cat => ['3'], fat => ['2','4'], rat => ['5A'] }. A positionless lexeme maps to an empty ArrayRef. Positions are kept verbatim as strings, so a weight suffix (A–D, e.g.'5A') is never lost. The empty tsvector (PostgreSQL prints it as'') inflates to{}.deflate (insert/update bind): a HashRef
{ lexeme => [ positions ] }deflates to a raw tsvector literal, lexemes sorted,'lexeme':p1,p2when it has positions and bare'lexeme'when it does not. A value that is a plain scalar (or undef) rather than an ArrayRef is treated as a single (or no) position. An ArrayRef of words deflates to positionless lexemes'cat' 'dog'. Single quotes inside a lexeme are doubled.
Deflate produces a bind value (a string), not SQL, so it emits a raw tsvector literal rather than a to_tsvector(...) call: a function call is SQL and cannot be bound as a parameter. Feed to_tsvector() through a literal expression in search/update when you want the server to normalise text; this component's job is the value on the wire.
The conversion is idempotent: a plain string is passed through verbatim on both directions, so an already-serialized value is never double-serialized, and a fetched value that does not look like a tsvector literal is returned as-is rather than mangled. Non-tsvector columns are untouched.
METHODS
register_column
Chains with the "register_column" in DBIO::Row method, and sets up tsvector columns appropriately. This would not normally be directly called by end users.
COLUMN INFO
inflate_tsvector => 0-
Opt out of inflation for a single column whose
data_typewould otherwise trigger it, mirroringinflate_datetime => 0in DBIO::InflateColumn::DateTime:__PACKAGE__->add_columns( body_search => { data_type => 'tsvector', inflate_tsvector => 0 }, );
SEE ALSO
DBIO::PostgreSQL::Result — the Result component that loads this one
DBIO::PostgreSQL::InflateColumn::Vector — the sibling component that inflates pgvector columns, whose pattern this one follows
DBIO::InflateColumn::DateTime — the component pattern this follows
AUTHOR
DBIO & DBIx::Class Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.