tellaro-query-language 2.0.0

//! Field mapping system for OpenSearch.
//!
//! This module handles field type detection and intelligent query building
//! based on OpenSearch mappings.

use super::error::{OpenSearchError, Result};
use serde_json::Value as JsonValue;
use std::collections::HashMap;

/// Field types in OpenSearch
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FieldType {
    /// Keyword field (exact match)
    Keyword,
    /// Text field (full-text search)
    Text,
    /// Long integer
    Long,
    /// Double precision floating point
    Double,
    /// Boolean
    Boolean,
    /// Date/datetime
    Date,
    /// IP address
    Ip,
    /// Un-analyzed string, optimised for wildcard/regexp matching.
    ///
    /// A real OpenSearch type, and it was in neither engine's type list.
    /// `parse_field_type` returned `None` for it, which drops the field from
    /// `mappings` entirely — so Rust treated a `wildcard`-mapped field as
    /// UNMAPPED, not as unsupported. That is worse than Python's honest
    /// refusal: an unmapped field is passed through untouched, so `f gt 5`
    /// emitted a `range` OpenSearch cannot answer on this type, and `f cidr`
    /// emitted the silent zero-hit `term` that F31 removes everywhere else.
    Wildcard,
    /// Object (nested JSON)
    Object,
    /// Nested (array of objects)
    Nested,
}

/// Field mapping information
#[derive(Debug, Clone)]
pub struct FieldMapping {
    /// The field type
    pub field_type: FieldType,
    /// Subfields (e.g., .keyword for text fields)
    pub subfields: HashMap<String, FieldType>,
}

impl FieldType {
    /// The OpenSearch type name, for error messages that name what the field
    /// actually is.
    pub fn as_str(&self) -> &'static str {
        match self {
            FieldType::Keyword => "keyword",
            FieldType::Text => "text",
            FieldType::Long => "long",
            FieldType::Double => "double",
            FieldType::Boolean => "boolean",
            FieldType::Date => "date",
            FieldType::Ip => "ip",
            FieldType::Wildcard => "wildcard",
            FieldType::Object => "object",
            FieldType::Nested => "nested",
        }
    }

    /// Can OpenSearch answer a `range` query against this type meaningfully?
    ///
    /// `keyword` is deliberately excluded: range on a keyword is lexicographic,
    /// which is a legitimate fallback but not what a caller writing `gt 5`
    /// means. It is reached explicitly, after this returns false.
    pub fn is_orderable(&self) -> bool {
        matches!(self, FieldType::Long | FieldType::Double | FieldType::Date)
    }

    /// Is this an un-analyzed string type — one whole value, one indexed term?
    ///
    /// `keyword` and `wildcard` both are. This is the property that exact-match
    /// and whole-value operators actually need, and it is deliberately NOT the
    /// same question as "can OpenSearch range over it": a `range` on a
    /// `wildcard` field is unimplemented and fails the shard
    /// (`query_shard_exception: failed to create query: TODO`, measured on
    /// OpenSearch 2.19.4), whereas a `range` on a `keyword` is a legitimate
    /// lexicographic fallback. Conflating the two is how `wildcard` support
    /// would turn an honest refusal into a runtime error.
    pub fn is_unanalyzed_string(&self) -> bool {
        matches!(self, FieldType::Keyword | FieldType::Wildcard)
    }
}

/// Collection of field mappings for an index
#[derive(Debug, Clone)]
pub struct FieldMappings {
    mappings: HashMap<String, FieldMapping>,
}

