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
DBIO::PostgreSQL::Vector::Op — operator object returned by
vector(), with the distance and consumption methodsDBIO::PostgreSQL::JSONB — the JSONB path DSL this module mirrors
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.