NAME

DBIO::PostgreSQL::Vector - pgvector distance-query helpers for DBIO::PostgreSQL

VERSION

version 0.900007

SYNOPSIS

use DBIO::PostgreSQL::Vector qw(vector);

# KNN — nearest neighbors by cosine distance (smallest first)
$rs->search(
  {},
  {
    order_by => vector('me.embedding')->cosine_distance([0.1, 0.2])->as_order,
    rows     => 5,
  },
);
# ORDER BY (me.embedding <=> ?::vector) LIMIT 5

# KNN, descending (furthest first)
$rs->search( {}, { order_by => { -desc => vector('me.embedding')->l2_distance([0.1, 0.2])->as_order } } );

# Distance range filter in WHERE
$rs->search( vector('me.embedding')->l2_distance($v)->lt(5) );
# WHERE (me.embedding <-> ?::vector) < ?

# Distance range filter combined with a regular condition
$rs->search([
  vector('me.embedding')->l2_distance($v)->le(3),
  { 'me.active' => 1 },
]);

# Selecting the distance (feeds the nearest_neighbors follow-up work)
$rs->search(
  {},
  {
    select => [ vector('me.embedding')->l2_distance($v)->as_select('distance') ],
  },
);
# SELECT (me.embedding <-> ?::vector) AS distance

DESCRIPTION

Provides the vector() helper function that builds pgvector distance expressions without handwritten literal SQL. The generated SQL uses PostgreSQL's pgvector distance operators (<->, <=>, <#>, <+> <~>, <%>) with the query vector as a bound parameter:

ORDER BY (me.embedding <=> ?::vector)   -- cosine nearest neighbors (KNN)
WHERE (me.embedding <-> ?::vector) < ?  -- L2 distance range filter

The distance methods themselves live on DBIO::PostgreSQL::Vector::Op, the operator object returned by vector(). This module only exports the helper.

METHODS

vector

use DBIO::PostgreSQL::Vector qw(vector);

my $expr = vector($column);
my $expr = vector($column, cast => 'halfvec');

Returns a DBIO::PostgreSQL::Vector::Op object representing a vector column ready for a distance operator. Call a distance method (l2_distance, cosine_distance, ...) on the returned object to produce an expression for ORDER BY, WHERE, or SELECT.

$column may include a table alias prefix (e.g. 'me.embedding'). It is code, written into the SQL as it is: letters, digits, underscores and dots, and any other form throws a DBIO::Exception. Do not build it from user input.

The query vector is sent as a bind placeholder cast to the column's type. cast defaults to vector and can be overridden for halfvec, sparsevec or bit columns — see DBIO::PostgreSQL::Vector::Op for the exact cast rules.

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.