tellaro_query_language/

lib.rs

//! # TQL - Tellaro Query Language
//!
//! A flexible, human-friendly query language for searching and filtering structured data.
//!
//! TQL provides an intuitive syntax similar to SQL WHERE clauses, with support for:
//! - Nested field access (`user.profile.name`)
//! - Rich set of operators (comparison, logical, collection)
//! - Field transformations via mutators (`field | lowercase`)
//! - Statistical aggregations (`| stats count() by field`)
//! - OpenSearch backend integration
//! - GeoIP lookups (MaxMind and DB-IP)
//!
//! ## Quick Start
//!
//! ```ignore
//! use tql::{Tql, TqlConfig};
//! use serde_json::json;
//!
//! let tql = Tql::new(TqlConfig::default());
//! let records = vec![
//!     json!({"name": "John", "age": 30}),
//!     json!({"name": "Jane", "age": 25}),
//! ];
//!
//! let results = tql.query(&records, "age > 25").unwrap();
//! assert_eq!(results.len(), 1);
//! ```
//!
//! ## Feature Parity
//!
//! This Rust implementation maintains 100% feature parity with the Python version,
//! providing identical syntax, behavior, and capabilities.

pub mod error;
pub mod parser;
pub mod field_accessor;
pub mod comparator;
pub mod evaluator;
pub mod mutators;
pub mod stats_evaluator;

// OpenSearch backend support (optional feature)
#[cfg(feature = "opensearch")]
pub mod opensearch;

// Re-export main types
pub use error::{Result, TqlError};
pub use parser::{AstNode, TqlParser};
pub use evaluator::TqlEvaluator;
pub use stats_evaluator::{StatsEvaluator, StatsQuery, AggregationSpec};

use serde_json::Value as JsonValue;

/// Main TQL query interface
///
/// Provides a high-level API for parsing and executing TQL queries against JSON data.
///
/// # Examples
///
/// ```
/// use tql::Tql;
/// use serde_json::json;
///
/// let tql = Tql::new();
///
/// let records = vec![
///     json!({"name": "Alice", "age": 30}),
///     json!({"name": "Bob", "age": 25}),
/// ];
///
/// let results = tql.query(&records, "age > 25").unwrap();
/// assert_eq!(results.len(), 1);
/// ```
pub struct Tql {
    parser: TqlParser,
    evaluator: TqlEvaluator,
    stats_evaluator: StatsEvaluator,
}

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

impl Tql {
    /// Create a new TQL instance with default settings
    pub fn new() -> Self {
        Self {
            parser: TqlParser::new(),
            evaluator: TqlEvaluator::new(),
            stats_evaluator: StatsEvaluator::new(),
        }
    }

    /// Create a new TQL instance with custom parser depth limit
    pub fn with_max_depth(max_depth: usize) -> Self {
        Self {
            parser: TqlParser::with_max_depth(max_depth),
            evaluator: TqlEvaluator::with_max_depth(max_depth),
            stats_evaluator: StatsEvaluator::new(),
        }
    }

