From 4fb7a9d43316d8a1f185a963d15303e11d4348ea Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 29 Apr 2026 16:04:51 +0000 Subject: [PATCH] docs: add data apps section under Build with AI --- docs.json | 11 +++++ guides/data-apps/best-practices.mdx | 57 +++++++++++++++++++++ guides/data-apps/creating-an-app.mdx | 74 ++++++++++++++++++++++++++++ guides/data-apps/data-context.mdx | 56 +++++++++++++++++++++ guides/data-apps/overview.mdx | 41 +++++++++++++++ guides/data-apps/sharing-an-app.mdx | 25 ++++++++++ 6 files changed, 264 insertions(+) create mode 100644 guides/data-apps/best-practices.mdx create mode 100644 guides/data-apps/creating-an-app.mdx create mode 100644 guides/data-apps/data-context.mdx create mode 100644 guides/data-apps/overview.mdx create mode 100644 guides/data-apps/sharing-an-app.mdx diff --git a/docs.json b/docs.json index 14cd67d4..d82e629c 100644 --- a/docs.json +++ b/docs.json @@ -148,6 +148,17 @@ ] }, "references/integrations/lightdash-mcp", + { + "group": "Data apps", + "icon": "window", + "pages": [ + "guides/data-apps/overview", + "guides/data-apps/creating-an-app", + "guides/data-apps/sharing-an-app", + "guides/data-apps/best-practices", + "guides/data-apps/data-context" + ] + }, { "group": "Agentic development", "icon": "code", diff --git a/guides/data-apps/best-practices.mdx b/guides/data-apps/best-practices.mdx new file mode 100644 index 00000000..40fb4be9 --- /dev/null +++ b/guides/data-apps/best-practices.mdx @@ -0,0 +1,57 @@ +--- +title: "Data apps best practices" +sidebarTitle: "Best practices" +description: "Practical tips for getting higher-quality data apps with fewer iterations." +--- + +A few small habits make a big difference in the quality of the apps the agent produces. Use these as a starting point and adapt them to your team's workflow. + +## Prompt iteratively + +Most apps improve substantially after a few rounds of prompting. Rather than trying to describe the perfect app in one message, start simple and refine: + +1. Send a short initial prompt that describes the core purpose of the app. +2. Preview the result and identify what's wrong or missing. +3. Send focused follow-up prompts (e.g. "make the revenue chart a bar chart and group it by month"). +4. Repeat until the app does what you want. + +Short, specific prompts tend to produce better changes than long, sweeping rewrites. + +## Use images to nail the style + +Images help a lot to get the style right. The agent can pick up on layout, color, density, typography, and component style much more reliably from a picture than from a long written description. + +Useful images to attach include: + +- Screenshots of dashboards or apps you want yours to look like. +- Design mockups from Figma or similar tools. +- Sketches or whiteboard photos showing the layout. +- Examples of specific components (a card, a chart, a header) you want to mirror. + +If you don't like how something looks, attaching a reference image is often faster than describing the change in words. + +## Provide example data + +Providing some data to the app—either as attached queries, dashboards, or sample values—helps the agent run much better queries. With concrete examples, the agent can: + +- Pick the right metrics and dimensions from your semantic layer. +- Choose sensible default filters and date ranges. +- Generate visualizations that match the shape of your data. + + + When you provide data as context, the agent can see that data while it's building your app. Don't attach data the agent shouldn't see. Once the app is built and running, all queries are still executed by Lightdash with the viewer's permissions—but the *building* phase reads whatever context you attach. + + +## Verify queries with the inspector + +Before sharing an app with your team, open the [query inspector](/guides/data-apps/creating-an-app#inspecting-the-apps-queries) and confirm that: + +- Each query is using the metrics and dimensions you expect. +- Filters and parameters are being applied correctly. +- The numbers in the app match the numbers in your dashboards and explores. + +Catching a wrong field or missing filter at this stage is much cheaper than discovering it after the app has been shared widely. + +## Keep apps focused + +Apps tend to be easier to build, faster to load, and easier to maintain when they have a clear, narrow purpose. If you find yourself describing several unrelated workflows in one app, consider splitting it into multiple apps and sharing each in the space where it's most relevant. diff --git a/guides/data-apps/creating-an-app.mdx b/guides/data-apps/creating-an-app.mdx new file mode 100644 index 00000000..0eedb4fe --- /dev/null +++ b/guides/data-apps/creating-an-app.mdx @@ -0,0 +1,74 @@ +--- +title: "Creating a new app" +sidebarTitle: "Creating an app" +description: "Create a data app, choose a template, and give the agent the context it needs to build something useful." +--- + +You can create a new data app from the **Apps** section of your Lightdash project. From there, the AI agent will guide you through building the app: you describe what you want, give it context, and iterate on the result. + +## Start a new app + +1. Open your Lightdash project and go to **Apps**. +2. Click **New app**. +3. Give your app a name and an initial prompt describing what you want it to do. + +The agent will use the prompt, any context you attach, and your semantic layer to scaffold a first version of the app inside a sandbox. The app appears in Lightdash as an iframe once it's ready to preview. + +## Choosing a template + +When you create a new app, you can start from a template instead of a blank prompt. A template is a pre-built starting point—a small app skeleton with example layout, components, and queries—that the agent uses as a foundation when generating your app. + +Templates are useful when: + +- You want a familiar shape (e.g. a KPI dashboard, a calculator, a form-driven report) without describing the whole structure from scratch. +- You want to set a consistent look and feel across multiple apps. +- You're not sure what's possible and want to see a working example to iterate on. + +Picking a template doesn't lock you in—you can keep prompting the agent to change the layout, add new sections, or remove anything you don't need. + +## Adding context + +The more relevant context you give the agent, the better the resulting app. You can attach several types of context to your prompts. + +### Queries and dashboards + +You can attach existing saved queries and dashboards as context. When you do this, the agent uses them to understand: + +- Which fields, metrics, and filters are relevant to the app you're building. +- How you typically slice and visualize this data. +- Which dashboards or charts the app should mirror, extend, or replace. + +Attaching a saved query or dashboard is usually the fastest way to point the agent at the right part of your semantic layer without having to describe everything in words. + +### Images + +You can also attach images—screenshots, mockups, sketches, or examples from other tools—as context for the agent. Images are especially helpful for: + +- Communicating the visual style and layout you want. +- Showing examples of charts or components from other products. +- Conveying brand or design conventions that are hard to put into words. + +For more on when and how to use images effectively, see [Best practices](/guides/data-apps/best-practices). + +## Inspecting the app's queries + +Every data app runs queries against your Lightdash project to fetch the data it displays. To see exactly what the app is doing, open the **query inspector**. + +The query inspector shows details about each query the app is running, including: + +- Which explore, dimensions, metrics, and filters were used. +- The parameters the app passed to the query. +- The results that were returned. + +This is the easiest way to debug unexpected numbers, confirm that the agent is using the right fields, or verify that filters are being applied as you intended. + +## Iterating on your app + +Building a great app is usually an iterative process: + +1. Start with a prompt (and optionally a template, queries, or images). +2. Preview the generated app and try it out. +3. Use the query inspector to verify it's pulling the right data. +4. Send follow-up prompts to refine the layout, change calculations, or add new features. + +Most apps improve substantially after a few rounds of feedback—see [Best practices](/guides/data-apps/best-practices) for tips on getting there faster. diff --git a/guides/data-apps/data-context.mdx b/guides/data-apps/data-context.mdx new file mode 100644 index 00000000..35050015 --- /dev/null +++ b/guides/data-apps/data-context.mdx @@ -0,0 +1,56 @@ +--- +title: "Data context and the app model" +sidebarTitle: "Data context and app model" +description: "How data apps reason about your data, run queries, and respect permissions." +--- + +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](/guides/data-apps/creating-an-app#inspecting-the-apps-queries) 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](/guides/data-apps/sharing-an-app) 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. + +## Related reading + +- [Creating a new app](/guides/data-apps/creating-an-app) +- [Sharing an app](/guides/data-apps/sharing-an-app) +- [Best practices](/guides/data-apps/best-practices) +- [Spaces](/references/workspace/spaces) diff --git a/guides/data-apps/overview.mdx b/guides/data-apps/overview.mdx new file mode 100644 index 00000000..af0cd2ff --- /dev/null +++ b/guides/data-apps/overview.mdx @@ -0,0 +1,41 @@ +--- +title: "Data apps" +sidebarTitle: "Overview" +description: "Build interactive, data-powered apps in Lightdash with the help of an AI agent." +--- + +Data apps let you describe what you want in natural language and have an AI agent build a custom, interactive experience on top of your Lightdash data. Apps are generated by Claude in a secure sandbox and rendered inside Lightdash in an iframe, so you get a fully custom UI without leaving your analytics tool. + +Behind the scenes, every query the app runs is executed by Lightdash using the viewer's permissions. That means data access is always governed by your existing semantic layer, spaces, and user attributes—no matter who is using the app. + +## What you can do with data apps + +- Build internal tools, calculators, and bespoke dashboards tailored to a specific workflow. +- Combine charts, tables, and custom UI (forms, filters, controls) that wouldn't fit a standard dashboard. +- Share apps with the rest of your organization through Lightdash spaces. +- Inspect every query the app runs to understand exactly what data is being fetched. + +## How data apps work + +1. You describe the app you want and (optionally) attach context like saved queries, dashboards, and reference images. +2. An AI agent builds the app inside a sandboxed environment. +3. The app is embedded in Lightdash as an iframe and runs against your project. +4. When the app needs data, it asks Lightdash to execute a query. Lightdash runs the query using the current user's permissions and returns the results to the app. +5. You can share the app by moving it into a space, where it behaves like any other piece of content in that space. + +## In this section + + + + Start a new app, choose a template, and add data context. + + + Move your app into a space so others in your organization can use it. + + + Tips to get higher-quality apps with fewer iterations. + + + Understand how the agent reasons about your data and runs queries. + + diff --git a/guides/data-apps/sharing-an-app.mdx b/guides/data-apps/sharing-an-app.mdx new file mode 100644 index 00000000..e6057532 --- /dev/null +++ b/guides/data-apps/sharing-an-app.mdx @@ -0,0 +1,25 @@ +--- +title: "Sharing an app" +sidebarTitle: "Sharing an app" +description: "Move your data app into a space so others in your organization can use it." +--- + +While you're building a data app, it lives in your personal workspace and is only visible to you. To share it with other people in your organization, move the app into a [space](/references/workspace/spaces). + +## Move an app to a space + +1. Open the app you want to share. +2. Click **Move to space** (or use the app's options menu). +3. Select the space you want to move the app into and confirm. + +Once the app is in a space, it behaves like any other piece of content in that space. + +## How permissions work after sharing + +Once your app is in a space, it follows the same rules as charts and dashboards in that space: + +- **Access** is controlled by the space's access settings. Anyone who can access the space can open the app; users who can't access the space can't see it. +- **Editing** follows space roles. Users with edit access on the space can update or remove the app; viewers can use it but can't change it. +- **Data permissions** still apply on every query. When a user opens the app, all of its queries are executed using *their* permissions—their role, group memberships, and user attributes—not yours. People only ever see data they're allowed to see, even when using an app someone else built. + +For a refresher on how spaces work, see [Spaces](/references/workspace/spaces).