/// Operators whose value is matched against the WHOLE stored string.
///
/// Mirrors `WHOLE_VALUE_OPERATORS` in
/// `src/tql/opensearch_components/field_mapping.py`. The two implementations
/// must agree: the Python package is what the backend and live validation use,
/// and a translator that disagrees with the production engine reports behaviour
/// the product does not have.
const WHOLE_VALUE_OPERATORS: &[&str] = &[
    "contains",
    "contains_cs",
    "not_contains",
    "not_contains_cs",
    "startswith",
    "startswith_cs",
    "not_startswith",
    "not_startswith_cs",
    "endswith",
    "endswith_cs",
    "not_endswith",
    "not_endswith_cs",
    "matches",
    "not_matches",
    "regexp",
    "not_regexp",
    "regex",
    "not_regex",
    // `eq_ci` is emitted as a `wildcard`, so it matches a whole indexed TERM
    // and belongs here. Python added it for that reason and Rust did not
    // follow, so on a text+keyword multifield Python resolved `f eq_ci 'a'`
    // onto `f.keyword` and Rust left it on the analyzed `f` — where a wildcard
    // is matched against the analyzer's tokens. Two files that document each
    // other as mirrors had drifted.
    "eq_ci",
];

/// The case-SENSITIVE whole-value operators.
///
/// These are the ones an ANALYZED field cannot answer at all. A standard
/// analyzer lowercases every token it indexes, so a case-preserving comparison
/// against those tokens is not a hard question -- the information it needs is
/// not in the index. `contains` and its `_ci` siblings are fine there: they ask
/// a case-insensitive question, which lowercased tokens can answer.
///
/// Mirrors `CASE_SENSITIVE_WHOLE_VALUE_OPERATORS` in
/// `src/tql/opensearch_components/field_mapping.py`.
const CASE_SENSITIVE_WHOLE_VALUE_OPERATORS: &[&str] = &[
    "contains_cs",
    "not_contains_cs",
    "startswith_cs",
    "not_startswith_cs",
    "endswith_cs",
    "not_endswith_cs",
];

/// The case-SENSITIVE MEMBERSHIP operators.
///
/// `in_cs` asks exactly the question `contains_cs` asks — does this stored
/// value carry THIS case? — and an analyzed field cannot answer it for exactly
/// the same reason: the analyzer lowercased every token it indexed, so the case
/// being asked about is not in the index.
///
/// They are separate from [`CASE_SENSITIVE_WHOLE_VALUE_OPERATORS`] because they
/// are classified as KEYWORD operators, not whole-value ones. That
/// classification is correct — `in_cs` is an exact-match `terms` query, not a
/// substring one — but it routes them through a different branch of
/// [`FieldMappings::get_query_field`], which is how they escaped the `_cs`
/// refusal and kept returning the silent zero it removed everywhere else.
///
/// Mirrors `CASE_SENSITIVE_MEMBERSHIP_OPERATORS` in
/// `src/tql/opensearch_components/field_mapping.py`.
const CASE_SENSITIVE_MEMBERSHIP_OPERATORS: &[&str] = &["in_cs", "not_in_cs"];

impl FieldMappings {
    /// Create an empty field mappings collection
    pub fn new() -> Self {
        Self {
            mappings: HashMap::new(),
        }
    }

    /// Create from OpenSearch index mappings response
    ///
    /// # Arguments
    ///
    /// * `response` - The JSON response from OpenSearch mappings API
    ///
    /// # Example
    ///
    /// ```ignore
    /// let response = client.indices().get_mapping().send().await?;
    /// let mappings = FieldMappings::from_opensearch_response(response)?;
    /// ```
    pub fn from_opensearch_response(response: JsonValue) -> Result<Self> {
        let mut mappings = HashMap::new();

        // Parse OpenSearch mappings response
        // Expected format:
        // {
        //   "index_name": {
        //     "mappings": {
        //       "properties": {
        //         "field_name": {
        //           "type": "text",
        //           "fields": {
        //             "keyword": { "type": "keyword" }
        //           }
        //         }
        //       }
        //     }
        //   }
        // }

        // Handle different response formats
        let properties = if let Some(index_obj) = response.as_object() {
            // Get the first index (usually there's only one)
            if let Some((_index_name, index_data)) = index_obj.iter().next() {
                if let Some(mappings_obj) = index_data.get("mappings") {
                    mappings_obj.get("properties")
                } else {
                    None
                }
            } else {
                None
            }
        } else {
            None
        };

        if let Some(properties) = properties {
            if let Some(props_obj) = properties.as_object() {
                for (field_name, field_def) in props_obj {
                    if let Some(mapping) = Self::parse_field_definition(field_def) {
                        mappings.insert(field_name.clone(), mapping);
                    }
                }
            }
        }

        Ok(Self { mappings })
    }

