prax_pgvector/
lib.rs

1//! # prax-pgvector
2//!
3//! pgvector integration for the Prax ORM — vector similarity search, embeddings,
4//! and index management for PostgreSQL.
5//!
6//! This crate provides type-safe wrappers around [pgvector](https://github.com/pgvector/pgvector)
7//! functionality, integrating with the `prax-postgres` driver for seamless vector operations.
8//!
9//! ## Features
10//!
11//! - **Vector types**: [`Embedding`], [`SparseEmbedding`], [`BinaryVector`] (and [`HalfEmbedding`]
12//!   with the `halfvec` feature)
13//! - **Distance metrics**: L2, inner product, cosine, L1, Hamming, Jaccard
14//! - **Index management**: IVFFlat and HNSW index creation with tuning parameters
15//! - **Query builder**: Fluent API for vector similarity search
16//! - **Hybrid search**: Combined vector + full-text search using Reciprocal Rank Fusion
17//! - **Filter integration**: Vector filters for prax-query WHERE/ORDER BY clauses
18//!
19//! ## Quick Start
20//!
21//! ```rust,ignore
22//! use prax_pgvector::prelude::*;
23//!
24//! // Create an embedding
25//! let query = Embedding::new(vec![0.1, 0.2, 0.3, /* ... */]);
26//!
27//! // Build a similarity search
28//! let search = VectorSearchBuilder::new("documents", "embedding")
29//!     .query(query)
30//!     .metric(DistanceMetric::Cosine)
31//!     .limit(10)
32//!     .ef_search(200) // Tune HNSW recall
33//!     .build();
34//!
35//! let sql = search.to_sql();
36//! // SELECT *, embedding <=> $1 AS distance FROM documents ORDER BY distance LIMIT 10
37//! ```
38//!
39//! ## Index Management
40//!
41//! ```rust,ignore
42//! use prax_pgvector::index::{VectorIndex, HnswConfig};
43//! use prax_pgvector::DistanceMetric;
44//!
45//! // Create an HNSW index
46//! let index = VectorIndex::hnsw("idx_doc_embedding", "documents", "embedding")
47//!     .metric(DistanceMetric::Cosine)
48//!     .config(HnswConfig::high_recall())
49//!     .concurrent()
50//!     .build()
51//!     .unwrap();
52//!
53//! println!("{}", index.to_create_sql());
54//! // CREATE INDEX CONCURRENTLY idx_doc_embedding ON documents
55//! //   USING hnsw (embedding vector_cosine_ops)
56//! //   WITH (m = 32, ef_construction = 128)
57//! ```
58//!
59//! ## Feature Flags
60//!
61//! | Feature | Description |
62//! |---------|-------------|
63//! | `halfvec` | Enable half-precision (float16) vector support |
64
65pub mod error;
66pub mod filter;
67pub mod index;
68pub mod ops;
69pub mod query;
70pub mod types;
71
72// Re-export primary types at crate root for convenience.
73pub use error::{VectorError, VectorResult};
74pub use ops::{BinaryDistanceMetric, DistanceMetric};
75pub use types::{BinaryVector, Embedding, SparseEmbedding};
76
77#[cfg(feature = "halfvec")]
78pub use types::HalfEmbedding;
79
80/// Prelude for convenient imports.
81///
82/// ```rust,ignore
83/// use prax_pgvector::prelude::*;
84/// ```
85pub mod prelude {
86    pub use crate::error::{VectorError, VectorResult};
87    pub use crate::filter::{VectorFilter, VectorOrderBy};
88    pub use crate::index::{HnswConfig, IvfFlatConfig, VectorIndex};
89    pub use crate::ops::{BinaryDistanceMetric, DistanceMetric, SearchParams};
90    pub use crate::query::{HybridSearchBuilder, VectorSearchBuilder, VectorSearchQuery};
91    pub use crate::types::{BinaryVector, Embedding, SparseEmbedding};
92
93    #[cfg(feature = "halfvec")]
94    pub use crate::types::HalfEmbedding;
95}
prax_pgvector/lib.rs

prax_pgvector/
lib.rs
