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

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.