Skip to main content

graphrt_rag/
filter.rs

1//! Metadata filtering for retrieval.
2
3use serde::{Deserialize, Serialize};
4
5use crate::types::Metadata;
6
7/// How conditions combine.
8#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
9#[serde(rename_all = "lowercase")]
10pub enum Logical {
11    #[default]
12    And,
13    Or,
14}
15
16/// One metadata condition, e.g. `{name: "lang", comparison_operator: "is", value: "en"}`.
17#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
18pub struct MetadataCondition {
19    /// Metadata key; dotted paths descend into nested objects.
20    pub name: String,
21    #[serde(alias = "operator")]
22    pub comparison_operator: String,
23    #[serde(default)]
24    pub value: serde_json::Value,
25}
26
27/// A set of metadata conditions.
28#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
29pub struct MetadataFilter {
30    #[serde(default)]
31    pub logical_operator: Logical,
32    #[serde(default)]
33    pub conditions: Vec<MetadataCondition>,
34}
35
36/// Error for an unsupported comparison operator.
37#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
38#[error("unsupported metadata operator `{0}`")]
39pub struct UnknownOperator(pub String);
40
41impl MetadataFilter {
42    pub fn is_empty(&self) -> bool {
43        self.conditions.is_empty()
44    }
45
46    /// Reject unknown operators up front (at node build / request time).
47    pub fn validate(&self) -> Result<(), UnknownOperator> {
48        for c in &self.conditions {
49            if Op::parse(&c.comparison_operator).is_none() {
50                return Err(UnknownOperator(c.comparison_operator.clone()));
51            }
52        }
53        Ok(())
54    }
55
56    /// Whether `metadata` satisfies the filter. An empty filter matches everything.
57    pub fn matches(&self, metadata: &Metadata) -> bool {
58        if self.conditions.is_empty() {
59            return true;
60        }
61        let mut results = self.conditions.iter().map(|c| condition_matches(c, metadata));
62        match self.logical_operator {
63            Logical::And => results.all(|r| r),
64            Logical::Or => results.any(|r| r),
65        }
66    }
67}
68
69#[derive(Clone, Copy, Debug, PartialEq, Eq)]
70enum Op {
71    Is,
72    IsNot,
73    Contains,
74    NotContains,
75    StartsWith,
76    EndsWith,
77    Empty,
78    NotEmpty,
79    Gt,
80    Lt,
81    Ge,
82    Le,
83    In,
84    NotIn,
85}
86
87impl Op {
88    fn parse(s: &str) -> Option<Op> {
89        Some(match s.trim() {
90            "is" | "=" | "==" | "eq" => Op::Is,
91            "is not" | "≠" | "!=" | "ne" => Op::IsNot,
92            "contains" => Op::Contains,
93            "not contains" => Op::NotContains,
94            "start with" | "starts with" => Op::StartsWith,
95            "end with" | "ends with" => Op::EndsWith,
96            "empty" => Op::Empty,
97            "not empty" => Op::NotEmpty,
98            ">" | "gt" | "after" => Op::Gt,
99            "<" | "lt" | "before" => Op::Lt,
100            "≥" | ">=" | "ge" => Op::Ge,
101            "≤" | "<=" | "le" => Op::Le,
102            "in" => Op::In,
103            "not in" => Op::NotIn,
104            _ => return None,
105        })
106    }
107}
108
109fn lookup<'a>(metadata: &'a Metadata, path: &str) -> Option<&'a serde_json::Value> {
110    let mut parts = path.split('.');
111    let first = parts.next()?;
112    let mut current = metadata.get(first)?;
113    for part in parts {
114        current = current.as_object()?.get(part)?;
115    }
116    Some(current)
117}
118
119fn as_text(v: &serde_json::Value) -> String {
120    match v {
121        serde_json::Value::String(s) => s.clone(),
122        serde_json::Value::Null => String::new(),
123        other => other.to_string(),
124    }
125}
126
127fn as_number(v: &serde_json::Value) -> Option<f64> {
128    match v {
129        serde_json::Value::Number(n) => n.as_f64(),
130        serde_json::Value::String(s) => s.trim().parse().ok(),
131        _ => None,
132    }
133}
134
135fn is_empty(v: Option<&serde_json::Value>) -> bool {
136    match v {
137        None | Some(serde_json::Value::Null) => true,
138        Some(serde_json::Value::String(s)) => s.is_empty(),
139        Some(serde_json::Value::Array(a)) => a.is_empty(),
140        Some(serde_json::Value::Object(o)) => o.is_empty(),
141        Some(_) => false,
142    }
143}
144
145fn equals(actual: &serde_json::Value, expected: &serde_json::Value) -> bool {
146    if let (Some(a), Some(b)) = (as_number(actual), as_number(expected))
147        && (matches!(actual, serde_json::Value::Number(_)) || matches!(expected, serde_json::Value::Number(_)))
148    {
149        return a == b;
150    }
151    as_text(actual) == as_text(expected)
152}
153
154fn contains(actual: &serde_json::Value, expected: &serde_json::Value) -> bool {
155    match actual {
156        serde_json::Value::Array(items) => items.iter().any(|i| equals(i, expected)),
157        other => as_text(other).contains(&as_text(expected)),
158    }
159}
160
161fn member_of(actual: &serde_json::Value, expected: &serde_json::Value) -> bool {
162    match expected {
163        serde_json::Value::Array(options) => options.iter().any(|o| equals(actual, o)),
164        serde_json::Value::String(s) => s.split(',').map(str::trim).any(|o| as_text(actual) == o),
165        other => equals(actual, other),
166    }
167}
168
169fn condition_matches(c: &MetadataCondition, metadata: &Metadata) -> bool {
170    let Some(op) = Op::parse(&c.comparison_operator) else {
171        return false;
172    };
173    let actual = lookup(metadata, &c.name);
174    match op {
175        Op::Empty => return is_empty(actual),
176        Op::NotEmpty => return !is_empty(actual),
177        _ => {}
178    }
179    let Some(actual) = actual else {
180        // A missing key only satisfies the negative operators.
181        return matches!(op, Op::IsNot | Op::NotContains | Op::NotIn);
182    };
183    let expected = &c.value;
184    match op {
185        Op::Is => equals(actual, expected),
186        Op::IsNot => !equals(actual, expected),
187        Op::Contains => contains(actual, expected),
188        Op::NotContains => !contains(actual, expected),
189        Op::StartsWith => as_text(actual).starts_with(&as_text(expected)),
190        Op::EndsWith => as_text(actual).ends_with(&as_text(expected)),
191        Op::In => member_of(actual, expected),
192        Op::NotIn => !member_of(actual, expected),
193        Op::Gt | Op::Lt | Op::Ge | Op::Le => {
194            let ordering = match (as_number(actual), as_number(expected)) {
195                (Some(a), Some(b)) => a.partial_cmp(&b),
196                // Fall back to lexical comparison (works for ISO dates).
197                _ => Some(as_text(actual).cmp(&as_text(expected))),
198            };
199            match (op, ordering) {
200                (Op::Gt, Some(o)) => o.is_gt(),
201                (Op::Lt, Some(o)) => o.is_lt(),
202                (Op::Ge, Some(o)) => o.is_ge(),
203                (Op::Le, Some(o)) => o.is_le(),
204                _ => false,
205            }
206        }
207        Op::Empty | Op::NotEmpty => false,
208    }
209}
210
211#[cfg(test)]
212mod tests {
213    use super::*;
214    use serde_json::json;
215
216    fn meta(v: serde_json::Value) -> Metadata {
217        v.as_object().cloned().unwrap_or_default()
218    }
219
220    fn filter(logical: Logical, conds: &[(&str, &str, serde_json::Value)]) -> MetadataFilter {
221        MetadataFilter {
222            logical_operator: logical,
223            conditions: conds
224                .iter()
225                .map(|(n, o, v)| MetadataCondition {
226                    name: (*n).into(),
227                    comparison_operator: (*o).into(),
228                    value: v.clone(),
229                })
230                .collect(),
231        }
232    }
233
234    #[test]
235    fn operators() {
236        let m = meta(json!({"lang": "en", "year": 2024, "tags": ["a", "b"], "doc": {"kind": "faq"}}));
237        assert!(filter(Logical::And, &[("lang", "is", json!("en"))]).matches(&m));
238        assert!(filter(Logical::And, &[("year", ">", json!("2023"))]).matches(&m));
239        assert!(filter(Logical::And, &[("year", "≤", json!(2024))]).matches(&m));
240        assert!(filter(Logical::And, &[("tags", "contains", json!("b"))]).matches(&m));
241        assert!(filter(Logical::And, &[("doc.kind", "start with", json!("fa"))]).matches(&m));
242        assert!(filter(Logical::And, &[("lang", "in", json!(["de", "en"]))]).matches(&m));
243        assert!(filter(Logical::And, &[("missing", "empty", json!(null))]).matches(&m));
244        assert!(filter(Logical::And, &[("missing", "is not", json!("x"))]).matches(&m));
245        assert!(!filter(Logical::And, &[("missing", "is", json!("x"))]).matches(&m));
246        assert!(!filter(Logical::And, &[("lang", "is", json!("en")), ("year", "<", json!(2000))]).matches(&m));
247        assert!(filter(Logical::Or, &[("lang", "is", json!("en")), ("year", "<", json!(2000))]).matches(&m));
248    }
249
250    #[test]
251    fn validate_rejects_unknown() {
252        assert!(filter(Logical::And, &[("a", "resembles", json!(1))]).validate().is_err());
253        assert!(filter(Logical::And, &[("a", "contains", json!(1))]).validate().is_ok());
254    }
255}