prax-pgvector 0.8.2

pgvector integration for the Prax ORM — vector similarity search, embeddings, and index management
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

//! # prax-pgvector
//!
//! pgvector integration for the Prax ORM — vector similarity search, embeddings,
//! and index management for PostgreSQL.
//!
//! This crate provides type-safe wrappers around [pgvector](https://github.com/pgvector/pgvector)
//! functionality, integrating with the `prax-postgres` driver for seamless vector operations.
//!
//! ## Features
//!
//! - **Vector types**: [`Embedding`], [`SparseEmbedding`], [`BinaryVector`] (and [`HalfEmbedding`]
//!   with the `halfvec` feature)
//! - **Distance metrics**: L2, inner product, cosine, L1, Hamming, Jaccard
//! - **Index management**: IVFFlat and HNSW index creation with tuning parameters
//! - **Query builder**: Fluent API for vector similarity search
//! - **Hybrid search**: Combined vector + full-text search using Reciprocal Rank Fusion
//! - **Filter integration**: Vector filters for prax-query WHERE/ORDER BY clauses
//!
//! ## Quick Start
//!
//! ```rust,ignore
//! use prax_pgvector::prelude::*;
//!
//! // Create an embedding
//! let query = Embedding::new(vec![0.1, 0.2, 0.3, /* ... */]);
//!
//! // Build a similarity search
//! let search = VectorSearchBuilder::new("documents", "embedding")
//!     .query(query)
//!     .metric(DistanceMetric::Cosine)
//!     .limit(10)
//!     .ef_search(200) // Tune HNSW recall
//!     .build();
//!
//! let sql = search.to_sql();
//! // SELECT *, embedding <=> $1 AS distance FROM documents ORDER BY distance LIMIT 10
//! ```
//!
//! ## Index Management
//!
//! ```rust,ignore
//! use prax_pgvector::index::{VectorIndex, HnswConfig};
//! use prax_pgvector::DistanceMetric;
//!
//! // Create an HNSW index
//! let index = VectorIndex::hnsw("idx_doc_embedding", "documents", "embedding")
//!     .metric(DistanceMetric::Cosine)
//!     .config(HnswConfig::high_recall())
//!     .concurrent()
//!     .build()
//!     .unwrap();
//!
//! println!("{}", index.to_create_sql());
//! // CREATE INDEX CONCURRENTLY idx_doc_embedding ON documents
//! //   USING hnsw (embedding vector_cosine_ops)
//! //   WITH (m = 32, ef_construction = 128)
//! ```
//!
//! ## Feature Flags
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `halfvec` | Enable half-precision (float16) vector support |

pub mod error;
pub mod filter;
pub mod index;
pub mod ops;
pub mod query;
pub mod types;

// Re-export primary types at crate root for convenience.
pub use error::{VectorError, VectorResult};
pub use ops::{BinaryDistanceMetric, DistanceMetric};
pub use types::{BinaryVector, Embedding, SparseEmbedding};

#[cfg(feature = "halfvec")]
pub use types::HalfEmbedding;

/// Prelude for convenient imports.
///
/// ```rust,ignore
/// use prax_pgvector::prelude::*;
/// ```
pub mod prelude {
    pub use crate::error::{VectorError, VectorResult};
    pub use crate::filter::{VectorFilter, VectorOrderBy};
    pub use crate::index::{HnswConfig, IvfFlatConfig, VectorIndex};
    pub use crate::ops::{BinaryDistanceMetric, DistanceMetric, SearchParams};
    pub use crate::query::{HybridSearchBuilder, VectorSearchBuilder, VectorSearchQuery};
    pub use crate::types::{BinaryVector, Embedding, SparseEmbedding};

    #[cfg(feature = "halfvec")]
    pub use crate::types::HalfEmbedding;
}