    /// Create from pre-extracted properties (e.g., from index template's mappings.properties)
    ///
    /// This is useful when field mappings have already been extracted from an index template
    /// and don't need the full OpenSearch response wrapper.
    ///
    /// # Arguments
    ///
    /// * `properties` - A HashMap of field names to their type definitions
    ///
    /// # Example
    ///
    /// ```ignore
    /// let properties = template.get_tql_field_mappings(Some(&["event.code", "message"]));
    /// let mappings = FieldMappings::from_properties(properties);
    /// ```
    pub fn from_properties(properties: HashMap<String, JsonValue>) -> Self {
        let mut mappings = HashMap::new();

        for (field_name, field_def) in properties {
            if let Some(mapping) = Self::parse_field_definition(&field_def) {
                mappings.insert(field_name, mapping);
            }
        }

        Self { mappings }
    }

    fn parse_field_definition(field_def: &JsonValue) -> Option<FieldMapping> {
        let field_type_str = field_def.get("type")?.as_str()?;
        let field_type = Self::parse_field_type(field_type_str)?;

        let mut subfields = HashMap::new();

        // Parse subfields if they exist
        if let Some(fields) = field_def.get("fields") {
            if let Some(fields_obj) = fields.as_object() {
                for (subfield_name, subfield_def) in fields_obj {
                    if let Some(subfield_type_str) =
                        subfield_def.get("type").and_then(|v| v.as_str())
                    {
                        if let Some(subfield_type) = Self::parse_field_type(subfield_type_str) {
                            subfields.insert(subfield_name.clone(), subfield_type);
                        }
                    }
                }
            }
        }

        Some(FieldMapping {
            field_type,
            subfields,
        })
    }

    fn parse_field_type(type_str: &str) -> Option<FieldType> {
        match type_str {
            "keyword" => Some(FieldType::Keyword),
            "text" => Some(FieldType::Text),
            "long" | "integer" | "short" | "byte" => Some(FieldType::Long),
            "double" | "float" | "half_float" | "scaled_float" => Some(FieldType::Double),
            "boolean" => Some(FieldType::Boolean),
            "date" => Some(FieldType::Date),
            "ip" => Some(FieldType::Ip),
            "wildcard" => Some(FieldType::Wildcard),
            "object" => Some(FieldType::Object),
            "nested" => Some(FieldType::Nested),
            _ => None, // Unknown type
        }
    }

    /// Operators whose value means the WHOLE stored string, so they need an
    /// un-analyzed field. Mirrors Python's `keyword_operators`.
    fn is_keyword_operator(operator: &str) -> bool {
        matches!(
            operator,
            "eq" | "="
                | "ne"
                | "!="
                | "in"
                | "not_in"
                | "exists"
                | "not_exists"
                | "any"
                | "all"
                | "not_any"
                | "not_all"
                // Case-sensitive `in` is exact-match on an un-analyzed field,
                // exactly like `in`. It was in NO operator set, which in Python
                // means `get_field_for_operator` falls through to
                // "Operator '...' is not supported for available field types"
                // and raises — so `f in_cs ['a','b']` translated fine with no
                // mappings and raised the moment mappings were available. Rust
                // leaves an unclassified operator on the base field instead, so
                // the two engines disagreed twice over: on WHICH field, and on
                // whether the query is legal at all.
                | "in_cs"
                | "not_in_cs"
                // The remaining collection operators. `any`/`all`/`not_any`/
                // `not_all` were already here; `none`/`not_none` are the same
                // question and were simply missed.
                | "none"
                | "not_none"
        )
    }

