AI analysis

AI analysis reads the results a data app has loaded for the viewer’s current filters and tells them what stands out: a headline, a short summary, a list of notable data points, and what the data could not show. For any notable point, an AI agent can then investigate the likely causes using data beyond the page. Nothing about this is written into the app. Lightdash runs the analysis over the queries the app already executed, so every result respects the viewer’s permissions and user attributes, and an app can pick the analysis up and render it in place without a single line of AI code of its own. The same analysis also works on classic dashboards — no data app required.

​

Turn it on

An organization admin enables AI analysis under Settings → Data apps → AI analysis. The page is only shown once the feature flag is on.

• AI analysis turns it on for every data app — and, with the dashboards flag, every dashboard — in the organization. It sends query results a viewer already has access to, to your configured AI provider. If you have brought your own provider keys, the calls go through your account; otherwise they run on Lightdash’s key.
• Continue investigations in Ask AI lets viewers carry an investigation on as an Ask AI thread. Turn it off to keep viewers at the written explanation.
• Summary instructions set organization-wide guidance every analysis summary follows — a language (“write in British English”), formats (“amounts in ZAR”), or a line of domain vocabulary. An app’s own analysis instructions are applied on top of these. Changing the instructions means stored analyses no longer match, so the next view runs fresh.

AI analysis does not depend on Ask AI being shown elsewhere in Lightdash. To run it in data apps while hiding the Ask AI homepage card, navbar action and agent chat, turn off Lightdash UI under Settings → Ask AI → General → Visibility. Self-hosted instances add enable-data-app-analysis (and/or enable-dashboard-analysis) to LIGHTDASH_ENABLE_FEATURE_FLAGS; see feature flags.

​

Limits

The same page sets caps on how much analysis the organization can run. Each is a number or, for the daily caps, empty for no cap. On Lightdash’s key the daily caps cannot be raised above the defaults. On your own key they apply as you set them. Once a daily cap is reached, the panel says so and analysis resumes the next day. Independently of those caps, each viewer is limited per app to 6 analyses, 3 investigations, and 20 prompts a minute. An analysis served from storage is free. When the limit is hit, an analysis a viewer asked for says when to retry; an automatic one on load stays quiet and tries again on the next view change. Investigations are also capped at three minutes each.

​

Analyse a view

Open a data app and click the sparkles icon in the header, labelled Analyse this view. It opens the AI analysis panel on the right. If the organization has analysis off, the icon’s tooltip and the panel say so, and organization admins get a link straight to the setting.

1. Pick an agent for investigations. The analysis itself needs no agent; the agent is what investigates a finding later, so any agent with access to the app’s data will do. Your choice is remembered per app.
2. Click Analyse this view. The panel reads every query the app ran for the current filters. Queries on tabs you are not looking at count too, as long as the app has loaded them. Apps built on a current SDK report exactly which queries are on screen, so the analysis covers what you see.

When it finishes you get:

• A headline with the main finding and a summary an executive can read without the charts.
• Findings, each with a severity of High, Medium, Positive, or Info. High and Medium point at something worth a look, Positive at a good surprise, and Info at context the summary relies on. A finding that refers to one row names the row; a finding about a whole table names only the table. Hovering a finding highlights the chart it came from when the app supports data lineage.
• Limitations, such as a missing comparison period or truncated results. They are what keeps the summary honest, so read them before acting on the headline.

An analysis with no findings is a normal outcome. The headline says so. If you change a filter or move to a different tab after analysing, the panel flags that the view changed and offers Re-analyse. The earlier result stays visible until you do. If the results behind the view have expired since the app loaded them, Lightdash reloads the app once so its queries run again, then analyses the fresh view. Should that fail too, the panel asks you to refresh the app yourself.

​

Reuse

Lightdash stores every analysis with the app version and a fingerprint of the results it read. Opening a view whose results match an analysis someone already ran shows that analysis straight away instead of running the model again, and the same applies when you return to the app later. Findings are shared this way; investigations are personal and are never copied between viewers. Re-analyse always runs afresh. Stored analyses and investigations are deleted after 30 days. A view opened after that is analysed again.

​

Investigate a finding

Click Investigate on a finding. The agent you picked runs in the background with read-only tools: it can search the semantic layer, run queries, read saved charts and dashboards, and read the agent’s knowledge documents. It cannot save content, change anything, or reach external systems. A run is bounded by the organization’s limits; if the query budget runs out, the explanation says the answer is partial. The explanation arrives as Markdown with a summary, a Possible drivers list with evidence for each, an Evidence list of what was checked, and a confidence line. It stays attached to the finding for you and is restored when you reopen the app. Viewers who have no access to any agent in the project still get the analysis. The panel explains that findings cannot be investigated, and apps hide their Investigate actions for them.

​

Continue in Ask AI

When the organization allows it, a finished investigation has a Continue in Ask AI button. It opens the investigation as a thread in Ask AI with the agent’s reasoning already in place, so you can keep asking questions. The thread stays read-only for its whole life: every later prompt keeps the investigation’s tool set, so it cannot save charts, write back, or start a deep research run, whatever the agent is otherwise allowed to do.

​

Show the analysis inside the app

Viewers do not have to open the panel. Ask the app agent to add AI analysis and the app renders the same analysis in place:

• “Add AI analysis” gives the full set: a summary block at the top of the page, markers on the flagged data points of every chart, Investigate with AI in every data point’s menu, and the investigation card under the chart.
• “Just an executive summary” gives the summary block alone.
• “Mark anomalies on the charts” gives the markers, the menu entry, and the card.

If the app should not wait for a click, ask for that too — “analyse as soon as it loads”. The agent bakes analyse on load into the app, and the analysis then runs whenever a viewer opens it or changes the view. A stored analysis of the same results is shown instead of re-running the model (see Reuse), and the organization’s limits still cap what an automatic run can spend. It is a choice made while building the app — there is no organization or per-app setting around it — so turning it off is also a prompt: “stop analysing on load”. The summary block has an Analyse button of its own and shows a Regenerate button once a result exists. Markers are painted on High, Medium, and Positive findings only, coloured by severity, and one metric’s finding never marks another series of the same chart. Hovering a marked point shows the finding under the value, and the point’s menu opens the investigation, or reopens it once one exists.

​

Steer the summaries

When the summaries should be written a certain way, ask the agent for it — “write the summaries in British English”, “amounts are in EUR”, or a line of domain vocabulary such as “stage labels are covenant stages, not sales stages”. The agent bakes the guidance into the app as analysis instructions, and every analysis of that app follows it, including analyses run from the panel. Instructions guide wording and interpretation only: they cannot grant data access or change which results are analysed, and they are capped at 2,000 characters. Guidance that should apply to every app — house style, language, currency — belongs in the organization-wide Summary instructions under Settings → Data apps → AI analysis instead. The organization default applies first and an app’s own instructions are added after it, so an app adds its domain vocabulary on top of the house style rather than replacing it. All of this renders nothing when AI analysis is off, so an app built with it works unchanged for organizations that have not turned it on. While you build, the app builder shows an AI analysis off chip next to the prompt when the app renders analysis but the organization has it off, so you are not left wondering why nothing appears; admins can click it to turn analysis on.

​

For app code

If you edit app code locally, two hooks from @lightdash/query-sdk expose the analysis:

• useInsights() returns the view’s analysis, and useInsights(result) narrows it to the findings on one useLightdash query, with a matches(row, fieldId) helper for marking data points. The template ships ready-made components under src/components/insights/ for the summary block, markers, menu entry, and investigation card.
• useInsights({ instructions }) — or the instructions prop on the shipped InsightsSummary component — sets the app’s analysis instructions. One string per app.
• useInsights({ analyseOnLoad: true }) — or the analyseOnLoad prop on InsightsSummary — declares analyse on load in app code. One value per app.
• useAiPrompt() lets the app ask its own short question about results it has already loaded, for an author-written takeaway under a chart or an explanation of a clicked row. Answers are plain text. Prompts are capped at 2,000 characters and count against the prompt limits above.

Neither hook sends rows anywhere: the app names the query, and Lightdash reads the results from the viewer’s own query history. Both report the feature as unavailable, and render nothing, outside a Lightdash host that has analysis on. The app template’s references/ai-analysis.md documents both in full.

​

On classic dashboards

The same analysis runs on any dashboard, without building a data app. It is gated by its own enable-dashboard-analysis feature flag — independent of the data-apps flags, so an organization can have dashboard analysis without data apps — which Lightdash support turns on for Cloud organizations on request; self-hosted instances add it to LIGHTDASH_ENABLE_FEATURE_FLAGS. The same organization consent toggle under Settings → AI analysis applies (when data apps are not enabled, the page appears as a top-level settings item), and so do the same limits, reuse, and 30-day retention. Open a dashboard in view mode and pick Analyse this view from the AI launcher in the corner. The analysis covers the queries the dashboard ran for the current filters, and charts on the active tab only — unlike apps, where hidden tabs may be included. A different tab, filter, or parameter value is a different view, analysed (or served from storage) separately. Hovering a finding scrolls the chart it came from into view, and once an analysis exists, the launcher greets the next viewer of that view with an Insights on this view card — the headline and top findings — instead of waiting for a click. Investigations and Continue in Ask AI work exactly as they do for apps. Dashboards have no app code to carry analysis instructions, so the organization-wide Summary instructions are the way to steer dashboard summaries. Dashboard analysis is for signed-in viewers: it is not offered in edit mode, on embedded dashboards, or in scheduled deliveries.

​

Where it works

AI analysis is for people viewing a data app in Lightdash while signed in. It is not available, and apps built with it show nothing extra, in:

• Scheduled deliveries and Google Sheets syncs, which render the app under the creator’s account.
• Embedded apps, which run under an embed token.
• Local preview with lightdash apps preview, where there is no Lightdash host to run the analysis.

​

What is sent to the model

• Analysis sends the query results the app loaded for the viewer, with their field names and any analysis instructions — the organization default and the app’s own — to the AI provider configured for your organization.
• Investigation runs the agent you picked, with the same data access that agent has anywhere else.
• App prompts send the results the app named, and the author’s question.

Results a viewer cannot see never reach the model, because the analysis only ever reads queries that viewer ran. Analyses are stored in your Lightdash database alongside the app for 30 days. Every run is recorded against the app, the viewer, the operation, and the model, so usage can be attributed.