Deep research

Run a multi-step AI investigation and get an evidence-backed report with verified charts and sources

Beta Deep research is available wherever AI agents and Documents are enabled, including eligible AI trials. Reports are published as Documents, so the documents feature flag must be on. Self-hosted deployments need the same Enterprise Edition license and AI provider configuration required by AI agents, and must add documents to LIGHTDASH_ENABLE_FEATURE_FLAGS. What Beta means.

Deep research is a long-running mode for Lightdash AI agents. It is designed for questions that need several queries, competing explanations, and a reusable report rather than one immediate answer.

The agent investigates in the background using its Lightdash context and configured sources. It publishes a structured report as a Document, with verified charts, evidence-led findings, and explicit caveats where the data limits the conclusion.

When to use deep research

Choose deep research for multi-step investigations that need cross-checking, several data cuts, or a report you can save and revisit. Stay in the default Ask mode for a quick lookup, one chart, or an interactive conversation where you want to steer each follow-up.

Questions that work well include:

• “Which product categories are trending down this quarter, and what is driving the change?”
• “Why did returning-customer revenue fall over the last 90 days? Test the main explanations.”
• “Compare paid and organic acquisition quality across our top three regions.”

How it works

Deep research uses the selected AI agent’s configuration, including its instructions, semantic-layer access, knowledge documents, project and repository context, and enabled tools. It automatically inherits the organization’s research limits and every MCP server attached to the agent; there is no per-run depth or source selection. Lightdash retries transient MCP discovery and provider timeouts with a bounded backoff. If an attached MCP server remains unavailable, the run preserves completed evidence and continues with healthy MCP servers and built-in tools where possible.

For each run, a coordinator owns the investigation: it gathers context, queries the data, and decides what to pursue next. When a question is genuinely separable it can hand that question to an isolated data worker, up to two per run. A worker sees only its own task and warehouse tools, and returns a compact findings packet rather than raw results.

The coordinator does not write the report. When research ends, Lightdash rebuilds what the run established from the queries it actually ran and their results, and the report is written from that evidence. This keeps the report grounded in verified executions and means a run that stops early still reports what it found.

Because the run executes on the server, you can close the tab or leave the thread. Reopening the thread restores the run card and its latest state.

Start a run

1. Open Ask AI

   Use the Ask AI composer on the homepage, start a new agent thread, or open an existing thread that you own. Deep research is unavailable in read-only threads, such as another user’s thread or a thread started in Slack.

2. Enable Deep research

   Select + in the composer, then select Deep research. A checkmark shows the mode is active, and the send button starts research instead of sending a chat message. CSV and document attachments are unavailable while the mode is on. When you type a longer investigative question, the + button can pulse to suggest this mode; you can still continue in regular chat.

3. Describe the outcome you need

   Include the decision or question, relevant time period, important segments, and any definitions or constraints the agent should preserve.

4. Start the investigation

   Submit the question. Lightdash saves it in the thread, creates a durable run, and begins processing it in the background.

Organization-wide settings and limits

When AI agents and the documents feature flag are enabled, organization admins can go to Organization settings → Ask AI → Deep research to configure the safety limits inherited by every run:

• Maximum steps — model steps the coordinator may take before it must finish
• Maximum tool calls — total tool calls across the coordinator and its workers
• Maximum warehouse queries — total semantic-layer and SQL queries across the run
• Time limit (ms) — wall-clock ceiling for the research phase
• Maximum tokens — total model tokens across the run
• Allow raw SQL — whether eligible users may use native or MCP run_sql tools during a run

Each numeric limit must be a positive whole number. Defaults are 16 steps, 24 tool calls, 15 warehouse queries, a 10-minute time limit, and 10 million model tokens. Raw SQL is disabled by default. Organization admins can change these values to match their governance and cost requirements.

Limits apply to the run as a whole, not to each worker separately. Well before a ceiling, a run stops widening its investigation and starts settling on an answer, so it usually finishes on its own rather than being cut off. When a run does reach a limit, Lightdash still writes the report from the evidence gathered up to that point and marks the run as partially completed. Lightdash blocks predictable unbounded field-value and dimension-only scans before warehouse execution and asks the agent to narrow them. A warehouse resource-limit error can trigger up to two attempts with a narrower or simpler query; Lightdash does not retry the unchanged query.

Sources and permissions

Deep research can use:

• Agent context and project data — the semantic layer, saved Lightdash content, knowledge documents, and other context configured on the selected agent, subject to its data access settings.
• Warehouse queries — semantic queries and, when the agent and user are allowed to use it, SQL.
• Repository context — project context and source-code tools configured on the agent.
• MCP servers — every server attached to the agent and its enabled tools.

Deep research runs without pausing for approval on each warehouse query or MCP tool call. An attached MCP server can expose write actions, and its enabled actions can run unattended. Review the agent’s attached servers and enabled tools before starting a run.

Deep research does not grant new permissions. The run starts with the creator’s access and the selected agent’s configuration, and Lightdash revalidates that access while the investigation runs. Revoking access or disconnecting a source can stop an active investigation or leave that source unavailable.

Raw SQL requires both Allow raw SQL in Organization settings → Ask AI → Deep research and the initiating user’s existing SQL Runner permission. Turning the organization setting off leaves governed semantic and metric queries available, but removes native and MCP raw SQL tools from the run.