    /// Operators that need a numeric, date, or at minimum un-analyzed field.
    /// Mirrors Python's `range_operators`.
    fn is_range_operator(operator: &str) -> bool {
        matches!(
            operator,
            ">" | ">=" | "<" | "<=" | "gt" | "gte" | "lt" | "lte" | "between" | "not_between"
        )
    }

    /// Name of a subfield of `field` whose type satisfies `pred`, if any.
    fn subfield_of<F>(&self, field: &str, pred: F) -> Option<String>
    where
        F: Fn(&FieldType) -> bool,
    {
        let mapping = self.mappings.get(field)?;
        // Deterministic: a HashMap iteration order would make the emitted query
        // vary between runs for a field carrying two candidate subfields.
        let mut names: Vec<&String> = mapping
            .subfields
            .iter()
            .filter(|(_, ty)| pred(ty))
            .map(|(name, _)| name)
            .collect();
        names.sort();
        names.first().map(|n| format!("{}.{}", field, n))
    }

    /// The field's KEYWORD form: itself when it is already a keyword, else a
    /// `keyword` subfield.
    ///
    /// Deliberately narrow. An earlier revision returned `Some(field)` for any
    /// non-text type, which made `contains` on a `long` and `gt` on an `ip`
    /// resolve happily and emit a query matching nothing — Python raises for
    /// both. "Not analyzed text" is not the same property as "has string
    /// semantics", and conflating them reproduced exactly the silent-zero-hits
    /// behaviour this whole change removes.
    fn keyword_form(&self, field: &str) -> Option<String> {
        let mapping = self.mappings.get(field)?;
        if mapping.field_type == FieldType::Keyword {
            return Some(field.to_string());
        }
        self.subfield_of(field, |t| *t == FieldType::Keyword)
    }

    /// The field's UN-ANALYZED form: `keyword` or `wildcard`, itself or a
    /// subfield. Prefers a true keyword so an existing mapping's emitted DSL
    /// does not change.
    ///
    /// Used by the exact-match and whole-value operator classes, which need
    /// "one whole value, one indexed term" — not "OpenSearch can range over
    /// it". The range arm keeps using `keyword_form`; see
    /// [`FieldType::is_unanalyzed_string`].
    fn unanalyzed_form(&self, field: &str) -> Option<String> {
        if let Some(kw) = self.keyword_form(field) {
            return Some(kw);
        }
        let mapping = self.mappings.get(field)?;
        if mapping.field_type == FieldType::Wildcard {
            return Some(field.to_string());
        }
        self.subfield_of(field, |t| *t == FieldType::Wildcard)
    }

    /// A human-readable inventory of what this field actually offers, for error
    /// messages. Mirrors Python's `available_types`.
    fn available_types(&self, field: &str) -> String {
        let Some(mapping) = self.mappings.get(field) else {
            return "unknown".to_string();
        };
        let mut parts = vec![format!("{}({})", field, mapping.field_type.as_str())];
        let mut subs: Vec<_> = mapping.subfields.iter().collect();
        subs.sort_by_key(|(n, _)| (*n).clone());
        for (name, ty) in subs {
            parts.push(format!("{}.{}({})", field, name, ty.as_str()));
        }
        parts.join(", ")
    }

