feat(query): implement fuzzy_match filter operator

Author: ichhitkarwa-ui

config/schemas/graph_query.schema.json

@@ -454,11 +454,11 @@
       "properties": {
         "op": {
           "type": "string",
-          "description": "Filter operator. Comparison: eq, gt, lt, gte, lte. Set membership: in (array value). Substring matching: contains, starts_with, ends_with. Nullability: is_null, is_not_null (no value). Word matching: token_match (exact word match), all_tokens (all words present), any_tokens (any word present) — only on fields that support word matching.",
-          "enum": ["eq", "gt", "lt", "gte", "lte", "in", "contains", "starts_with", "ends_with", "is_null", "is_not_null", "token_match", "all_tokens", "any_tokens"]
+          "description": "Filter operator. Comparison: eq, gt, lt, gte, lte. Set membership: in (array value). Substring matching: contains, starts_with, ends_with. Nullability: is_null, is_not_null (no value). Word matching: token_match (exact word match), all_tokens (all words present), any_tokens (any word present) — only on fields that support word matching. Fuzzy matching: fuzzy_match (case-insensitive fuzzy match) — only on string fields.",
+          "enum": ["eq", "gt", "lt", "gte", "lte", "in", "contains", "starts_with", "ends_with", "is_null", "is_not_null", "token_match", "all_tokens", "any_tokens", "fuzzy_match"]
         },
         "value": {
-          "description": "Filter value. Required for all operators except is_null/is_not_null. Type: array for 'in', string for contains/starts_with/ends_with/token_match/all_tokens/any_tokens, scalar for comparison operators."
+          "description": "Filter value. Required for all operators except is_null/is_not_null. Type: array for 'in', string for contains/starts_with/ends_with/token_match/all_tokens/any_tokens/fuzzy_match, scalar for comparison operators."
         }
       },
       "additionalProperties": false,
@@ -488,6 +488,10 @@
         {
           "if": { "properties": { "op": { "enum": ["token_match", "all_tokens", "any_tokens"] } } },
           "then": { "required": ["value"], "properties": { "value": { "type": "string", "maxLength": 1024 } } }
+        },
+        {
+          "if": { "properties": { "op": { "const": "fuzzy_match" } } },
+          "then": { "required": ["value"], "properties": { "value": { "type": "string", "maxLength": 1024 } } }
         }
       ]
     },

crates/query-engine/compiler/src/input.rs

@@ -510,6 +510,8 @@ pub enum FilterOp {
     AllTokens,
     /// Any token present via `hasAnyTokens()`. Requires a text index on the column.
     AnyTokens,
+    /// Fuzzy string matching via ClickHouse `ngramDistanceCaseInsensitive`.
+    FuzzyMatch,
 }
 
 fn deserialize_filters<'de, D>(

crates/query-engine/compiler/src/passes/codegen/clickhouse.rs

@@ -1041,4 +1041,41 @@ mod tests {
 
         assert_eq!(pq.render(), "SELECT {p0:String} AND {p1:Int64}");
     }
+
+    #[test]
+    fn fuzzy_match_operator() {
+        use crate::input::{FilterOp, InputFilter};
+        use crate::passes::shared::filter_to_expr;
+
+        let filter = InputFilter {
+            op: Some(FilterOp::FuzzyMatch),
+            value: Some(Value::from("antigravity")),
+            data_type: Some(ontology::DataType::String),
+            ..Default::default()
+        };
+        let expr = filter_to_expr("n", "name", &filter);
+        let q = Query {
+            select: vec![SelectExpr {
+                expr: Expr::col("n", "id"),
+                alias: None,
+            }],
+            from: TableRef::scan("nodes", "n"),
+            where_clause: Some(expr),
+            ..Default::default()
+        };
+
+        let result = codegen(&Node::Query(Box::new(q)), empty_ctx(), QueryConfig::empty()).unwrap();
+        assert_eq!(
+            result.sql,
+            "SELECT n.id FROM nodes AS n WHERE (ngramDistanceCaseInsensitive(n.name, {p0:String}) < {p1:Float64})"
+        );
+        assert_eq!(
+            result.params.get("p0").map(|p| &p.value),
+            Some(&Value::from("antigravity"))
+        );
+        assert_eq!(
+            result.params.get("p1").map(|p| &p.value),
+            Some(&Value::from(0.3))
+        );
+    }
 }

