Brain (AI Assistant)

Brain is a built-in AI assistant that understands your ClickHouse schema and generates executable SQL. It supports multiple LLM providers, persisted chat history, streaming responses, and optional Langfuse observability.

Included in the free Community edition.

Overview

Each Brain chat has:

• A selected model (from any configured provider)
• Schema context (up to 10 tables with column types sent to the LLM)
• Message history (persisted in SQLite, survives restarts)
• Artifacts (SQL query results saved alongside the conversation)

Chats are scoped to the authenticated user and active connection. Users cannot see each other's chats.

Providers

Brain supports three provider kinds. Configure them in Admin > Brain Providers.

Provider Configuration

Temperature Handling

• Default temperature: 0.1 for standard models
• O1/O3/O4 reasoning models: temperature omitted (not supported)
• If the provider returns a temperature unsupported error, Brain retries without temperature automatically

Model Management

After creating a provider, sync its available models:

1. Go to Admin > Brain Providers
2. Click Sync Models on the provider card
3. Activate/deactivate individual models or use bulk actions

Bulk Actions

Recommendation Scoring

When no default is set, Brain auto-selects based on a scoring heuristic:

Model Resolution Priority

When streaming a message, the model is resolved in this order:

1. Model ID from the current request (if specified)
2. Chat's stored model ID
3. System default (first active model marked as default)

Chat Workflow

Creating a Chat

Navigate to Brain in the sidebar and click New Chat. A chat is created with a default title ("New Chat") and optionally a pre-selected model.

Adding Schema Context

Use the header dropdowns to add table context:

1. Select a database
2. Select a table
3. Click Add — column names and types are fetched and attached

Up to 10 tables can be added per chat. The context is persisted as a JSON array and sent with every message.

Schema Context Format

The LLM receives structured context like:

Schema context (database: default, table: events):
Columns:
- id: UInt64
- timestamp: DateTime
- user_id: String
- event_type: String

Sending Messages

Messages stream via Server-Sent Events (SSE). The full chat history (excluding errors) is sent to the LLM with each request.

After the first message, the chat title is auto-generated from the first 48 characters of the user prompt.

System Prompt

Brain uses a focused system prompt:

You are Brain, an expert ClickHouse assistant for analytics teams.

Core behavior:
- Prioritize correctness over verbosity.
- Provide SQL first when the user asks for query help.
- Keep default queries safe: LIMIT 100 for exploratory SELECT queries.
- Ask one concise clarification if schema/context is insufficient.
- Reuse prior chat context and artifacts when relevant.

Output style:
1) One sentence acknowledging intent.
2) SQL in a fenced sql block when applicable.
3) Short explanation and optional alternatives.

If an active skill is configured, its content is appended to the system prompt.

Artifacts

When Brain generates SQL, you can execute it directly from the chat as an artifact.

Execution Rules

• Only read-only queries are allowed: SELECT, WITH, SHOW, DESC, DESCRIBE, EXPLAIN
• Default timeout: 30 seconds (max 5 minutes)
• Results are persisted as query_result artifacts with the query, data, metadata, and statistics
• Use Open in Editor to move a query to the full SQL workspace

Audit

Every artifact execution is logged as a brain.query.run audit event.

Skills

Skills are custom system prompt extensions that augment Brain's behavior for all users.

• Managed in Admin > Brain Skills
• Only one skill can be active at a time
• Content is appended as an "Active skills:" section in the system prompt
• Use skills to encode team conventions, naming standards, or domain-specific instructions

Langfuse Integration

Brain optionally reports traces and metrics to Langfuse for cost tracking and quality monitoring.

Configuration

Set credentials in Admin > Langfuse:

Use the Test button to verify connectivity before saving.

What Gets Traced

Each chat message generates:

Events are batched asynchronously (max 10 per batch or 5-second flush) with a 256-event buffer.

Safety Defaults