    /// Resolve the field an operator should actually query, or explain why it
    /// cannot be.
    ///
    /// # Why this returns a Result
    ///
    /// It used to return `String` and always succeed, redirecting to `.keyword`
    /// only for `eq|ne|in|not_in` plus [`WHOLE_VALUE_OPERATORS`] and otherwise
    /// handing back the base field untouched. Measured against the Python
    /// converter across 6 mapping shapes x 14 operators, **42 of 84
    /// combinations disagreed**, in three ways:
    ///
    /// * **Wrong subfield.** `cidr` on a field mapped `text` with an `.ip`
    ///   subfield queried the analyzed text; Python queries `.ip`. Range
    ///   operators queried the analyzed field; Python uses `.keyword`. Both
    ///   return zero hits rather than an error.
    /// * **Silence where Python refuses.** `contains` on a `long`, `gt` on a
    ///   `text` — Python raises `TQLTypeError` / `TQLUnsupportedOperationError`;
    ///   Rust emitted a query that matches nothing. For a query language whose
    ///   purpose is to spare the user from knowing OpenSearch mapping rules,
    ///   silently answering "no results" to an impossible question is the worst
    ///   available behaviour: it is indistinguishable from a quiet network.
    /// * `cidr` had no translation arm at all (tql#198).
    ///
    /// Rust is the production engine — it is what the agent's detection engine
    /// runs — so the divergence meant shipped detection content behaved
    /// differently from everything validated against the Python package.
    ///
    /// The resolution order mirrors
    /// `src/tql/opensearch_components/field_mapping.py::get_field_for_operator`
    /// class for class. Keep them in lockstep; `cross_language_dsl_parity`
    /// fails if they drift.
    pub fn get_query_field(&self, field: &str, operator: &str) -> Result<String> {
        // Unmapped field: nothing to reason about, and refusing would break
        // every query against an index whose mappings we could not fetch.
        // Python behaves the same way (it only consults mappings it has).
        let Some(mapping) = self.mappings.get(field) else {
            return Ok(field.to_string());
        };

        // "Does this document have this field at all" is a question about the
        // field, not any subfield. A `.keyword` subfield carries `ignore_above`
        // (256 by default), so `exists` against it is silently false for longer
        // values; an analyzed subfield is absent when analysis produced no
        // tokens. Both answer "no such field" for a document that plainly has
        // one. Matches Python.
        // `is` / `is_not` are existence questions too (audit finding F30).
        //
        // `is` used to be classified as a keyword operator and resolved to the
        // `.keyword` form, so on a text+keyword multifield `f is null` asked
        // about `f.keyword` while `f is not null` asked about `f`. A value
        // longer than `ignore_above` (256 by default) is indexed into `f` and
        // NOT into `f.keyword`, so a 300-character document came back from BOTH
        // — it read as null and as not-null at once. Measured against a live
        // cluster rather than predicted, and fixed on both sides together
        // because both engines classified it the same way.
        if matches!(operator, "exists" | "not_exists" | "is" | "is_not") {
            return Ok(field.to_string());
        }

        if Self::is_keyword_operator(operator) {
            // Un-analyzed first; an analyzed field is better than failing.
            if let Some(unanalyzed) = self.unanalyzed_form(field) {
                return Ok(unanalyzed);
            }
            // No un-analyzed form and a case-SENSITIVE membership operator
            // against an ANALYZED text field: the field cannot answer at all,
            // exactly as for `contains_cs` and its siblings. The analyzer
            // lowercased every token it indexed, so the case `in_cs` asks about
            // is not in the index — falling back to the analyzed field emits a
            // `terms` clause that can never match a mixed-case value and
            // returns zero hits with no error.
            //
            // Measured live on OpenSearch 2.19.4, an analyzed `text` field
            // holding "A MiXeD Value":
            //
            //     terms ["MiXeD"]            -> 0 hits
            //     terms ["mixed"]  (control) -> 1 hit
            //     must_not(terms ["MiXeD"])  -> 1 hit  (excludes NOTHING)
            //
            // The control is what makes this a measurement rather than an
            // assumption: the token IS there, lowercased, so the miss is about
            // case and not about the field or an empty index. The negated
            // direction is the dangerous one — `not_in_cs` becomes a match-all.
            //
            // Gated on the BASE field being `text` rather than on "no
            // un-analyzed form" alone. A `long`, `date` or `ip` field also has
            // no un-analyzed string form, but it answers `in_cs` perfectly
            // well: case-sensitivity is vacuous for a number. Only an analyzed
            // string field is UNANSWERABLE.
            if CASE_SENSITIVE_MEMBERSHIP_OPERATORS.contains(&operator)
                && mapping.field_type == FieldType::Text
            {
                return Err(OpenSearchError::TypeError {
                    field: field.to_string(),
                    field_type: mapping.field_type.as_str().to_string(),
                    operator: operator.to_string(),
                    suggestion: format!(
                        " '{field}' is analyzed and has no case-preserving form, \
                         so the case this operator asks about is not in the index \
                         -- the analyzer lowercased it. Add a `.keyword` subfield \
                         to '{field}', or use the case-insensitive '{ci}'.",
                        field = field,
                        ci = operator.trim_end_matches("_cs"),
                    ),
                });
            }
            return Ok(field.to_string());
        }

        if WHOLE_VALUE_OPERATORS.contains(&operator) {
            // `wildcard`, `prefix` and `regexp` match a single indexed TERM. On
            // an analyzed field the terms are the analyzer's tokens, so a
            // pattern spanning a token boundary can never match:
            // `email contains '@example.com'` searched ["alice", "example.com"]
            // for `*@example.com*` and found nothing (tql#169).
            if let Some(unanalyzed) = self.unanalyzed_form(field) {
                return Ok(unanalyzed);
            }
            // No un-analyzed form. For a case-SENSITIVE operator that is not
            // "imperfect", it is UNANSWERABLE: the analyzer lowercased every
            // token it indexed, so the case the query asks about is not in the
            // index at all. Falling back to the analyzed field there produces a
            // query that can never match a mixed-case value and returns zero
            // hits with no error -- indistinguishable from "nothing matched",
            // which is the exact confusion TQL exists to remove.
            //
            // Same shape as F31 (`cidr` against a keyword field, where `term`
            // compares the CIDR string literally), and resolved the same way:
            // refuse, and say what would fix it. The operator is not at fault
            // and neither is the value -- the FIELD cannot answer, and only the
            // mapping owner can change that.
            //
            // Only the `_cs` operators refuse. `contains` / `startswith` /
            // `endswith` and `eq_ci` ask case-INSENSITIVE questions, which
            // lowercased tokens answer perfectly well, and `matches` carries its
            // own case handling. Those keep the analyzed-field fallback, where
            // imperfect really does beat impossible.
            if CASE_SENSITIVE_WHOLE_VALUE_OPERATORS.contains(&operator) {
                return Err(OpenSearchError::TypeError {
                    field: field.to_string(),
                    field_type: mapping.field_type.as_str().to_string(),
                    operator: operator.to_string(),
                    suggestion: format!(
                        " '{field}' is analyzed and has no case-preserving form, \
                         so the case this operator asks about is not in the index \
                         -- the analyzer lowercased it. Add a `.keyword` subfield \
                         to '{field}', or use the case-insensitive '{ci}'.",
                        field = field,
                        ci = operator.trim_end_matches("_cs"),
                    ),
                });
            }
            // Text-only: Python falls back to the analyzed field rather than
            // failing, and so do we. Imperfect beats impossible.
            if mapping.field_type == FieldType::Text {
                return Ok(field.to_string());
            }
            // Numeric/date/boolean have no string semantics at all.
            return Err(OpenSearchError::UnsupportedOperation {
                operator: operator.to_string(),
                available_types: self.available_types(field),
            });
        }

        if Self::is_range_operator(operator) {
            if mapping.field_type.is_orderable() {
                return Ok(field.to_string());
            }
            if let Some(sub) = self.subfield_of(field, FieldType::is_orderable) {
                return Ok(sub);
            }
            // OpenSearch does support range on keyword (lexicographic).
            if let Some(keyword) = self.keyword_form(field) {
                return Ok(keyword);
            }
            // Python raises TQLTypeError only when the field has TEXT forms to
            // complain about (`if self.text_fields:`); every other unusable
            // shape reaches its catch-all TQLUnsupportedOperationError. Mirror
            // that split exactly — the two exception types are part of the
            // contract callers match on.
            if mapping.field_type == FieldType::Text {
                return Err(OpenSearchError::TypeError {
                    field: field.to_string(),
                    field_type: mapping.field_type.as_str().to_string(),
                    operator: operator.to_string(),
                    suggestion:
                        " Range operators need a numeric, date, or keyword field; this field is analyzed text."
                            .to_string(),
                });
            }
            return Err(OpenSearchError::UnsupportedOperation {
                operator: operator.to_string(),
                available_types: self.available_types(field),
            });
        }

        if matches!(operator, "cidr" | "not_cidr") {
            // An `ip`-typed field is the only one that matches CIDR notation
            // natively. Prefer it, including as a subfield.
            if mapping.field_type == FieldType::Ip {
                return Ok(field.to_string());
            }
            if let Some(sub) = self.subfield_of(field, |t| *t == FieldType::Ip) {
                return Ok(sub);
            }
            // NO KEYWORD FALLBACK. Both engines used to fall back to the
            // field's keyword form here, "because that is what the reference
            // implementation does" — and the reference implementation was
            // wrong. `term` accepts CIDR notation ONLY on an `ip` field, where
            // OpenSearch expands the prefix; on a `keyword` it is a literal
            // string comparison against the stored address, so
            // `kwip cidr '10.0.0.0/8'` asks whether the field holds the eight
            // characters "10.0.0.0/8". Measured on OpenSearch 2.19.4 against a
            // document holding 10.1.2.3 in both an `ip` and a `keyword` field:
            //
            //   term realip = "10.0.0.0/8"  -> 1 hit   (ip: CIDR expanded)
            //   term kwip   = "10.0.0.0/8"  -> 0 hits  (keyword: literal)
            //   term kwip   = "10.1.2.3"    -> 1 hit   (control)
            //
            // Zero hits and no error is the worst answer available: a detection
            // rule that can never fire is indistinguishable from a rule for an
            // event that never happened. Refusing is loud, and the caller can
            // then map the field as `ip` or add an `ip` subfield — which is the
            // only thing that would have made the query mean what they wrote.
            //
            // An UNMAPPED field is deliberately still allowed through above:
            // with no mappings we cannot tell an `ip` field from a `keyword`
            // one, and refusing would break every query against an index whose
            // mappings could not be fetched.
            //
            // Python's two cidr spellings do not agree with each other: the
            // positive form surfaces TQLTypeError while `not cidr` reaches the
            // catch-all TQLUnsupportedOperationError, on the SAME field. That
            // asymmetry looks like a Python defect rather than a design, but it
            // is observable behaviour that callers may match on, so it is
            // mirrored rather than quietly corrected here. Filed separately;
            // when Python is fixed, this branch collapses to one arm.
            if operator == "cidr" {
                return Err(OpenSearchError::TypeError {
                    field: field.to_string(),
                    field_type: mapping.field_type.as_str().to_string(),
                    operator: operator.to_string(),
                    suggestion: " CIDR matching needs an ip field or an ip subfield; a keyword holding an address is compared literally and can never match a prefix.".to_string(),
                });
            }
            return Err(OpenSearchError::UnsupportedOperation {
                operator: operator.to_string(),
                available_types: self.available_types(field),
            });
        }

        // Unclassified operator: behave as before rather than refusing, so a
        // new operator does not become an outage. `opensearch_operator_
        // translation_coverage` is what stops one arriving unnoticed.
        Ok(field.to_string())
    }

