How timauzi/cqql-es works
Project Type and Purpose
• Type: An Elasticsearch plugin (Java‐based) that implements “Commuting Quantum” Boolean query semantics using Symja (Matheclipse).
• Purpose: Hook into Elasticsearch’s query pipeline, parse incoming JSON queries under a new “commuting_quantum” clause, transform them according to Boolean‐algebra laws via Symja, then execute them through Elasticsearch’s search subsystem.
File Structure
• build.gradle at root of search-cqql indicates a Gradle‐built Java project.
• src/main/java/org/elasticsearch/plugin/query/CQQLPlugin.java – Entry point: registers the plugin.
• src/main/java/org/elasticsearch/index/query/CommutingQuantumQueryBuilder.java & AtomicQueryBuilderName.java – JSON → internal Query objects.
• src/main/java/org/elasticsearch/index/search/CommutingQuantumQuery.java – Wraps the rewriting logic.
• CommutingQuantumWeight & CommutingQuantumScorer – Integrate with Lucene scoring.
• libs/matheclipse/*.jar – Third-party Symja library, used for symbolic simplification.
• plugin-metadata/plugin-security.policy – JVM security policy granting file‐system access for Symja temp files.
Extract Architecture Insights from the README
• The plugin replaces “bool” DSL with “commuting_quantum” and enforces Boolean‐algebra equivalences before execution.
• Relies on Symja only for symbolic transformations, then feeds results back into Elasticsearch’s native engine.
• Loaded at runtime via elasticsearch-plugin install; no external microservices.
Main Components
a. External Inputs:
– Client JSON Query with “commuting_quantum” clause.
b. Elasticsearch Core:
– REST layer → Query DSL parser → Plugin registry.
c. CQQL Plugin Module:
– CQQLPlugin (registers builder/rewrite phases)
– CommutingQuantumQueryBuilder (parses JSON → AST)
– AtomicQueryBuilderName (maps atomic query types)
– Symja Library (matheclipse jars)
– CommutingQuantumQuery → rewrite() uses Symja to enforce algebra laws
– CommutingQuantumWeight → compute weight
– CommutingQuantumScorer → score documents
d. Lucene Search Engine (underneath ES): executes the rewritten query.
e. Data Flow: results back to client.
Relationships & Interactions
1. Client → ES REST API
2. REST API → Query Parser → CommutingQuantumQueryBuilder
3. QueryBuilder → builds CommutingQuantumQuery instance
4. CommutingQuantumQuery.rewrite() → invokes Symja symbol engine
5. Rewritten query → CommutingQuantumWeight → CommutingQuantumScorer
6. Lucene executes scorer → hits
7. Results → client
• Plugin registration during node startup.
Architectural Patterns & Design Principles
• Extension Point Pattern: implements Elasticsearch’s Plugin interface and QuerySpec for modular integration.
• Builder Pattern: QueryBuilder classes create Query objects.
• Strategy Pattern: custom Weight/Scorer for scoring strategy.
• Separation of Concerns: Symja only for symbolic logic, ES handles indexing & scoring.
Technologies & Frameworks
• Java + Gradle
• Elasticsearch Plugin API (v7.10.2)
• Lucene Query/Weight/Scorer API
• Symja (Matheclipse) – jars under libs/
• JVM Security Policy for file‐system access