iqdb_types/
search.rs

1//! Parameters for a similarity search.
2
3use crate::filter::Filter;
4use crate::metric::DistanceMetric;
5
6/// The parameters of a nearest-neighbor search.
7///
8/// `k` is how many results to return, `metric` is how distance is measured,
9/// `ef` is an optional search-breadth knob (the candidate-list size some
10/// approximate indexes expose; ignored by exact search), and `filter` is an
11/// optional metadata predicate restricting which records are eligible. Start
12/// from [`SearchParams::new`] and set the optional fields as needed.
13///
14/// # Examples
15///
16/// ```
17/// use iqdb_types::{DistanceMetric, Filter, SearchParams, Value};
18///
19/// let params = SearchParams {
20///     filter: Some(Filter::eq("published", Value::Bool(true))),
21///     ..SearchParams::new(10, DistanceMetric::Cosine)
22/// };
23///
24/// assert_eq!(params.k, 10);
25/// assert_eq!(params.metric, DistanceMetric::Cosine);
26/// assert_eq!(params.ef, None);
27/// assert!(params.filter.is_some());
28/// ```
29#[derive(Debug, Clone, PartialEq)]
30#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
31pub struct SearchParams {
32    /// The number of nearest neighbors to return.
33    pub k: usize,
34    /// Optional search breadth (candidate-list size) for approximate indexes;
35    /// `None` lets the engine choose, and exact search ignores it.
36    pub ef: Option<usize>,
37    /// The distance metric used to rank candidates.
38    pub metric: DistanceMetric,
39    /// Optional metadata predicate restricting which records are eligible.
40    pub filter: Option<Filter>,
41}
42
43impl SearchParams {
44    /// Creates parameters for a top-`k` search under `metric`, with no search
45    /// breadth and no filter.
46    ///
47    /// # Examples
48    ///
49    /// ```
50    /// use iqdb_types::{DistanceMetric, SearchParams};
51    ///
52    /// let params = SearchParams::new(5, DistanceMetric::Euclidean);
53    /// assert_eq!(params.k, 5);
54    /// assert_eq!(params.ef, None);
55    /// assert!(params.filter.is_none());
56    /// ```
57    #[inline]
58    #[must_use]
59    pub fn new(k: usize, metric: DistanceMetric) -> Self {
60        Self {
61            k,
62            ef: None,
63            metric,
64            filter: None,
65        }
66    }
67}
iqdb_types/search.rs

iqdb_types/
search.rs
