Brain (AI Assistant)

Brain is a built-in AI copilot that understands your ClickHouse schema and writes executable, ClickHouse-idiomatic SQL. It supports persisted multi-chat history, streaming responses, skills (reusable expertise applied to every chat), and living artifacts (charts, reports, and query results you can re-run, edit, and promote into the rest of CH-UI).

Powering Brain

Brain runs on your own LLM provider — your key, your cost, unmetered. Configure it at Admin → Brain (admin only).

Configuring AI

All AI configuration lives at Admin → Brain and is restricted to admins:

• Providers — add/edit/remove providers, sync their model lists, activate models, set a default.
• Skills — create, edit, and activate the reusable expertise Brain draws on (see Skills).

API keys are encrypted at rest with the app secret key.

Model resolution

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

1. Model selected in the request
2. The chat's stored model
3. The default active model

Ask AI (text-to-SQL)

You don't have to open a chat to get a query. In the SQL editor, click Ask AI in the toolbar, describe what you want in plain English (e.g. "top 10 users by orders last month"), and CH-UI writes a ClickHouse query straight into the editor.

The generation is grounded in your metadata, not guessed:

• The most relevant tables and columns from the active connection's live schema are retrieved and given to the model.
• Your documented models (names + descriptions) are included so the model prefers curated, governed datasets.
• The model is instructed to use only those tables/columns and ClickHouse syntax.

It uses the same AI provider as Brain. Always review generated SQL before running it.

Chat workflow

Creating a chat

Open Brain in the sidebar and click New Chat. If no provider is configured yet, Brain points you to Admin → Brain to add one.

Schema context

Use the header dropdowns to attach table context (up to 10 tables per chat): pick a database, pick a table, click Add — column names and types are fetched and sent with every message:

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 chat history (excluding errors) is sent to the model with each request. The chat title is auto-generated from the first prompt. Chats are scoped to the authenticated user + connection — users can't see each other's chats.

Base prompt

Brain uses a focused base prompt (prioritize correctness, SQL-first, safe LIMIT 100 on exploratory selects, ask one clarifying question when needed). On top of that, it appends the active skill.

Agentic tools (Pro)

With a Pro license (and a provider that supports tool calling), Brain runs an agentic loop: instead of only writing SQL for you, it can call tools to inspect your schema, run queries, and create or modify workspace objects. The catalog is 33 tools:

Read-only tools (listing, describing, querying) run without ceremony. Ask AI is Pro too.

Approval workflow

Every mutating tool — creates, updates, deletes, runs, scheduling, pipeline configuration — requires your explicit approval. Brain proposes the action as a card in the chat with Approve / Decline buttons; nothing is executed until you approve. If you decline, Brain acknowledges and offers a different approach rather than re-proposing the same thing.

Pending approvals don't linger: requests left undecided for more than 10 minutes are swept to an interrupted state, so a stale card can never be approved into action later.

Skills

A skill is reusable expertise Brain applies to every chat — domain instructions, conventions, and example queries written as plain text. Skills make Brain better at your data and your workflows without re-explaining context each time. Manage them at Admin → Brain (admin only).

Each skill has a name, its instructions (free-form text, included verbatim in Brain's system prompt), and two flags:

• Active — eligible to be used.
• Default — preferred when more than one skill is active.

One skill applies at a time: Brain uses the active skill, preferring the default one, then the most recently updated. Its content is appended to the system prompt of every chat, so keep it focused — schema conventions, naming rules, common joins, and known gotchas earn their tokens; long prose doesn't.

Writing a good pack

• Put a crisp, specific description — it's the only thing Brain sees in the catalog, so it decides whether the pack gets loaded.
• Keep instructions behaviour-focused (what to do, which tools to prefer, what good SQL looks like on your schema).
• Reserve Core for small, always-relevant guidance; everything else should be on-demand.

Living artifacts

Brain doesn't just answer — it produces artifacts you can keep, refine, and turn into real CH-UI objects. There are four types:

Every artifact is versioned and carries its re-runnable definition, so from the chat you can:

• Re-run — re-execute the query against your ClickHouse and refresh the data (bumps the version).
• Edit — change the title, SQL, or markdown in place; SQL edits re-run automatically.
• Promote — turn the artifact into a first-class object:
  • Save as query → a saved query in your workspace
  • Add to dashboard → a panel on a dashboard you pick (charts carry their config across)
  • Open in SQL editor → load the query in the full editor
  • Export markdown → download the report (or query) as a .md file

Running queries safely

Query-backed artifacts are read-only only: SELECT, WITH, SHOW, DESC, DESCRIBE, EXPLAIN. Default timeout 30s (max 5 min). Promoting to a dashboard panel or saved query is an explicit, audited action (brain.artifact.promoted); ad-hoc runs are logged as brain.query.run.

Storage

Chats, messages, artifacts, and skills are stored in CH-UI's local SQLite database on your own server. History survives restarts.

Safety defaults