The Reasoner feature for AQL queries

Beta

The Reasoner is an AI-powered query optimization agent for ArangoDB that helps improve the performance of AQL queries. Once the service is set up and started, you can submit a query and the Reasoner agent inspects it by running Explain and Profile, calls tools to examine available indexes and collection statistics, then rewrites the query using what it has learned.

The process is iterative: the agent tries alternative optimization strategies, measures the result of each attempt, and picks the best. If an attempt fails or does not produce a meaningful improvement, it retries with a different approach (up to 3 times). The final optimized query is validated to ensure it returns identical results to the original. The Reasoner is currently limited to read-only query execution.

You can interact with the Reasoner directly from the Query Editor in the Arango Contextual Data Platform, or through its HTTP API for programmatic integrations.

Key capabilities

How the Reasoner works

The Reasoner automatically identifies the nature of each request and selects the appropriate processing pipeline.

General and exploration queries

For requests such as “list all collections” or “show me the graph structure”:

flowchart TD
    A([Request received]) --> B["`**Execute**
      Calls database tools as needed to retrieve the relevant data`"]
    B --> C(["`**Respond** — results returned in a clear, formatted answer`"])

Query optimization

For requests that mention terms such as optimize, slow, performance, speed up, faster, execution time, or profile:

flowchart TD
    A([Request received]) --> B["`**Profile**
      Baseline metrics collected from the original query
      (execution time, memory, index usage, row counts)`"]
    B --> C["`**Analyze**
      Available indexes and collection sizes examined`"]
    C --> D["`**Optimize**
      A new query is produced using applicable techniques
      (consults relevant AQL manual sections as needed,
      e.g. aggregation, graph traversal, subqueries, filtering)`"]
    D --> E["`**Validate**
      The optimized query is verified to return identical
      results and achieve a measurable improvement (≥ 5%)`"]
    E --> F{Passed?}
    F -->|No — up to 3 attempts| D
    F -->|Yes| G["`**Report**
      A structured markdown report is returned with the
      performance comparison and the final optimized query`"]

Architecture overview

The Reasoner runs as a single self-contained service. It bundles an AI coder that communicates with the ArangoDB MCP Server — a dedicated bridge that exposes ArangoDB operations as structured tools.

flowchart TD
    Client["Client Request
      <code>POST /query</code>"] --> ReasonerPort

    subgraph ReasonerService["Reasoner Service"]
        ReasonerPort["Reasoner
        (port 8080)"] --> AICoder["AI coder
        (port 4099)"]
    end

    AICoder --> MCP["ArangoDB MCP Server
      (database tooling)"]
    MCP --> DB[(ArangoDB)]

Prerequisites

The following external services are required:

Query optimization

The Reasoner includes a fully automated query optimization pipeline. To trigger it, include the query you want to optimize in your request along with any of the following terms: optimize, slow, performance, speed up, faster, execution time, or profile.

Optimization stages

The pipeline runs through the following stages automatically:

1. Baseline Profiling — The original query is profiled to measure execution time, memory usage, index utilization, and rows scanned. This establishes the benchmark.
2. Index Discovery — All available indexes on the relevant collections are retrieved to inform the optimization strategy.
3. Query Rewriting — A new query is produced using applicable optimization techniques.
4. Syntax Validation — The rewritten query is validated for correctness before execution, at no additional query cost.
5. Side-by-Side Comparison — Both the original and optimized queries are executed and their performance metrics compared.
6. Result Verification — The Reasoner confirms that the optimized query returns identical results to the original, matching both row counts and data content, before accepting it.
7. Automatic Retry — If the improvement does not meet the minimum threshold (5%) or the results do not match, a new optimization approach is attempted automatically, up to 3 attempts.
8. Optimization Report — A structured markdown report is returned including a performance comparison table, a summary of what changed, the reason it is faster, and the final optimized query.

Safety guarantees

The optimization pipeline operates in strict read-only mode. The Reasoner rejects any optimization attempt that includes write operations, ensuring the optimizer never modifies your data or schema.

What’s next

• Web Interface: Step-by-step instructions for using the Reasoner from the Query Editor in the Arango Contextual Data Platform.
• API Reference: Use the Reasoner programmatically via its HTTP API, including streaming and non-streaming modes.