lucisearch 0.8.0

Embeddable, in-process search engine — the SQLite/DuckDB of Elasticsearch
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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

use crate::core::{LuciError, Result};

/// Quantization scheme for `dense_vector` fields.
///
/// Configurable via the `dense_vector` field mapping:
/// ```json
/// {"embedding": {"type": "dense_vector", "dims": 768, "quantization": "int8"}}
/// ```
///
/// Recognized but unimplemented variants ([`Self::Int4`], [`Self::Bbq`])
/// are rejected at mapping parse time with [`LuciError::InvalidQuery`].
/// The mapping API will not accept a value the engine cannot honor —
/// see [[code-must-not-lie]].
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum QuantizationType {
    /// No quantization — full float32 storage and scoring.
    None,
    /// Int8 scalar quantization (8 bits/dim). 4× memory reduction with
    /// minimal recall loss in typical embedding workloads.
    Int8,
    /// Int4 scalar quantization (4 bits/dim).
    ///
    /// Recognized name; not yet implemented. Constructing a mapping
    /// with this value returns [`LuciError::InvalidQuery`].
    Int4,
    /// Better Binary Quantization (1 bit/dim with a correction term and
    /// oversampling-rerank).
    ///
    /// Recognized name; not yet implemented. Constructing a mapping
    /// with this value returns [`LuciError::InvalidQuery`].
    Bbq,
}

impl QuantizationType {
    /// The default quantization for `dense_vector` fields when the user
    /// does not specify one.
    pub const DEFAULT: Self = Self::Int8;

    /// Parse a quantization name from the mapping JSON `quantization` field.
    ///
    /// Returns [`LuciError::InvalidQuery`] for both unknown names and
    /// recognized-but-unimplemented values (`int4`, `bbq`). The error
    /// message names the rejected value and the reason — the system
    /// will never silently substitute a different quantization for the
    /// one the user asked for.
    pub fn from_es_name(name: &str) -> Result<Self> {
        match name {
            "none" => Ok(Self::None),
            "int8" => Ok(Self::Int8),
            "int4" => Err(LuciError::InvalidQuery(
                "quantization \"int4\" is recognized but not yet implemented; \
                 supported values: \"none\", \"int8\""
                    .into(),
            )),
            "bbq" => Err(LuciError::InvalidQuery(
                "quantization \"bbq\" is recognized but not yet implemented; \
                 supported values: \"none\", \"int8\""
                    .into(),
            )),
            other => Err(LuciError::InvalidQuery(format!(
                "unknown quantization type: \"{other}\" \
                 (supported: \"none\", \"int8\")"
            ))),
        }
    }

    /// The ES-compatible name used in JSON mappings.
    pub fn es_name(self) -> &'static str {
        match self {
            Self::None => "none",
            Self::Int8 => "int8",
            Self::Int4 => "int4",
            Self::Bbq => "bbq",
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn supported_values_round_trip() {
        for q in [QuantizationType::None, QuantizationType::Int8] {
            let parsed = QuantizationType::from_es_name(q.es_name()).unwrap();
            assert_eq!(parsed, q);
        }
    }

    #[test]
    fn int4_is_rejected_as_unimplemented() {
        let err = QuantizationType::from_es_name("int4").unwrap_err();
        let msg = format!("{err}");
        assert!(msg.contains("int4"), "error must name the value: {msg}");
        assert!(
            msg.contains("not yet implemented"),
            "error must explain why: {msg}"
        );
    }

    #[test]
    fn bbq_is_rejected_as_unimplemented() {
        let err = QuantizationType::from_es_name("bbq").unwrap_err();
        let msg = format!("{err}");
        assert!(msg.contains("bbq"), "error must name the value: {msg}");
        assert!(
            msg.contains("not yet implemented"),
            "error must explain why: {msg}"
        );
    }

    #[test]
    fn unknown_value_is_rejected() {
        let err = QuantizationType::from_es_name("magic").unwrap_err();
        let msg = format!("{err}");
        assert!(msg.contains("magic"), "error must name the value: {msg}");
        assert!(
            msg.contains("supported"),
            "error must list supported values: {msg}"
        );
    }

    #[test]
    fn empty_string_is_rejected() {
        assert!(QuantizationType::from_es_name("").is_err());
    }

    #[test]
    fn default_is_int8() {
        assert_eq!(QuantizationType::DEFAULT, QuantizationType::Int8);
    }
}