Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt

Use this file to discover all available pages before exploring further.

Experimental: Data apps are currently in the Experimental phase. Learn what this means in our Feature Maturity Levels guide: Feature Maturity Levels.
Data apps let you describe what you want in plain English and get back a working, interactive application built on top of your semantic layer. Behind the scenes, Claude generates a React app inside an isolated sandbox and Lightdash serves it back to you in a sandboxed iframe. When the app runs, every query goes through Lightdash, so results respect the same permissions, user attributes, and access controls as the rest of your project. Once you’re happy with an app, you can move it into a space and share it with the rest of your organization.

​
Creating a new app

You create a new data app from the ‘New’ menu in the navigation bar.

​
Choosing a template

Every new app starts from a template. The template you pick tells the agent what kind of layout you have in mind and sets up some of the built in interactions:
  • Dashboard - a single-page layout with multiple charts and KPIs, optimized for at-a-glance reading.
  • Slide show - a presentation-style app you can step through, useful for narratives or executive reviews.
  • PDF report - a print-friendly layout designed to be exported as a PDF.
  • Custom - start from a blank prompt with no layout assumptions.
Clean Shot 2026 04 29 At 18 35 18@2x
After picking a template (other than Custom), the wizard asks a few short clarifying questions - things like the topic, the audience, and the key metrics you want to highlight. Your answers are used to seed the first prompt, which you can edit before sending. Templates only affect the first version of the app. Once you start iterating, the agent works from the existing code and your follow-up prompts.

We encourage you to try out Custom apps to make something wildly different - the sky is the limit!

​
Adding context

The more context you give the agent, the better the result. You can attach several types of context to your prompt:
  • Charts - pick existing saved charts to give the agent a working metric query it can reuse. The agent gets the structure of the query (the dimensions, metrics, filters, and table) so it knows exactly which fields to use.
  • Dashboards - attach a dashboard to pull in every query on it at once.
  • Images - upload screenshots, mockups, or design references. Images are one of the fastest ways to nail the visual style you want.
  • Sample data - each chart and dashboard chip has an Include sample data toggle. When you turn it on, Lightdash runs the query and passes the first 10 rows to the agent so it can make better decisions about formatting, content, and copy. Sample data is opt-in per resource because rows can be sensitive - the agent will see whatever you send it.

​
Iterating on your app

Every prompt you send creates a new version of the app. The agent keeps its working state between versions, so follow-up prompts like “make the header smaller” or “swap the bar chart for a line chart” land as targeted changes instead of full rewrites. If a build is taking too long or going in the wrong direction, you can cancel it and try a different prompt.

​
Query inspector

When an app runs a query, it will appear in the query inspector. Open it to see every query the running app is making - the underlying metric query, the fields it’s pulling, and the results it gets back. Use it to verify the app is asking for the right data, debug unexpected numbers, or sanity-check performance.
Clean Shot 2026 04 29 At 18 38 42@2x

​
Sharing an app

Newly created apps are personal - only you can see them. Apps will initially appear in Settings > My apps. To share an app with your team, add it to a space. Once an app is added to a space, it follows the same rules as everything else in that space:
  • Viewers of the space can open the app and interact with it.
  • Editors and admins of the space can iterate on it, rename it, move it, and delete it.
  • The app respects the same project-level access controls (user attributes, row-level filters) as the rest of your content.
Personal apps stay tied to whoever created them until they’re moved into a space. Once moved, the original creator no longer has special rights - access is governed entirely by the space.
Clean Shot 2026 04 29 At 18 39 56@2x

​
Data context and the app model

Data apps don’t ship with their own copy of your data. They run inside a sandboxed iframe with no direct access to the Lightdash API, so every query the app wants to run is proxied through the Lightdash UI hosting the iframe. This means:
  • Permissions are enforced by Lightdash, not the app. Whoever opens the app sees data based on their own role, group memberships, and user attributes - exactly as if they had run the query themselves in an explore.
  • The agent generates code, not data. When the app is being built, Claude sees your dbt model catalog (tables, dimensions, metrics) and any context you attach to the prompt. It writes queries against your semantic layer; it does not get a dump of your warehouse.
  • The agent can see anything you attach. Charts, dashboards, images, and sample data you include in the prompt are passed to the agent as context. Don’t include data you wouldn’t be comfortable sending to the model.

​
Best practices

  • Iterate. Most apps get substantially better after a few rounds of iteration. Start with the rough shape, then refine.
  • Use images to lock in style. A screenshot of a dashboard, a brand guideline, or even a hand-drawn mockup goes a long way toward getting the layout, typography, and colors right on the first try.
  • Attach sample data when content matters. If the app is making decisions based on what’s actually in your data - picking a chart type, writing copy, or formatting values - turn on sample data for the relevant charts. Just remember the agent will see the rows you share.
  • Reference existing charts and dashboards. Pointing the agent at a working metric query is faster and more reliable than describing the query in prose.
  • Use the query inspector early. If something looks off, check the queries the app is running before tweaking the prompt.