iqdb_types/
lib.rs

1//! # iqdb-types
2//!
3//! Shared, dependency-light public types for the HiveDB **iqdb** vector-database
4//! spine. This crate is pure data: the vectors that get indexed, the ids that
5//! name them, the metadata attached to them, the metrics that compare them, the
6//! parameters and filters of a search, the hits it returns, and the one domain
7//! error that ties them together. It holds no engine, no storage, and no I/O —
8//! it is the vocabulary every other `iqdb-*` crate shares so they agree on
9//! shapes without depending on each other.
10//!
11//! Its only runtime dependency is [`error_forge`], whose `ForgeError` trait
12//! [`IqdbError`] implements.
13//!
14//! ## Feature flags
15//!
16//! | Feature | Default | Description |
17//! |---------|---------|-------------|
18//! | `serde` | no | Derives [`Serialize`](https://docs.rs/serde)/[`Deserialize`](https://docs.rs/serde) on the public types. [`VectorRef`] is `Serialize` only — a borrowed view has nowhere to own decoded data. |
19//!
20//! ## Example
21//!
22//! ```
23//! use iqdb_types::{DistanceMetric, Filter, SearchParams, Value, Vector, VectorId};
24//!
25//! // An embedding to index, and an id that names it. `Vector::new`
26//! // validates the contents up front (no empty, no NaN/Inf).
27//! let embedding = Vector::new(vec![0.1, 0.2, 0.3]).unwrap();
28//! let id = VectorId::from(1u64);
29//!
30//! // Query parameters: a top-3 cosine search, restricted to published records.
31//! let params = SearchParams {
32//!     filter: Some(Filter::eq("published", Value::Bool(true))),
33//!     ..SearchParams::new(3, DistanceMetric::Cosine)
34//! };
35//!
36//! assert_eq!(embedding.dim(), 3);
37//! assert_eq!(id, VectorId::U64(1));
38//! assert_eq!(params.k, 3);
39//! ```
40
41#![deny(warnings)]
42#![deny(missing_docs)]
43#![deny(unsafe_op_in_unsafe_fn)]
44#![deny(unused_must_use)]
45#![deny(unused_results)]
46#![deny(clippy::unwrap_used)]
47#![deny(clippy::expect_used)]
48#![deny(clippy::todo)]
49#![deny(clippy::unimplemented)]
50#![deny(clippy::print_stdout)]
51#![deny(clippy::print_stderr)]
52#![deny(clippy::dbg_macro)]
53#![deny(clippy::unreachable)]
54#![deny(clippy::undocumented_unsafe_blocks)]
55
56mod error;
57mod filter;
58mod hit;
59mod id;
60mod metadata;
61mod metric;
62mod search;
63mod vector;
64
65pub use crate::error::{IqdbError, Result};
66pub use crate::filter::Filter;
67pub use crate::hit::Hit;
68pub use crate::id::VectorId;
69pub use crate::metadata::{Metadata, Value};
70pub use crate::metric::DistanceMetric;
71pub use crate::search::SearchParams;
72pub use crate::vector::{Vector, VectorRef};
73
74/// The version of this crate, taken from `Cargo.toml` at compile time.
75///
76/// Exposed so a consumer can report the exact `iqdb-types` build it links
77/// against — useful in diagnostics and version-skew checks across the iqdb
78/// crate family.
79///
80/// # Examples
81///
82/// ```
83/// // Carries a `major.minor.patch` SemVer core.
84/// let version = iqdb_types::VERSION;
85/// assert_eq!(version.split('.').count(), 3);
86/// assert!(version.split('.').all(|part| !part.is_empty()));
87/// ```
88pub const VERSION: &str = env!("CARGO_PKG_VERSION");
iqdb_types/lib.rs

iqdb_types/
lib.rs