    /// Execute a TQL query against a list of records
    ///
    /// # Arguments
    ///
    /// * `records` - A slice of JSON values to query against
    /// * `query` - The TQL query string
    ///
    /// # Returns
    ///
    /// A vector of references to matching records
    ///
    /// # Examples
    ///
    /// ```
    /// use tql::Tql;
    /// use serde_json::json;
    ///
    /// let tql = Tql::new();
    /// let records = vec![
    ///     json!({"name": "Alice", "age": 30}),
    ///     json!({"name": "Bob", "age": 20}),
    /// ];
    ///
    /// let results = tql.query(&records, "age >= 25").unwrap();
    /// assert_eq!(results.len(), 1);
    /// ```
    pub fn query<'a>(&self, records: &'a [JsonValue], query: &str) -> Result<Vec<&'a JsonValue>> {
        let ast = self.parser.parse(query)?;
        self.evaluator.filter(&ast, records)
    }

    /// Execute a TQL query with enrichment (applies field mutators to results)
    ///
    /// # Arguments
    ///
    /// * `records` - A slice of JSON values to query against
    /// * `query` - The TQL query string
    ///
    /// # Returns
    ///
    /// A vector of owned records with mutators applied
    pub fn query_enriched(&self, records: &[JsonValue], query: &str) -> Result<Vec<JsonValue>> {
        let ast = self.parser.parse(query)?;
        self.evaluator.filter_and_enrich(&ast, records)
    }

    /// Count the number of records matching a query
    ///
    /// # Arguments
    ///
    /// * `records` - A slice of JSON values to query against
    /// * `query` - The TQL query string
    ///
    /// # Returns
    ///
    /// The number of matching records
    pub fn count(&self, records: &[JsonValue], query: &str) -> Result<usize> {
        let ast = self.parser.parse(query)?;
        self.evaluator.count(&ast, records)
    }

    /// Evaluate a query against a single record
    ///
    /// # Arguments
    ///
    /// * `record` - A JSON value to evaluate against
    /// * `query` - The TQL query string
    ///
    /// # Returns
    ///
    /// true if the record matches the query, false otherwise
    pub fn matches(&self, record: &JsonValue, query: &str) -> Result<bool> {
        let ast = self.parser.parse(query)?;
        self.evaluator.evaluate(&ast, record)
    }

    /// Parse a TQL query into an AST without executing it
    ///
    /// Useful for pre-compiling queries or validating syntax
    pub fn parse(&self, query: &str) -> Result<AstNode> {
        self.parser.parse(query)
    }

    /// Check if a query contains stats expressions
    ///
    /// # Arguments
    ///
    /// * `query` - The TQL query string
    ///
    /// # Returns
    ///
    /// true if the query contains stats aggregations
    pub fn is_stats_query(&self, query: &str) -> Result<bool> {
        let ast = self.parser.parse(query)?;
        Ok(matches!(ast, AstNode::StatsExpr(_) | AstNode::QueryWithStats(_)))
    }

    /// Execute a stats query against a list of records
    ///
    /// # Arguments
    ///
    /// * `records` - A slice of JSON values to aggregate
    /// * `query` - The TQL query string containing stats expression
    ///
    /// # Returns
    ///
    /// Aggregated results as a JSON value
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use tql::Tql;
    /// use serde_json::json;
    ///
    /// let tql = Tql::new();
    /// let records = vec![
    ///     json!({"name": "Alice", "status": "active"}),
    ///     json!({"name": "Bob", "status": "active"}),
    ///     json!({"name": "Charlie", "status": "inactive"}),
    /// ];
    ///
    /// let results = tql.evaluate_stats(&records, "| stats count() by status").unwrap();
    /// ```
    pub fn evaluate_stats(&self, records: &[JsonValue], query: &str) -> Result<JsonValue> {
        use crate::parser::QueryWithStatsNode;

        let ast = self.parser.parse(query)?;

        match ast {
            AstNode::StatsExpr(stats_node) => {
                // Pure stats query (no filter)
                self.evaluate_stats_node(records, &stats_node)
            }
            AstNode::QueryWithStats(QueryWithStatsNode { filter, stats }) => {
                // Filter + stats query
                let filtered = self.evaluator.filter(&filter, records)?;
                let owned_records: Vec<JsonValue> = filtered.iter().map(|&r| r.clone()).collect();
                self.evaluate_stats_node(&owned_records, &stats)
            }
            _ => Err(TqlError::SyntaxError {
                message: "Query does not contain stats expressions".to_string(),
                position: None,
                query: Some(query.to_string()),
                suggestions: vec!["Use '| stats' to add aggregations".to_string()],
            }),
        }
    }

    /// Helper to evaluate a stats node
    fn evaluate_stats_node(&self, records: &[JsonValue], stats_node: &parser::StatsNode) -> Result<JsonValue> {
        use crate::parser::{Aggregation, GroupBy};

        // Convert AST stats node to StatsQuery
        let aggregations: Vec<AggregationSpec> = stats_node
            .aggregations
            .iter()
            .map(|agg: &Aggregation| AggregationSpec {
                function: agg.function.clone(),
                field: agg.field.clone().unwrap_or_else(|| "*".to_string()),
                alias: agg.alias.clone(),
                params: std::collections::HashMap::new(),
            })
            .collect();

        let group_by: Vec<String> = stats_node
            .group_by
            .iter()
            .map(|gb: &GroupBy| gb.field.clone())
            .collect();

        let stats_query = StatsQuery {
            aggregations,
            group_by,
        };

        self.stats_evaluator.evaluate_stats(records, &stats_query)
    }
}

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

    #[test]
    fn test_tql_creation() {
        let _tql = Tql::new();
    }

    #[test]
    fn test_tql_query() {
        let tql = Tql::new();
        let records = vec![
            json!({"name": "Alice", "age": 30}),
            json!({"name": "Bob", "age": 20}),
            json!({"name": "Charlie", "age": 35}),
        ];

        let results = tql.query(&records, "age > 25").unwrap();
        assert_eq!(results.len(), 2);
    }

    #[test]
    fn test_tql_count() {
        let tql = Tql::new();
        let records = vec![
            json!({"status": "active"}),
            json!({"status": "inactive"}),
            json!({"status": "active"}),
        ];

        let count = tql.count(&records, "status eq 'active'").unwrap();
        assert_eq!(count, 2);
    }

    #[test]
    fn test_tql_matches() {
        let tql = Tql::new();
        let record = json!({"name": "John", "age": 30});

        assert!(tql.matches(&record, "age >= 25").unwrap());
        assert!(!tql.matches(&record, "age < 25").unwrap());
    }

    #[test]
    fn test_tql_parse() {
        let tql = Tql::new();
        let ast = tql.parse("age > 25 AND name eq 'John'").unwrap();

        // Verify AST was created (just check it doesn't error)
        assert!(matches!(ast, AstNode::LogicalOp(_)));
    }

    #[test]
    fn test_tql_with_mutators() {
        let tql = Tql::new();
        let records = vec![
            json!({"email": "USER@EXAMPLE.COM"}),
            json!({"email": "user@test.org"}),
        ];

        let results = tql.query(&records, "email | lowercase contains '@example.com'").unwrap();
        assert_eq!(results.len(), 1);
    }
}