Core Concepts

This page explains the fundamental concepts you need to understand when working with datarelix.ai.

Runs

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

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

Run States

State	Description
`pending`	Run created, waiting to start
`planning`	LLM is generating the execution plan
`executing`	Steps are being executed
`success`	All steps completed successfully
`partial`	Some steps failed but partial results available
`failed`	Run 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 using sqlglot AST parsing
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

Intermediate Representation (IR)

The IR is the structured plan that the LLM outputs. Instead of executing tools directly, the LLM produces an IR that describes:

{
  "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 are encrypted database credentials stored securely:

Passwords encrypted 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.ai 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

This prevents runaway executions and ensures fair resource usage.

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
Sample values (optional)

Schema context is cached and refreshed periodically.