NAME

DBIO::PostgreSQL::InflateColumn::Vector - Auto-inflate/deflate pgvector columns to/from Perl data structures

VERSION

version 0.900007

SYNOPSIS

package MyApp::DB::Result::Item;
use base 'DBIO::Core';
__PACKAGE__->load_components('PostgreSQL::Result');   # loads this component

__PACKAGE__->add_columns(
  embedding => { data_type => 'vector(3)' },
  sparse    => { data_type => 'sparsevec(3)' },
);

Then treat the columns as Perl data structures:

$row->update({ embedding => [0.1, 0.2, 0.3] });   # stored as '[0.1,0.2,0.3]'
my $v = $row->embedding;                          # [0.1, 0.2, 0.3]

$row->update({ sparse => { 0 => 0.1, 2 => 0.2 } });  # stored as '{0:0.1,2:0.2}/3'
my $s = $row->sparse;   # { dims => 3, values => { 0 => 0.1, 2 => 0.2 } }

DESCRIPTION

This component translates pgvector column data between PostgreSQL's text input/output format and Perl data structures, 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 pgvector column is the whole opt-in — no user glue. The mapping:

  • vector(N) / halfvec(N) — dense vectors. An ArrayRef of numbers deflates to [0.1,0.2] on insert/update/search binds; [0.1,0.2] inflates back to an ArrayRef on fetch.

  • sparsevec(N) — sparse vectors. A HashRef deflates to {i:v,...}/N; {i:v,...}/N inflates back to { dims => N, values => { i => v } } (the same shape the DBIO::PostgreSQL::Vector query DSL accepts). The dimensions come from the column declaration sparsevec(N); a HashRef without an explicit { dims => N, values => {...} } wrapper on a dimension-less column is an error rather than a guess.

  • bit(N) — not inflated. pgvector binary vectors are plain PostgreSQL bit(N) columns, a general engine type rather than a pgvector one, and their bitstring form is already the natural Perl representation ('101010' feeds the Hamming/Jaccard operators directly).

The conversion is idempotent: a plain string is passed through verbatim on both directions, so an already-serialized value (e.g. '[0.1, 0.2]') is never double-serialized, and a fetched value that does not look like a pgvector literal is returned as-is rather than mangled. Non-pgvector columns are untouched.

METHODS

register_column

Chains with the "register_column" in DBIO::Row method, and sets up pgvector columns appropriately. This would not normally be directly called by end users.

COLUMN INFO

inflate_pgvector => 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(
  embedding => { data_type => 'vector(3)', inflate_pgvector => 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.