Documentation
¶
Overview ¶
Package vector holds the vector value types.
Index ¶
Examples ¶
Constants ¶
const MaxBits = 83886080
MaxBits is PostgreSQL's limit for the length of a bit string.
const MaxDim = 16000
MaxDim is the storage limit for the dimension of vector and halfvec (pgvector README).
const MaxSparseDim = 1_000_000_000
MaxSparseDim is the largest sparsevec dimension: pgvector accepts up to 1,000,000,000 dimensions, of which at most MaxSparseNNZ are non-zero.
const MaxSparseNNZ = 16000
MaxSparseNNZ is the largest number of stored elements in a sparsevec.
Variables ¶
var ErrDialect = errors.New("momo/vector: type not supported by dialect")
ErrDialect reports a vector type the target dialect cannot store or query.
var ErrInvalidVector = errors.New("momo/vector: invalid vector")
ErrInvalidVector reports a vector value that fails validation, such as a dimension mismatch or a non-finite component. The root package re-exports it as momo.ErrInvalidVector.
Functions ¶
This section is empty.
Types ¶
type Bits ¶
Bits is a pgvector bit string of Len bits, packed most significant bit first into ceil(Len/8) bytes. Unused trailing bits must be zero.
Example ¶
Bits is a bit string packed most significant bit first.
package main
import (
"errors"
"fmt"
"github.com/azrtydxb/momo/vector"
)
func main() {
b := vector.Bits{Len: 4, Data: []byte{0b0101_0000}}
fmt.Println(b.Validate(4))
text, _ := b.Value()
fmt.Println(text)
// A set bit beyond Len is rejected.
dirty := vector.Bits{Len: 4, Data: []byte{0b0101_0001}}
fmt.Println(errors.Is(dirty.Validate(4), vector.ErrInvalidVector))
}
Output: <nil> 0101 true
func (Bits) DialectValue ¶
DialectValue encodes b for dialect d. SQLite gets the packed bytes; its SQL wraps them in vec_bit.
func (*Bits) Scan ¶
Scan accepts a string of 0 and 1, or a packed []byte blob (sqlite-vec), whose Len becomes 8 times its length.
type HalfVector ¶
type HalfVector []float32
HalfVector is a pgvector halfvec; elements must fit in float16.
Example ¶
A HalfVector holds float16 values, so each component must fit in 65504.
package main
import (
"errors"
"fmt"
"github.com/azrtydxb/momo/vector"
)
func main() {
fmt.Println(vector.HalfVector{1, 65504}.Validate(2))
fmt.Println(errors.Is(vector.HalfVector{1, 70000}.Validate(2), vector.ErrInvalidVector))
}
Output: <nil> true
func (HalfVector) DialectValue ¶
func (h HalfVector) DialectValue(d dialect.Name) (any, error)
DialectValue encodes h for dialect d. Any dialect other than PostgreSQL gets an unsupported-dialect error.
func (*HalfVector) Scan ¶
func (h *HalfVector) Scan(src any) error
Scan accepts pgvector text (string) or a []byte float32 blob.
func (HalfVector) Validate ¶
func (h HalfVector) Validate(dim int) error
Validate is Vector.Validate plus the float16 range. Like pgvector, which converts to float16 with round-to-nearest-even, it accepts |x| < 65520 (values in (65504, 65520) round down to 65504) and rejects larger ones.
type SparseVector ¶
SparseVector is a pgvector sparsevec. Indices are 0-based, strictly increasing, and each lies in [0, Dim).
Example ¶
A SparseVector lists zero-based, strictly increasing indices. Its text form is pgvector's {index:value,...}/dimension, with one-based indices.
package main
import (
"errors"
"fmt"
"github.com/azrtydxb/momo/vector"
)
func main() {
s := vector.SparseVector{Dim: 5, Indices: []int32{0, 2}, Values: []float32{1.5, 2}}
fmt.Println(s.Validate(5))
text, _ := s.Value()
fmt.Println(text)
unsorted := vector.SparseVector{Dim: 5, Indices: []int32{2, 0}, Values: []float32{1, 1}}
fmt.Println(errors.Is(unsorted.Validate(5), vector.ErrInvalidVector))
}
Output: <nil> {1:1.5,3:2}/5 true
func (SparseVector) DialectValue ¶
func (s SparseVector) DialectValue(d dialect.Name) (any, error)
DialectValue encodes s for dialect d. Any dialect other than PostgreSQL gets an unsupported-dialect error.
func (*SparseVector) Scan ¶
func (s *SparseVector) Scan(src any) error
Scan accepts pgvector sparsevec text ("{2:1,4:2}/5").
func (SparseVector) Validate ¶
func (s SparseVector) Validate(dim int) error
Validate reports whether s has dimension dim and well-formed entries: 1 <= dim <= MaxSparseDim, at most MaxSparseNNZ entries, indices strictly increasing and inside [0, dim).
type Vector ¶
type Vector []float32
Vector is a pgvector vector (float32 elements).
Example ¶
A Vector is checked against the declared column dimension, and its Value is the pgvector text form.
package main
import (
"errors"
"fmt"
"github.com/azrtydxb/momo/vector"
)
func main() {
v := vector.Vector{1, 2.5, -3}
fmt.Println(v.Validate(3))
text, _ := v.Value()
fmt.Println(text)
err := v.Validate(4)
fmt.Println(errors.Is(err, vector.ErrInvalidVector))
}
Output: <nil> [1,2.5,-3] true
func (Vector) DialectValue ¶
DialectValue encodes v for dialect d. PostgreSQL passes the value through so the driver chooses text or binary; SQLite gets a little-endian float32 blob; MySQL and MariaDB get the text form, which the SQL wraps in STRING_TO_VECTOR or VEC_FromText.
func (*Vector) Scan ¶
Scan accepts pgvector text (string) or a sqlite-vec blob ([]byte).
Example ¶
Scan reads the pgvector text form back.
package main
import (
"fmt"
"github.com/azrtydxb/momo/vector"
)
func main() {
var v vector.Vector
if err := v.Scan("[1,2.5,-3]"); err != nil {
fmt.Println(err)
return
}
fmt.Println(v)
}
Output: [1 2.5 -3]
func (Vector) Validate ¶
Validate reports whether v has exactly dim finite elements and dim is in 1..MaxDim.
Example ¶
NaN and infinite components are rejected, and so is a dimension above MaxDim.
package main
import (
"errors"
"fmt"
"math"
"github.com/azrtydxb/momo/vector"
)
func main() {
nan := float32(math.NaN())
fmt.Println(errors.Is(vector.Vector{1, nan}.Validate(2), vector.ErrInvalidVector))
fmt.Println(vector.MaxDim)
}
Output: true 16000
Source Files