Skip to content
datarelix.ai docs

Core Concepts

Runs

A Run is the core unit of work in Datarelix. When you ask a question, you create a run that:

  1. Plans the execution strategy using the LLM
  2. Executes SQL queries and Python code
  3. Produces a final answer

Run States

StateDescription
pendingRun created, waiting to start
planningLLM is generating the execution plan
executingSteps are being executed
successAll steps completed successfully
partialSome steps failed but partial results available
failedRun failed to complete

Steps

Each run consists of one or more Steps. Steps are the individual operations:

SQL Steps

Execute SQL queries against your database:

  • Validated before execution (sqlglot AST parsing for SQL dialects; dedicated validators for KQL and ES|QL)
  • Limited to SELECT statements
  • Automatic LIMIT enforcement
  • Timeout protection

Sandbox Steps

Execute Python code for analysis:

  • Isolated execution environment
  • Access to pandas, numpy, matplotlib
  • Can produce artifacts (charts, files)
  • Memory and time limits

The structured plan

Instead of executing tools directly, the model returns a structured plan. It describes the steps to run:

{
  "version": "1",
  "blocks": [
    {
      "type": "sql",
      "id": "query_1",
      "sql": "SELECT * FROM customers LIMIT 100",
      "description": "Get customer data",
      "output_var": "customers_data"
    },
    {
      "type": "sandbox",
      "id": "analysis_1",
      "code": "result = customers_data.groupby('country').size()",
      "description": "Count customers by country",
      "inputs": ["customers_data"],
      "outputs": ["result"]
    }
  ]
}

This approach:

  • Ensures all operations are validated before execution
  • Allows for retry and repair logic
  • Provides transparency into the execution plan

Connections

Connections hold your database credentials:

  • Passwords encrypted at rest with Fernet symmetric encryption
  • Connection pooling for performance
  • SSL/TLS support

Artifacts

Artifacts are files produced during execution:

  • Charts and visualizations (PNG, SVG)
  • Data exports (CSV, JSON)
  • Stored securely with signed URLs

Budget System

Datarelix uses a budget system to control resource usage:

  • Maximum SQL blocks per plan
  • Maximum repair attempts
  • Token limits for LLM calls
  • Rate limiting, per API key or per signed-in user

This prevents runaway executions and ensures fair resource usage. Plan-level limits — monthly questions, active connections, AI schema analyses — are separate; see Billing & plans and the plan and quota responses.

Schema Context

The Schema Context is metadata about your database that helps the LLM write accurate queries:

  • Table names and comments
  • Column types and descriptions
  • Foreign key relationships

Schema context is cached and refreshed periodically.

Privacy