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,p2 when 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_type would otherwise trigger it, mirroring inflate_datetime => 0 in DBIO::InflateColumn::DateTime:

__PACKAGE__->add_columns(
  body_search => { data_type => 'tsvector', inflate_tsvector => 0 },
);

SEE ALSO

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.