Follow progress

The run card stays next to the question that started it and shows the latest phase, elapsed time, warehouse-query count, finding count, and recent activity.

Queued

Lightdash accepted the run and is waiting for a background worker to start it.

Running

The agent is gathering context, querying the data, or writing the report. Select View activity to inspect recent progress.

Completed

The report is published as a personal Document and linked from the run card.

Partially completed

The run reached a resource limit or recoverable error. Lightdash still wrote the report from the evidence gathered before it stopped. Select Resume research to continue unfinished work from the preserved evidence without rerunning successful queries.

Failed

The run could not produce or publish a valid report. If it preserved usable evidence, select Resume research to continue unfinished work. Otherwise, the run card provides guidance to start over.

Cancelled

The creator stopped the run before it finished.

Select Stop research while a run is queued or running to request cancellation. Cancellation is asynchronous, so a running tool call may reach its next safe checkpoint before the status changes.

Only one deep research run can be active in a thread at a time. While it is active, Deep research is disabled in the composer menu, but you can continue sending regular chat messages in the same thread. The control becomes available again when the run completes, partially completes, fails, or is cancelled.

Read the report

Select the Document card on a completed or partially completed run. The report opens in the side panel; use the open link to view it full page. The report is a personal Document: only you and organization admins can see it until you save it to a Space. Use Save to Space to share it with others.

The Document is named after the report’s title, and each finding is a top-level section, so the contents rail lets you jump between findings. A report contains:

• A short introduction
• Finding sections led by verified charts, followed by concise supporting narrative
• A conclusion and inline caveats where data coverage, freshness, or the semantic layer limits the conclusion
• Links to external evidence when the report uses it

Before publishing, Lightdash validates every chart in the report. If a chart is malformed, duplicated, missing, or cannot be verified, Lightdash leaves it out while preserving valid findings and narrative, and the report notes that evidence was omitted.

Report charts

Every report chart is a standard Document chart built from one verified warehouse query the run actually executed. It runs live against the warehouse, so it shows current data, and you can edit or explore it like any other chart in a Document.

Keeping reports

A published report is an ordinary Document: it does not expire, and deleting or retrying the run does not affect it. Delete or move it like any other Document.

Reports from runs that finished before Documents publishing stay available in their thread for 30 days after the run completed.

The regular chat agent can use the status and report from deep research runs in the same conversation when answering follow-up questions. Ask it to clarify a finding, compare evidence, or explain a limitation without pasting the report back into the chat.

Get better reports

• State the decision you are trying to make, not only the metric you want to inspect.
• Define ambiguous terms such as active customer, conversion, or retention.
• Include the time range and comparison period.
• Name segments the agent must test, such as channel, region, plan, or product category.
• Ask it to test alternatives or contradictions instead of assuming one cause.
• Treat a partially completed report as a starting point. Resolve unavailable sources or tighten the question before running it again; ask an organization admin to review the limits if runs repeatedly exhaust them.

Access requirements

Your organization must have the AI Agents entitlement or an eligible trial, the documents feature flag enabled, and Enable AI features for users turned on in Organization settings → Ask AI → General. Self-hosted deployments must also configure an AI provider as described in AI agents.

On Lightdash Cloud, ask your Lightdash contact to turn on Documents for your organization. Self-hosted deployments must add documents to LIGHTDASH_ENABLE_FEATURE_FLAGS. The older ai-deep-research flag has no effect.

Starting a run requires the Enterprise Start Deep Research runs scope (create:AiDeepResearch) for the project. Developer and Admin roles receive this scope by default. Add it explicitly to any custom role that should be allowed to start runs.

Users can only read, retry, or cancel their own deep research runs, and only within threads they are allowed to access.

Frequently asked questions

Do I have to keep the tab open?

No. The run continues on the server and its state is saved in the thread.

Can I start deep research in an existing conversation?

Yes. You can start a run from an existing thread you own as long as the thread is not read-only and the agent’s model is still available.

Can I start another run while research is still active?

Not in the same thread. You can keep chatting normally, or start deep research in another eligible thread. The control returns when the current run reaches a terminal state.

Why did my run partially complete?

The agent reached a resource budget or encountered a recoverable failure. Because the report is written from the queries the run executed rather than assembled as it goes, Lightdash still reports what the run established instead of discarding it.

What happens when a warehouse query exceeds a resource limit?

Lightdash asks the agent to narrow or simplify the query and allows up to two changed-query recovery attempts. If recovery is exhausted, the affected evidence is omitted and the report can still complete with a caveat when the remaining evidence is useful.

What does “No relevant data” mean?

The investigation completed cleanly but found no evidence relevant to the question. Refine the question or choose a project and data source that cover the topic; starting the same request again does not add new evidence.

Does retrying a failed run reuse its queries?

When a partially completed or failed run has usable evidence, Resume research creates a new run that reuses its completed queries, findings, and charts, then continues the unfinished work. If no usable evidence was preserved, Start over creates a new run from the original question.

Does deep research only read data?

No. It uses the selected agent’s configured tools. Warehouse queries run without individual approval, and attached MCP servers may include write actions. Review the agent’s configuration before starting.

Can I continue chatting after the report is ready?

Yes. The same agent can read the published report as context for follow-up questions in the thread.