Skip to main content

Documentation Index

Fetch the complete documentation index at: https://lightdash-mintlify-7725ae17.mintlify.app/llms.txt

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

This page describes how a data app interacts with your Lightdash project: what the agent sees while building, how the running app fetches data, and how permissions are enforced.

​
How the app is built and run

A data app is a small custom application generated by the AI agent and run inside a secure sandbox. Lightdash embeds the app in the UI through an iframe, so it behaves like a normal piece of Lightdash content while still being fully custom. While it’s being built, the agent uses:
  • Your prompt(s).
  • Any saved queries, dashboards, or images you attached as context.
  • Your project’s semantic layer (explores, metrics, dimensions, descriptions, and metadata).
The agent uses this context to decide which queries the app should run and how to lay out the result.

​
How queries are executed

Apps don’t talk to your data warehouse directly. Instead, every query an app needs is sent to Lightdash, which runs it on the app’s behalf. This has a few important consequences:
  • Queries use your semantic layer. Apps query the same explores, metrics, and dimensions you use in dashboards and explores—not raw SQL against tables.
  • Permissions are enforced for every viewer. When someone opens an app, every query is run with their permissions: their project role, group memberships, user attributes, and access to specific spaces and explores. Two users opening the same app can see different numbers if they have different permissions.
  • You can audit what the app is doing. The query inspector shows the explore, fields, filters, and parameters for every query the app runs.
Because queries are governed by Lightdash, an app can’t be tricked into bypassing your access controls—it can only ask for data the current user is already allowed to see.

​
What the agent can and can’t see

It’s helpful to think about two distinct phases:

​
While building (with context)

When you attach saved queries, dashboards, or sample data as context, the agent can see that data so it can build a useful app. If a piece of data is sensitive enough that you wouldn’t want the agent to see it, don’t attach it as context.

​
While the app is running

After the app is built, it runs in the sandbox and can only access data through Lightdash’s query APIs, using the viewer’s permissions. The agent isn’t sitting between the app and your warehouse—the app is a self-contained piece of code that asks Lightdash for data on behalf of whoever is using it.

​
App content and lifecycle

  • Drafts live in your personal workspace while you’re iterating.
  • Shared apps live in spaces and follow the access rules of those spaces.
  • Updates to an app are made by prompting the agent again; the app’s queries and UI change together as a single unit.