---
title: "Core Concepts"
description: "The concepts behind Datarelix: connections, schema context, plans, read-only validation, runs, and the evidence attached to every answer."
canonical: https://docs.datarelix.ai/concepts/
---

# 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

| 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 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:

```json
{
  "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](/guides/billing/) and the [plan and quota responses](/api/errors/).

## 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.