| 1 | package DBIO::PostgreSQL::Vector::Op; | ||||||||||||||||||||||||||||||||||||||||||
| 2 | # ABSTRACT: pgvector distance-operator object built by vector() | ||||||||||||||||||||||||||||||||||||||||||
| 3 | |||||||||||||||||||||||||||||||||||||||||||
| 4 | 29 | ▶ | use strict; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 5 | 29 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||||||||||||||||
| 7 | 29 | our $VERSION = '0.900007'; | |||||||||||||||||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||||||||||||||||
| 9 | 29 | ▶ | use Carp (); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||||||||||||||||||||
| 11 | 29 | ▶ | use DBIO::Exception (); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||||||||||||||||
| 13 | |||||||||||||||||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||||||||||||||||
| 15 | 46 | ▶ | sub new { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 16 | 46 | my ( $class, %args ) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 17 | DBIO::Exception->throw( | ||||||||||||||||||||||||||||||||||||||||||
| 18 | 'vector: the column is a plain identifier (letters, digits, underscores and dots)' | ||||||||||||||||||||||||||||||||||||||||||
| 19 | 46 | ▶ | ) unless defined $args{col} && !ref $args{col} && $args{col} =~ /\A[\w.]+\z/; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition83%5/6
defined $args{"col"} and not ref $args{"col"} and $args{"col"} =~ /\A[\w.]+\z/
defined $args{"col"} and not ref $args{"col"}
MC/DC66%2/3
defined $args{"col"} and not ref $args{"col"} and $args{"col"} =~ /\A[\w.]+\z/
defined $args{"col"}
not ref $args{"col"}
$args{"col"} =~ /\A[\w.]+\z/
Truth table75%3/4
A and not(B) and C
A= defined $args{"col"}B= not ref $args{"col"}C= $args{"col"} =~ /\A[\w.]+\z/
| |||||||||||||||||||||||||||||||||||||||||||
| 20 | 40 | return bless \%args, $class; | |||||||||||||||||||||||||||||||||||||||||
| 21 | } | ||||||||||||||||||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||||||||||||||||
| 23 | # Only pgvector's real type names are legal cast targets. The cast is | ||||||||||||||||||||||||||||||||||||||||||
| 24 | # interpolated unquoted into the SQL string below, so anything outside this | ||||||||||||||||||||||||||||||||||||||||||
| 25 | # list is a SQL-injection surface, not a feature. | ||||||||||||||||||||||||||||||||||||||||||
| 26 | 29 | my %ALLOWED_CAST = map { $_ => 1 } qw( vector halfvec sparsevec bit ); | |||||||||||||||||||||||||||||||||||||||||
| 27 | |||||||||||||||||||||||||||||||||||||||||||
| 28 | # Builds the distance expression (col <op> ?::cast) and its bind from a query | ||||||||||||||||||||||||||||||||||||||||||
| 29 | # vector. Returns a fresh Op so the original (column-only) object stays reusable. | ||||||||||||||||||||||||||||||||||||||||||
| 30 | 40 | ▶ | sub _distance { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_distance: called CC=6 SCAR=17.9
| |||||||||||||||||||||||||||||||||||||||||||
| 31 | 40 | my ( $self, $op, $qv, $force_cast ) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 32 | |||||||||||||||||||||||||||||||||||||||||||
| 33 | 40 | my $text = $self->_serialize_query_vector($qv); | |||||||||||||||||||||||||||||||||||||||||
| 34 | # Placeholder cast defaults to the vector type; a sparsevec query vector | ||||||||||||||||||||||||||||||||||||||||||
| 35 | # (hashref) defaults to sparsevec instead. An explicit cast option on | ||||||||||||||||||||||||||||||||||||||||||
| 36 | # vector() overrides either — the escape hatch for halfvec/sparsevec/bit. | ||||||||||||||||||||||||||||||||||||||||||
| 37 | # hamming/jaccard force 'bit': their operators only exist for bit columns, | ||||||||||||||||||||||||||||||||||||||||||
| 38 | # so any other cast (explicit or default) would be invalid SQL. | ||||||||||||||||||||||||||||||||||||||||||
| 39 | # (The cast-override decision itself belongs to the pgvector ADR, karr k42.) | ||||||||||||||||||||||||||||||||||||||||||
| 40 | 40 | my $cast = $self->{cast}; | |||||||||||||||||||||||||||||||||||||||||
| 41 | DBIO::Exception->throw( 'vector: unknown cast ' | ||||||||||||||||||||||||||||||||||||||||||
| 42 | . "'$cast'" | ||||||||||||||||||||||||||||||||||||||||||
| 43 | . ' (known: ' | ||||||||||||||||||||||||||||||||||||||||||
| 44 | . join( ', ', sort keys %ALLOWED_CAST ) | ||||||||||||||||||||||||||||||||||||||||||
| 45 | . ')' ) | ||||||||||||||||||||||||||||||||||||||||||
| 46 | 40 | ▶ | if defined $cast && !$ALLOWED_CAST{$cast}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
defined $cast and not $ALLOWED_CAST{$cast}
MC/DC100%2/2
defined $cast and not $ALLOWED_CAST{$cast}
defined $cast
not $ALLOWED_CAST{$cast}
Truth table100%3/3
A and not(B)
A= defined $castB= not $ALLOWED_CAST{$cast}
| |||||||||||||||||||||||||||||||||||||||||||
| 47 | 39 | ▶ | $cast = $force_cast if defined $force_cast; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 48 | 39 | ▶ | $cast //= ( ref $qv eq 'HASH' ? 'sparsevec' : 'vector' ); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%2/2
$cast //= ref $qv eq "HASH" ? "sparsevec" : "vector"
MC/DC100%1/1
$cast //= ref $qv eq "HASH" ? "sparsevec" : "vector"
$cast
Truth table100%2/2
A
A= $cast
| |||||||||||||||||||||||||||||||||||||||||||
| 49 | 39 | my $sql = sprintf( '(%s %s ?::%s)', $self->{col}, $op, $cast ); | |||||||||||||||||||||||||||||||||||||||||
| 50 | |||||||||||||||||||||||||||||||||||||||||||
| 51 | 39 | return bless { col => $self->{col}, sql => $sql, bind => [$text] }, ref $self; | |||||||||||||||||||||||||||||||||||||||||
| 52 | } | ||||||||||||||||||||||||||||||||||||||||||
| 53 | |||||||||||||||||||||||||||||||||||||||||||
| 54 | 20 | ▶ | sub l2_distance { $_[0]->_distance( '<->', $_[1] ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
l2_distance: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||||||||||||||||
| 56 | |||||||||||||||||||||||||||||||||||||||||||
| 57 | 2 | ▶ | sub max_inner_product { $_[0]->_distance( '<#>', $_[1] ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
max_inner_product: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 58 | |||||||||||||||||||||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||||||||||||||||||||
| 60 | 9 | ▶ | sub cosine_distance { $_[0]->_distance( '<=>', $_[1] ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
cosine_distance: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 61 | |||||||||||||||||||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||||||||||||||||||
| 63 | 3 | ▶ | sub l1_distance { $_[0]->_distance( '<+>', $_[1] ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
l1_distance: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 64 | |||||||||||||||||||||||||||||||||||||||||||
| 65 | |||||||||||||||||||||||||||||||||||||||||||
| 66 | 4 | ▶ | sub hamming_distance { $_[0]->_distance( '<~>', $_[1], 'bit' ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
hamming_distance: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||||||||||||||||
| 68 | |||||||||||||||||||||||||||||||||||||||||||
| 69 | 2 | ▶ | sub jaccard_distance { $_[0]->_distance( '<%>', $_[1], 'bit' ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
jaccard_distance: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||||||||||||||||
| 71 | |||||||||||||||||||||||||||||||||||||||||||
| 72 | # Serializes a query vector into pgvector's text input format. | ||||||||||||||||||||||||||||||||||||||||||
| 73 | # arrayref -> "[0.1,0.2]" | ||||||||||||||||||||||||||||||||||||||||||
| 74 | # hashref (sparsevec) -> "{i:v,...}/dims" | ||||||||||||||||||||||||||||||||||||||||||
| 75 | # plain string -> passed through verbatim | ||||||||||||||||||||||||||||||||||||||||||
| 76 | 40 | ▶ | sub _serialize_query_vector { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_serialize_query_vector: called CC=5 SCAR=16.3
| |||||||||||||||||||||||||||||||||||||||||||
| 77 | 40 | my ( $self, $qv ) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||||||||||||||||
| 79 | 40 | ▶ | if ( ref $qv eq 'ARRAY' ) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 80 | 33 | return '[' . join( ',', @$qv ) . ']'; | |||||||||||||||||||||||||||||||||||||||||
| 81 | } | ||||||||||||||||||||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||||||||||||||||||
| 83 | 7 | ▶ | if ( ref $qv eq 'HASH' ) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 84 | Carp::croak( | ||||||||||||||||||||||||||||||||||||||||||
| 85 | 'sparsevec query vector must be { dims => N, values => { idx => val } }' | ||||||||||||||||||||||||||||||||||||||||||
| 86 | 2 | ▶ | ) unless $qv->{dims} && ref $qv->{values} eq 'HASH'; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$qv->{"dims"} and ref $qv->{"values"} eq "HASH"
MC/DC0%0/2
$qv->{"dims"} and ref $qv->{"values"} eq "HASH"
$qv->{"dims"}
ref $qv->{"values"} eq "HASH"
Truth table33%1/3
A and B
A= $qv->{"dims"}B= ref $qv->{"values"} eq "HASH"
| |||||||||||||||||||||||||||||||||||||||||||
| 87 | |||||||||||||||||||||||||||||||||||||||||||
| 88 | my $body = join( ',', | ||||||||||||||||||||||||||||||||||||||||||
| 89 | 2 | map { "$_:$qv->{values}{$_}" } sort { $a <=> $b } keys %{ $qv->{values} } ); | |||||||||||||||||||||||||||||||||||||||||
| 90 | 2 | return "{$body}/$qv->{dims}"; | |||||||||||||||||||||||||||||||||||||||||
| 91 | } | ||||||||||||||||||||||||||||||||||||||||||
| 92 | |||||||||||||||||||||||||||||||||||||||||||
| 93 | # plain string: caller is responsible for pgvector text syntax | ||||||||||||||||||||||||||||||||||||||||||
| 94 | 5 | return $qv; | |||||||||||||||||||||||||||||||||||||||||
| 95 | } | ||||||||||||||||||||||||||||||||||||||||||
| 96 | |||||||||||||||||||||||||||||||||||||||||||
| 97 | 56 | ▶ | sub _require_distance { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_require_distance: called CC=2 SCAR=7.2
| |||||||||||||||||||||||||||||||||||||||||||
| 98 | 56 | my ($self) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 99 | Carp::croak( | ||||||||||||||||||||||||||||||||||||||||||
| 100 | 'no distance operator selected — call a distance method (l2_distance etc.) first' | ||||||||||||||||||||||||||||||||||||||||||
| 101 | 56 | ▶ | ) unless $self->{sql}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 102 | } | ||||||||||||||||||||||||||||||||||||||||||
| 103 | |||||||||||||||||||||||||||||||||||||||||||
| 104 | 5 | ▶ | sub _op { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_op: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 105 | 5 | my ( $self, $op, $val ) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 106 | 5 | $self->_require_distance; | |||||||||||||||||||||||||||||||||||||||||
| 107 | 5 | return \[ sprintf( '%s %s ?', $self->{sql}, $op ), @{ $self->{bind} }, $val ]; | |||||||||||||||||||||||||||||||||||||||||
| 108 | } | ||||||||||||||||||||||||||||||||||||||||||
| 109 | |||||||||||||||||||||||||||||||||||||||||||
| 110 | 1 | ▶ | sub lt { $_[0]->_op( '<', $_[1] ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
lt: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||||||||||||||||
| 112 | |||||||||||||||||||||||||||||||||||||||||||
| 113 | 2 | ▶ | sub le { $_[0]->_op( '<=', $_[1] ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
le: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||||||||||||||||
| 115 | |||||||||||||||||||||||||||||||||||||||||||
| 116 | 1 | ▶ | sub gt { $_[0]->_op( '>', $_[1] ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
gt: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||||||||||||||||
| 118 | |||||||||||||||||||||||||||||||||||||||||||
| 119 | 1 | ▶ | sub ge { $_[0]->_op( '>=', $_[1] ) } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
ge: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 120 | |||||||||||||||||||||||||||||||||||||||||||
| 121 | |||||||||||||||||||||||||||||||||||||||||||
| 122 | 29 | ▶ | sub as_order { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
as_order: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 123 | 29 | my ($self) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 124 | 29 | $self->_require_distance; | |||||||||||||||||||||||||||||||||||||||||
| 125 | 29 | return \[ $self->{sql}, @{ $self->{bind} } ]; | |||||||||||||||||||||||||||||||||||||||||
| 126 | } | ||||||||||||||||||||||||||||||||||||||||||
| 127 | |||||||||||||||||||||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||||||||||||||||||||
| 129 | 22 | ▶ | sub as_select { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
as_select: called CC=4 SCAR=14.3
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 130 | 22 | my ( $self, $alias ) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 131 | 22 | $self->_require_distance; | |||||||||||||||||||||||||||||||||||||||||
| 132 | 22 | ▶ | DBIO::Exception->throw( | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition50%3/6
defined $alias and not ref $alias and $alias =~ /\A[\w.]+\z/
defined $alias and not ref $alias
MC/DC33%1/3
defined $alias and not ref $alias and $alias =~ /\A[\w.]+\z/
defined $alias
not ref $alias
$alias =~ /\A[\w.]+\z/
Truth table50%2/4
A and not(B) and C
A= defined $aliasB= not ref $aliasC= $alias =~ /\A[\w.]+\z/
| |||||||||||||||||||||||||||||||||||||||||||
| 133 | 'vector: the alias of as_select is a plain identifier (letters, digits, underscores and dots)' | ||||||||||||||||||||||||||||||||||||||||||
| 134 | ) unless defined $alias && !ref $alias && $alias =~ /\A[\w.]+\z/; | ||||||||||||||||||||||||||||||||||||||||||
| 135 | 18 | return \[ sprintf( '%s AS %s',$self->{sql}, $alias ), @{ $self->{bind} } ]; | |||||||||||||||||||||||||||||||||||||||||
| 136 | } | ||||||||||||||||||||||||||||||||||||||||||
| 137 | |||||||||||||||||||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||||||||||||||||||
| 140 | 29 | 1; | |||||||||||||||||||||||||||||||||||||||||
| 141 | |||||||||||||||||||||||||||||||||||||||||||
| 142 | __END__ | ||||||||||||||||||||||||||||||||||||||||||