crates/query-engine/compiler/src/passes/shared.rs

@@ -65,6 +65,14 @@ pub fn filter_to_expr(alias: &str, prop: &str, filter: &InputFilter) -> Expr {
             "hasAnyTokens",
             vec![col, Expr::param(ChType::String, str_val())],
         ),
+        Some(FilterOp::FuzzyMatch) => Expr::binary(
+            Op::Lt,
+            Expr::func(
+                "ngramDistanceCaseInsensitive",
+                vec![col, Expr::param(ChType::String, str_val())],
+            ),
+            Expr::param(ChType::Float64, serde_json::Value::from(0.3)),
+        ),
     }
 }
 

crates/query-engine/compiler/src/passes/validate.rs

@@ -534,14 +534,20 @@ impl<'a> Validator<'a> {
     ) -> Result<()> {
         let op = filter.op.unwrap_or(FilterOp::Eq);
 
+        if op == FilterOp::FuzzyMatch && data_type != DataType::String {
+            return Err(QueryError::Validation(format!(
+                "filter on \"{prop}\" for {entity}: fuzzy_match requires a string field, got {data_type}"
+            )));
+        }
+
         // Ops without a value — nothing to type-check.
         if matches!(op, FilterOp::IsNull | FilterOp::IsNotNull) {
             return Ok(());
         }
 
         let is_like_op = matches!(
             op,
-            FilterOp::Contains | FilterOp::StartsWith | FilterOp::EndsWith
+            FilterOp::Contains | FilterOp::StartsWith | FilterOp::EndsWith | FilterOp::FuzzyMatch
         );
 
         let is_token_op = matches!(
@@ -2507,6 +2513,71 @@ mod tests {
         );
     }
 
+    #[test]
+    fn rejects_fuzzy_match_on_disallowed_field() {
+        let ont = ontology_with_sensitive_field();
+        let validator = Validator::new(&ont);
+        let input = parse_input(
+            r#"{
+            "query_type": "traversal",
+            "node": {"id": "u", "entity": "User",
+                     "filters": {"email": {"op": "fuzzy_match", "value": "example"}}},
+            "limit": 10
+        }"#,
+        )
+        .unwrap();
+
+        let err = validator.check_references(&input).unwrap_err();
+        assert!(
+            err.to_string().contains("LIKE operators"),
+            "expected like_allowed rejection, got: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_short_fuzzy_match_pattern() {
+        let ont = test_ontology();
+        let validator = Validator::new(&ont);
+        let input = parse_input(
+            r#"{
+            "query_type": "traversal",
+            "node": {"id": "u", "entity": "User",
+                     "filters": {"username": {"op": "fuzzy_match", "value": "ab"}}},
+            "limit": 10
+        }"#,
+        )
+        .unwrap();
+
+        let err = validator.check_references(&input).unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("search pattern must be at least 3 characters"),
+            "expected min length error, got: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_fuzzy_match_on_non_string_field() {
+        let ont = test_ontology();
+        let validator = Validator::new(&ont);
+        let input = parse_input(
+            r#"{
+            "query_type": "traversal",
+            "node": {"id": "u", "entity": "User",
+                     "filters": {"created_at": {"op": "fuzzy_match", "value": "2024-01-01"}}},
+            "limit": 10
+        }"#,
+        )
+        .unwrap();
+
+        let err = validator.check_references(&input).unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("fuzzy_match requires a string field"),
+            "expected non-string field rejection, got: {err}"
+        );
+    }
+
     #[test]
     fn rejects_filter_on_unfilterable_field() {
         let ont = ontology_with_unfilterable_field();