ringdb/
query.rs

1use std::time::Duration;
2
3/// A ring query: find all vectors whose Euclidean distance to `query`
4/// lies within `[d - lambda, d + lambda]`.
5///
6/// Internally, ringdb uses squared L2 distances to avoid computing square
7/// roots. The ring bounds become:
8///
9/// ```text
10/// lower_sq = max(0, d - lambda)²
11/// upper_sq = (d + lambda)²
12/// ```
13pub struct RingQuery<'a> {
14    /// The query vector. Must have length equal to `RingDb::dims()`.
15    pub query: &'a [f32],
16    /// Target distance (centre of the ring).
17    pub d: f32,
18    /// Half-width of the ring.
19    pub lambda: f32,
20}
21
22/// A range query: find all vectors whose Euclidean distance to `query`
23/// lies within `[d_min, d_max]`.
24pub struct RangeQuery<'a> {
25    /// The query vector. Must have length equal to `RingDb::dims()`.
26    pub query: &'a [f32],
27    /// Lower bound of the distance interval (inclusive). Must be ≥ 0.
28    pub d_min: f32,
29    /// Upper bound of the distance interval (inclusive). Must be ≥ `d_min`.
30    pub d_max: f32,
31}
32
33/// A disk query: find all vectors whose Euclidean distance to `query`
34/// is at most `d_max` (i.e. the full disk/ball of radius `d_max`).
35///
36/// This is equivalent to a [`RangeQuery`] with `d_min = 0`.
37pub struct DiskQuery<'a> {
38    /// The query vector. Must have length equal to `RingDb::dims()`.
39    pub query: &'a [f32],
40    /// Radius of the disk (inclusive upper bound on distance). Must be ≥ 0.
41    pub d_max: f32,
42}
43
44/// Result of a ring query.
45pub struct QueryResult {
46    /// IDs of all vectors whose distance to the query falls within
47    /// `[d - lambda, d + lambda]`. IDs correspond to insertion order
48    /// (first inserted vector has ID 0).
49    pub ids: Vec<u32>,
50    /// Name of the backend that executed the query (e.g. `"cpu"`, `"wgpu"`, `"cuda"`).
51    pub backend_used: &'static str,
52    /// Wall-clock time for the query (excluding dataset upload).
53    pub elapsed: Duration,
54}
ringdb/query.rs

ringdb/
query.rs
