Creating a new app

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.

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 for tips on getting there faster.