    /// Determine if a field should use term query vs match query
    ///
    /// # Arguments
    ///
    /// * `field` - The field name
    ///
    /// # Returns
    ///
    /// `true` if term query should be used (exact match), `false` for match query
    pub fn should_use_term_query(&self, field: &str) -> bool {
        if let Some(mapping) = self.mappings.get(field) {
            matches!(
                mapping.field_type,
                FieldType::Keyword
                    | FieldType::Long
                    | FieldType::Double
                    | FieldType::Boolean
                    | FieldType::Date
                    | FieldType::Ip
                    | FieldType::Wildcard
            )
        } else {
            // Default to term query if we don't know the type
            true
        }
    }

    /// Get the field type for a given field
    pub fn get_field_type(&self, field: &str) -> Option<&FieldType> {
        self.mappings.get(field).map(|m| &m.field_type)
    }

    /// The type of a RESOLVED field path, which may name a subfield.
    ///
    /// `get_field_type` only sees top-level keys, because subfields live inside
    /// their parent's `FieldMapping` rather than as map entries of their own.
    /// So `get_field_type("f.keyword")` is `None` for every multifield in
    /// existence — and a caller that reads that `None` as "unknown, fall back"
    /// gets the base field's type instead of the type it is about to query.
    ///
    /// That is a live defect, not a hypothetical: `supports_case_insensitive_term`
    /// stripped `.keyword` and typed the BASE, so on an `ip` field with a
    /// `keyword` subfield it concluded "ip, no case-insensitivity" while the
    /// query it was building targeted `f.keyword`. `in` is contractually
    /// case-insensitive, so `role in ['ADMIN']` silently missed `admin` on
    /// exactly that mapping shape. Measured live: `term role='ADMIN'` returns
    /// 0 hits case-sensitively and 1 case-insensitively, and `case_insensitive`
    /// is accepted on the `.keyword` subfield of an `ip` field.
    ///
    /// Absence stays absence: an unknown path returns `None` rather than
    /// defaulting to the parent, so callers must decide what to do about not
    /// knowing instead of being handed a plausible wrong answer.
    pub fn resolved_field_type(&self, path: &str) -> Option<&FieldType> {
        if let Some(mapping) = self.mappings.get(path) {
            return Some(&mapping.field_type);
        }
        let (base, sub) = path.rsplit_once('.')?;
        self.mappings.get(base)?.subfields.get(sub)
    }

