Skip to content

docs: document SQL mode for AI agents #643

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document SQL mode for AI agents #643

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions guides/ai-agents/using-ai-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,39 @@ As mentioned earlier, Lightdash agents use the **semantic layer** defined in you
This ensures that the AI generates accurate queries and visualizations based on your specific data context.
So, *when an Agent generates an answer, the output is a semantic query, **not SQL!*** This means that you can easily swap between the conversational AI interface and the standard Lightdash exploration experience.

## SQL mode

SQL mode lets the agent reach for raw SQL when a question can't be answered from the semantic layer alone — for example, when the data exists in your warehouse but hasn't been modeled as an explore yet. With SQL mode on, the agent can list warehouse tables, describe their columns, and run SQL queries against your warehouse.

SQL mode is **off by default** on every new thread. You opt in per conversation using the **SQL mode** toggle below the message input.

### When to use it

- The data you need lives in a warehouse table that isn't part of an explore.
- You want a one-off lookup, audit, or shape-of-the-data check before modeling it.
- The agent has already told you it can't answer from the semantic layer.

Prefer the default (semantic) mode for anything that *can* be answered from your modeled explores — answers stay governed by your dbt metrics, joins, and row-level filters.

### Who can use it

The SQL mode toggle is visible only to users who hold the **`manage:SqlRunner`** ability — the same permission required to use the [SQL Runner](/guides/developer/sql-runner) page. If you don't see the toggle, ask a workspace admin to grant SQL Runner access to your role.

### How approvals work

SQL mode is gated by a human-in-the-loop check on every query:

1. You flip **SQL mode** on for the thread.
2. You ask a question. The agent drafts a SQL query.
3. Lightdash shows the proposed SQL inline and waits for you to **Approve** or **Reject** before anything runs against your warehouse.
4. Approved queries return results to the agent, which then summarizes or visualizes them.

Each SQL call is approved individually — there is no \"approve all\" shortcut, and approvals don't carry over between threads.

### SQL mode in Slack

Slack-triggered prompts can only use SQL mode when your organization has the **\"Require Slack users to authenticate with Lightdash\"** setting (`aiRequireOAuth`) turned on. Without it, Slack messages run under a shared workspace-default identity, so SQL execution is disabled fail-closed regardless of the toggle. See [Slack AI bot setup](/guides/ai-agents/getting-started) for how to configure OAuth.

## Asking about a chart or dashboard

You can launch an AI conversation with a chart or dashboard pre-loaded as context. From the resource's `⋯` menu, click **Ask AI Agent**.
Expand Down
Loading