NAME
DBIO::PostgreSQL::Vector::Op - pgvector distance-operator object built by vector()
VERSION
version 0.900007
DESCRIPTION
Operator object representing a pgvector distance expression. You do not construct this class directly — use the vector() helper from DBIO::PostgreSQL::Vector:
use DBIO::PostgreSQL::Vector qw(vector);
my $expr = vector('me.embedding'); # DBIO::PostgreSQL::Vector::Op
$rs->search( {}, { order_by => $expr->cosine_distance([0.1, 0.2])->as_order } );
A distance method (l2_distance etc.) selects the pgvector distance operator and the query vector; it returns a fresh operator object carrying the rendered SQL and its bind. A consumption method (as_order, the threshold comparisons, as_select) then turns that into a SQL::Abstract fragment.
METHODS
new
my $expr = DBIO::PostgreSQL::Vector::Op->new( col => 'me.embedding', cast => 'halfvec' );
The constructor vector() calls. col is the column as it is written into the SQL; cast, optional, the type the placeholder of the query vector is cast to. The identifiers of this DSL are code: col is letters, digits, underscores and dots (me.embedding), and any other form throws a DBIO::Exception. A cast other than vector, halfvec, sparsevec and bit throws when a distance method renders the expression.
l2_distance
vector('me.embedding')->l2_distance([0.1, 0.2])
# (me.embedding <-> ?::vector)
Euclidean (L2) distance, operator <->. Also the default "distance" operator for most pgvector types.
max_inner_product
vector('me.embedding')->max_inner_product([0.1, 0.2])
# (me.embedding <#> ?::vector)
Maximum inner product, operator <#>. Sort ascending for similarity (the largest inner product sorts first).
cosine_distance
vector('me.embedding')->cosine_distance([0.1, 0.2])
# (me.embedding <=> ?::vector)
Cosine distance, operator <=>. The standard choice for KNN search.
l1_distance
vector('me.embedding')->l1_distance([0.1, 0.2])
# (me.embedding <+> ?::vector)
Taxicab (Manhattan, L1) distance, operator <+>. Requires the halfvec type.
hamming_distance
vector('me.embedding')->hamming_distance('101010')
# (me.embedding <~> ?::bit)
Hamming distance, operator <~>. For bit columns; the placeholder cast is forced to bit — the operator only exists for bit columns.
jaccard_distance
vector('me.embedding')->jaccard_distance('101010')
# (me.embedding <%> ?::bit)
Jaccard distance, operator <%>. For bit columns; the placeholder cast is forced to bit — the operator only exists for bit columns.
lt
vector('me.embedding')->l2_distance($v)->lt(5)
# WHERE (me.embedding <-> ?::vector) < ?
Distance-range comparison: the expression holds if the distance is less than $val. Use for threshold filtering in search().
le
vector('me.embedding')->l2_distance($v)->le(5)
# WHERE (me.embedding <-> ?::vector) <= ?
gt
vector('me.embedding')->l2_distance($v)->gt(5)
# WHERE (me.embedding <-> ?::vector) > ?
ge
vector('me.embedding')->l2_distance($v)->ge(5)
# WHERE (me.embedding <-> ?::vector) >= ?
as_order
$rs->search(
{},
{ order_by => vector('me.embedding')->cosine_distance([0.1, 0.2])->as_order },
);
# ORDER BY (me.embedding <=> ?::vector)
Returns a literal-with-bind fragment suitable for use as an order_by value (the query vector travels as a bind placeholder, not inlined SQL). Combine with -asc/-desc wrappers as usual:
{ order_by => { -desc => vector('me.embedding')->l2_distance($v)->as_order } }
# ORDER BY (me.embedding <-> ?::vector) DESC
as_select
$rs->search(
{},
{ select => [ vector('me.embedding')->l2_distance($v)->as_select('distance') ] },
);
# SELECT (me.embedding <-> ?::vector) AS distance
Returns a literal-with-bind fragment selecting the distance value under the given alias. $alias is code, written into the SQL as it is: letters, digits, underscores and dots, and any other form throws a DBIO::Exception.
SEE ALSO
DBIO::PostgreSQL::Vector — the
vector()helper that builds these objectsDBIO::PostgreSQL::JSONB::Op — the JSONB operator object this class 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.