    /// Add a field mapping
    pub fn add_mapping(&mut self, field: String, mapping: FieldMapping) {
        self.mappings.insert(field, mapping);
    }

    /// Get the number of field mappings
    pub fn len(&self) -> usize {
        self.mappings.len()
    }

    /// Check if there are no field mappings
    pub fn is_empty(&self) -> bool {
        self.mappings.is_empty()
    }
}

impl Default for FieldMappings {
    fn default() -> Self {
        Self::new()
    }
}

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

    #[test]
    fn test_empty_mappings() {
        let mappings = FieldMappings::new();
        assert_eq!(mappings.get_query_field("test", "eq").unwrap(), "test");
        assert!(mappings.should_use_term_query("test"));
    }

    #[test]
    fn test_text_field_with_keyword() {
        let mut mappings = FieldMappings::new();
        let mut subfields = HashMap::new();
        subfields.insert("keyword".to_string(), FieldType::Keyword);

        mappings.add_mapping(
            "message".to_string(),
            FieldMapping {
                field_type: FieldType::Text,
                subfields,
            },
        );

        // For eq operator, should use .keyword subfield
        assert_eq!(
            mappings.get_query_field("message", "eq").unwrap(),
            "message.keyword"
        );
        // A substring operator also needs the un-analyzed field: a wildcard on
        // the analyzed base matches per token, so anything spanning two tokens
        // is unmatchable. This assertion used to read "message" and pinned the
        // bug (tql#169).
        assert_eq!(
            mappings.get_query_field("message", "contains").unwrap(),
            "message.keyword"
        );
        assert_eq!(
            mappings.get_query_field("message", "matches").unwrap(),
            "message.keyword"
        );
    }

    #[test]
    fn test_keyword_field() {
        let mut mappings = FieldMappings::new();
        mappings.add_mapping(
            "status".to_string(),
            FieldMapping {
                field_type: FieldType::Keyword,
                subfields: HashMap::new(),
            },
        );

        assert_eq!(mappings.get_query_field("status", "eq").unwrap(), "status");
        assert!(mappings.should_use_term_query("status"));
    }
}