# Lightdash ## Docs - [Welcome to Lightdash](https://lightdash-mintlify-38246967.mintlify.site/introduction.md): Lightdash is an enterprise-ready platform for Agentic Analytics. Ask questions and get insights, dashboards, or completely bespoke apps. - [The Lightdash way: data access](https://lightdash-mintlify-38246967.mintlify.site/best-practice/lightdash-way.md): Our mission at Lightdash is to enable everybody in your company to answer their own questions using data. - [Setting up a new project](https://lightdash-mintlify-38246967.mintlify.site/get-started/setup-lightdash/intro.md): This guide is for people who are new to Lightdash and would like to learn how to set up a new project. We'll show you how to get your dbt project Lightdash-ready, connect your database and dbt project, and invite your team. - [Create your first project](https://lightdash-mintlify-38246967.mintlify.site/get-started/setup-lightdash/get-project-lightdash-ready.md) - [Update your project connection](https://lightdash-mintlify-38246967.mintlify.site/get-started/setup-lightdash/connect-project.md) - [Connect through an SSH tunnel](https://lightdash-mintlify-38246967.mintlify.site/get-started/setup-lightdash/ssh-tunnel.md): Reach a Postgres or Redshift database in a private VPC by tunnelling through a bastion host. - [Inviting teammates to your Lightdash project](https://lightdash-mintlify-38246967.mintlify.site/get-started/setup-lightdash/invite-new-users.md): You can only share things with people you've invited to your Lightdash project. Users with **Admin** access to your project can invite users. - [Learning to explore data in Lightdash](https://lightdash-mintlify-38246967.mintlify.site/get-started/exploring-data/intro.md): This guide is for people who are new to Lightdash and want to learn the fundamentals of Lightdash: querying from tables, building charts and dashboards, and sharing with your team. - [Exploring your content](https://lightdash-mintlify-38246967.mintlify.site/get-started/exploring-data/exploring-your-content.md) - [An intro to metrics and dimensions](https://lightdash-mintlify-38246967.mintlify.site/get-started/exploring-data/intro-metrics-dimensions.md) - [Querying from tables and exploring your data](https://lightdash-mintlify-38246967.mintlify.site/get-started/exploring-data/using-explores.md) - [Sharing with your team](https://lightdash-mintlify-38246967.mintlify.site/get-started/exploring-data/sharing-insights.md): It's time to share your hard work with the world! - [Planning your dashboard: the Who, What and How of building great dashboards.](https://lightdash-mintlify-38246967.mintlify.site/best-practice/planning-your-dashboard.md): For those of you who are just getting started with building dashboards, it it can be useful to do some planning before you get your hands dirty and actually start building the thing. - [Creating dashboards](https://lightdash-mintlify-38246967.mintlify.site/get-started/exploring-data/dashboards.md) - [Using dashboards](https://lightdash-mintlify-38246967.mintlify.site/get-started/exploring-data/interactive-dashboards.md) - [Metrics](https://lightdash-mintlify-38246967.mintlify.site/guides/metrics-catalog.md): The Metrics page puts your metrics front and center. Browse and explore them in the Metrics Catalog, and map how they relate to each other with Saved Trees. - [Catalog](https://lightdash-mintlify-38246967.mintlify.site/guides/metrics-catalog/catalog.md): Browse, explore, and curate your metrics in the Metrics Catalog. - [Saved Trees](https://lightdash-mintlify-38246967.mintlify.site/guides/metrics-catalog/saved-trees.md): Build shareable diagrams that show how your metrics relate to each other, visualize hierarchies, and understand dependencies across your data model. - [Drivers](https://lightdash-mintlify-38246967.mintlify.site/guides/metrics-catalog/drivers.md): Define which metrics influence each other in your .yml files and visualize those relationships automatically in Saved Trees. - [Configure your charts](https://lightdash-mintlify-38246967.mintlify.site/guides/configure-charts.md): Learn about the configuration options available for most chart types in Lightdash. - [Scheduled deliveries](https://lightdash-mintlify-38246967.mintlify.site/guides/how-to-create-scheduled-deliveries.md): Scheduled deliveries let you send a dashboard or saved chart, and their results to people via email or Slack - even to people who don't have an account in your Lightdash instance. - [Alerts](https://lightdash-mintlify-38246967.mintlify.site/guides/how-to-create-alerts.md): Alerts enable you to receive notifications via email or Slack when the value of a saved chart meets your specified conditions. - [Using the Slack integration](https://lightdash-mintlify-38246967.mintlify.site/guides/using-slack-integration.md) - [Using Filters](https://lightdash-mintlify-38246967.mintlify.site/guides/limiting-data-using-filters.md): Filters appear at the top of the Explore view or dashboard and allow users to change the data being pulled into your charts. - [Filters reference](https://lightdash-mintlify-38246967.mintlify.site/guides/filters.md): Filters appear at the top of the Explore view and allow users to change the data being pulled in. - [Date zoom](https://lightdash-mintlify-38246967.mintlify.site/guides/date-zoom.md): Change the time granularity of charts on your dashboard without editing them - [Formatting your fields](https://lightdash-mintlify-38246967.mintlify.site/guides/formatting-your-fields.md) - [How to do period-over-period analysis in Lightdash](https://lightdash-mintlify-38246967.mintlify.site/guides/period-over-period.md): Learn how to do period-over-period analysis in Lightdash with examples and best practices. - [Using custom fields](https://lightdash-mintlify-38246967.mintlify.site/guides/custom-fields.md): The fields that you see in your `dimensions` and `metrics` are created by the people maintaining your Lightdash project. But, you can create new custom dimensions or metrics for quick calculations and binning on the fly. On this page, we'll explain what custom dimensions and metrics are and how to u… - [Custom tooltips](https://lightdash-mintlify-38246967.mintlify.site/guides/custom-tooltip.md) - [Version history](https://lightdash-mintlify-38246967.mintlify.site/guides/version-history.md): Roll back to previous versions of charts and dashboards in Lightdash. - [How to promote content](https://lightdash-mintlify-38246967.mintlify.site/guides/how-to-promote-content.md): Promoting content enables you to copy content from one project to another. It's especially useful when working with preview or development projects. You can promote charts created in your development projects to production, so it's easy to test and make changes without the fear of breaking things in… - [Verified charts and dashboards](https://lightdash-mintlify-38246967.mintlify.site/guides/verified-content.md): Mark charts and dashboards as verified so your team can instantly identify trusted, approved content. Verified content gets a green checkmark badge that shows who verified it and when, and verification is automatically removed if someone other than the verifier edits the content. - [Instance health best practices](https://lightdash-mintlify-38246967.mintlify.site/guides/instance-health-best-practices.md): How to keep a Lightdash deployment relevant, governed, and performant. These are the practices a Lightdash instance health review grades against, with what good looks like, why it matters, and further guidance for each. - [Keyboard shortcuts](https://lightdash-mintlify-38246967.mintlify.site/guides/keyboard-shortcuts.md): Speed up your workflow with keyboard shortcuts in Lightdash - [Table calculations](https://lightdash-mintlify-38246967.mintlify.site/guides/table-calculations.md): Table calculations make it easy to create metrics on the fly (for example, aggregating the data in your table over some window, or getting a running total of a column). - [Formula table calculations](https://lightdash-mintlify-38246967.mintlify.site/guides/formula-table-calculations.md): Build table calculations using a spreadsheet-style formula syntax instead of raw SQL. - [SQL templates](https://lightdash-mintlify-38246967.mintlify.site/guides/table-calculations/sql-templates.md): Use our SQL templates to get started with your table calculations! - [Percent change from previous](https://lightdash-mintlify-38246967.mintlify.site/guides/table-calculations/table-calculation-sql-templates/percent-change-from-previous.md): The percent change gives you the percent change in a value compared to the value in the row above it. - [Percent of previous value](https://lightdash-mintlify-38246967.mintlify.site/guides/table-calculations/table-calculation-sql-templates/percent-of-previous-value.md) - [Percent of column total](https://lightdash-mintlify-38246967.mintlify.site/guides/table-calculations/table-calculation-sql-templates/percent-of-total-column.md): The percent of the column total will give you the percentage of each value in the column out of the total sum of the values in the column. - [Percent of group/pivot total](https://lightdash-mintlify-38246967.mintlify.site/guides/table-calculations/table-calculation-sql-templates/percent-of-group-pivot-total.md): The percent of the group/pivot total will give you the percentage of each value in a group out of the total sum of the values for that group. - [Rank in column](https://lightdash-mintlify-38246967.mintlify.site/guides/table-calculations/table-calculation-sql-templates/rank-in-column.md): Ranking values in a column is when you set every value as a number either higher than or lower than the other values. The lowest value (rank = 1) indicates the value with the first rank in your set of values. - [Running total](https://lightdash-mintlify-38246967.mintlify.site/guides/table-calculations/table-calculation-sql-templates/running-total.md): Running totals give you the sum of a value + all of the previous values in that column. - [Rolling window](https://lightdash-mintlify-38246967.mintlify.site/guides/table-calculations/table-calculation-sql-templates/rolling-window.md): Rolling windows, or lookbacks, calculate metrics like rolling averages using the current row combined with N previous rows. This can be useful for smoothing out volatile time series data to better understand long term trends. - [Using AI with Lightdash](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-overview.md): Lightdash offers multiple AI-powered capabilities to help you explore data, build your semantic layer, and integrate with external tools. - [Choosing the right AI workflow in Lightdash](https://lightdash-mintlify-38246967.mintlify.site/guides/choosing-ai-workflow.md): A practical guide to picking the right Lightdash AI surface for your user, task, and governance needs. - [Data apps](https://lightdash-mintlify-38246967.mintlify.site/guides/data-apps.md): Build interactive, AI-generated apps on top of your Lightdash semantic layer. - [Building data apps locally](https://lightdash-mintlify-38246967.mintlify.site/guides/data-apps/building-locally.md): Download a data app's source, edit it in your own editor, preview it against real data, and publish new versions with the Lightdash CLI. - [Scheduled deliveries and syncs](https://lightdash-mintlify-38246967.mintlify.site/guides/data-apps/deliveries-and-syncs.md): Send a data app's query results on a schedule as files, or keep a Google Sheet up to date from an app. - [External connections](https://lightdash-mintlify-38246967.mintlify.site/guides/data-apps/external-connections.md): Let data apps fetch from third-party HTTP APIs through a credential-injecting proxy. - [Themes](https://lightdash-mintlify-38246967.mintlify.site/guides/data-apps/themes.md): Create shared themes to give your data apps consistent styles, fonts, and instructions. - [Building a globe visualization with external connections](https://lightdash-mintlify-38246967.mintlify.site/guides/data-apps/maps.md): Build interactive d3 maps and globes in a data app, powered by an external connection for shapes and your semantic layer for data. - [Self-hosting](https://lightdash-mintlify-38246967.mintlify.site/guides/data-apps/self-hosting.md): Configure your self-hosted Lightdash instance to run Data apps. - [AI agents](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents.md): No code, no complex tools, just type what you want to know. AI Agents use your saved dashboards and the metrics you've defined in Lightdash semantic layer, so your whole team can find answers faster. - [Getting started with AI agents](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/getting-started.md): Learn how to create and configure your first AI agent in Lightdash - [Using AI agents](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/using-ai-agents.md): Learn how to interact with AI agents in Lightdash and Slack - [Deep research](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/deep-research.md): Run a durable, multi-step AI investigation and get an evidence-backed report with verified charts, findings, sources, and limitations. - [Agent visibility](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/visibility.md): Understand how Lightdash gives admins visibility, control, and a feedback loop over what AI agents do with your data. - [AI Router](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/ai-router.md): Automatically route questions to the best-fit agent, so users don't have to pick one first. - [Agent memory (Beta)](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/agent-memory.md): Lightdash AI agents learn from your questions, corrections, and feedback automatically — no setup required. - [Verified Answers](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/verified-answers.md): Train your AI agent with high-quality examples for better, more consistent responses - [Evaluations](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/evaluations.md): Test and validate your AI agent's performance with custom evaluation suites - [AI agent reviews](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/reviews.md): Surface answers your agents probably got wrong, grouped by root cause, with one-click fixes for semantic layer and project context gaps. - [Data access control](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/data-access.md): Understand how AI agents access and use your data - [Best practices for AI agents](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/best-practices.md): Learn how to configure and optimize your AI agents for the best results - [AI writeback (Beta)](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/ai-writeback.md): Ask an AI agent to edit your dbt project in chat and open a pull request with the changes. - [Creating and editing content (Beta)](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/content-tools.md): Let AI agents build and edit charts and dashboards in Lightdash - [Connecting MCP servers](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/mcp-servers.md): Extend AI agents with external tools by connecting Model Context Protocol (MCP) servers - [Autopilot](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/autopilot.md): Scheduled AI agent that keeps your project clean — fixes broken charts, flags stale content, and suggests new ones. - [AI agents as code](https://lightdash-mintlify-38246967.mintlify.site/guides/ai-agents/agents-as-code.md): Download AI agents to YAML, review them in Git, and promote them between projects using the same content-as-code workflow as charts and dashboards. - [Agent skills](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/agent-skills.md): Use AI coding agents like Cursor, Claude Code, Codex, and Antigravity to build and maintain your Lightdash semantic layer. - [Editing dashboards with agents](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/editing-dashboards-with-agents.md): Use AI coding agents to bulk edit dashboards and charts using the download-edit-upload workflow. - [AI writeback self-hosting](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/ai-writeback-self-hosting.md): Configure your self-hosted Lightdash instance to run the AI writeback agent. - [Lightdash semantic layer](https://lightdash-mintlify-38246967.mintlify.site/guides/lightdash-semantic-layer.md): Here we explain everything you need to know about the Lightdash semantic layer: how it works, where you can use it, benefits, and challenges. - [Lightdash YAML](https://lightdash-mintlify-38246967.mintlify.site/guides/lightdash-yaml.md): Use Lightdash without a dbt project by defining your semantic layer directly in YAML files. - [Developing in Lightdash](https://lightdash-mintlify-38246967.mintlify.site/get-started/develop-in-lightdash/intro.md): This guide is for people who are new to Lightdash and need to learn the developer workflow. We'll go over how to install and use the CLI, plus how to create metrics and dimensions. - [How to install the Lightdash CLI](https://lightdash-mintlify-38246967.mintlify.site/guides/cli/how-to-install-the-lightdash-cli.md): The Lightdash CLI is the recommended way to develop your dbt + Lightdash project. It makes development faster and easier, as well as giving you options for building more powerful automation to manage your Lightdash instance. - [Authenticating your CLI](https://lightdash-mintlify-38246967.mintlify.site/guides/cli/cli-authentication.md) - [Install Lightdash Skills](https://lightdash-mintlify-38246967.mintlify.site/get-started/develop-in-lightdash/install-skills.md): Enable AI-powered development with Claude Code or Cursor by installing Lightdash skills - [Adding and managing Tables](https://lightdash-mintlify-38246967.mintlify.site/get-started/develop-in-lightdash/adding-tables-to-lightdash.md) - [How to create dimensions](https://lightdash-mintlify-38246967.mintlify.site/get-started/develop-in-lightdash/how-to-create-dimensions.md) - [How to create metrics](https://lightdash-mintlify-38246967.mintlify.site/get-started/develop-in-lightdash/how-to-create-metrics.md) - [Autogenerate Lightdash-ready YAML files for your models](https://lightdash-mintlify-38246967.mintlify.site/guides/cli/how-to-auto-generate-schema-files.md): Use the lightdash generate command to auto-generate and sync schema.yml files for your dbt models so they appear as tables in Lightdash. - [Preview local changes](https://lightdash-mintlify-38246967.mintlify.site/guides/cli/how-to-use-lightdash-preview.md): Preview projects are temporary Lightdash projects where you can safely experiment with your metrics, dimensions and charts without affecting your production project. - [Deploy changes to production](https://lightdash-mintlify-38246967.mintlify.site/guides/cli/how-to-use-lightdash-deploy.md) - [Automate with CI/CD](https://lightdash-mintlify-38246967.mintlify.site/guides/cli/automate-cli-workflow.md): You can use Github actions or other CI/CD tools to automate the CLI workflow - [How to use lightdash lint](https://lightdash-mintlify-38246967.mintlify.site/guides/cli/how-to-use-lightdash-lint.md): Validate your Lightdash Code files against JSON schemas before deploying to catch errors early. - [dbt model best practices for Lightdash](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/dbt-model-best-practices.md): Learn how to structure your dbt models for optimal performance and usability in Lightdash. - [Preview projects](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/preview-projects.md): **Preview projects** are temporary Lightdash projects where you can safely experiment with your metrics, dimensions and charts without affecting your production project. - [dbt write-back](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/dbt-write-back.md): dbt Write-Back allows you to develop your models and Metrics in Lightdash and write back these changes to your dbt project. Writing back to dbt will create a new branch and pull request in your project so you can save and manage these changes. - [Pull requests](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/pull-requests.md): Track the pull requests Lightdash opens in your dbt project from write-backs, the SQL runner, the source editor, and AI agents — including their live status, source, and author — all from one place in your project settings. - [Dashboards as code](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/dashboards-as-code.md): You can download your charts and dashboards as code, make changes, then upload your changes back to your Lightdash project using the CLI. Content as code is also useful for creating new Lightdash projects where you want the content to be copied from an existing project and added to your new project. - [SQL runner](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/sql-runner.md): The SQL runner is used to build ad-hoc queries or charts using totally custom SQL. - [Virtual views](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/virtual-views.md): Virtual Views are created in the [SQL Runner](/guides/developer/sql-runner) and allow other users to reuse your custom SQL queries in Lightdash. They get listed in your `Tables` and can be used like the tables that come from your dbt project. - [Lightdash Validate](https://lightdash-mintlify-38246967.mintlify.site/guides/cli/how-to-use-lightdash-validate.md): You can check to see if your changes break any of the content in your project using `lightdash validate`. This command will run the validator which will return a list of content in your project that is broken and details about the errors. - [Validating your content](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/validating-your-content.md): Broken content is not useful content. We've built tools in Lightdash to help validate your content so you can keep it useful and we'll notify you when it isn't. - [Renaming models, metrics, and dimensions](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/renaming-models-and-fields.md) - [How to use parameters](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/using-parameters.md) - [Caching](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/caching.md): Caching can reduce the overall number of queries that Lightdash executes against your data warehouse. Learn more about the types of caching and how to enable caching in this doc. - [Working with timezones in Lightdash](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/timezones.md): Configure reports so timezones behave predictably. - [Creating tailored tables from a single dbt model](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/explores.md): You can use the `explores` configuration in your Lightdash Semantic Layer to curate multiple ways to query from the same table for different audiences. - [How to filter a dashboard in the URL](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/filtering-dashboard-in-url.md) - [How to set up Lightdash YAML validation for VS Code](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/vs-code-yaml-validation.md) - [Test changes with Lightdash compile](https://lightdash-mintlify-38246967.mintlify.site/guides/developer/cli/how-to-compile-your-lightdash-project.md): If you've connected Lightdash to GitHub, you can setup a `github action` and get Lightdash to compile your project and test your changes whenever you open a pull request. - [Upgrading your Lightdash CLI](https://lightdash-mintlify-38246967.mintlify.site/guides/cli/how-to-upgrade-cli.md) - [Lightdash Admin References](https://lightdash-mintlify-38246967.mintlify.site/references/admin.md): Below are reference docs for all admin functions and features in Lightdash. - [How to embed content](https://lightdash-mintlify-38246967.mintlify.site/guides/embedding/how-to-embed-content.md): Lightdash allows you to embed your content using expirable URLs and tokens. This is a great way to enable self-serve analytics in your own application and platform by leveraging the insights you've got in Lightdash and making them available to your own users. - [How to Embed Dashboards](https://lightdash-mintlify-38246967.mintlify.site/guides/embedding/dashboards.md): Complete guide to embedding Lightdash dashboards with full configuration options for both iframe and React SDK methods - [How to Embed Charts](https://lightdash-mintlify-38246967.mintlify.site/guides/embedding/charts.md): Learn how to embed individual Lightdash charts with minimal UI for focused, single-metric displays - [How to embed AI agents](https://lightdash-mintlify-38246967.mintlify.site/guides/embedding/ai-agents.md): Embed a Lightdash AI agent in your application so your users can chat with their data without leaving your product. - [How to embed the metrics catalog](https://lightdash-mintlify-38246967.mintlify.site/guides/embedding/metrics-catalog.md): Embed the Lightdash metrics catalog so your users can browse the metrics and dimensions in a project without a Lightdash login. - [How to embed data apps](https://lightdash-mintlify-38246967.mintlify.site/guides/embedding/data-apps.md): Embed a Lightdash data app as standalone content in an iframe using a JWT-scoped preview token. - [FAQs](https://lightdash-mintlify-38246967.mintlify.site/contact/faqs.md) - [Contact Us](https://lightdash-mintlify-38246967.mintlify.site/contact/contact-info.md): Here's the fastest way to reach us - [Generating a HAR file](https://lightdash-mintlify-38246967.mintlify.site/contact/generating-har-file.md): How to capture a HAR file from your browser to help the Lightdash support team troubleshoot issues - [Guide to package-lock.yml in dbt](https://lightdash-mintlify-38246967.mintlify.site/dbt-guides/dbt-package-lock.md): Learn what dbt's package-lock.yml file does, why it matters for your data projects, and how to manage it effectively. - [Migrating to dbt 1.10: Fix Meta and Tags Configuration Warnings](https://lightdash-mintlify-38246967.mintlify.site/dbt-guides/dbt-1.10-migration.md): Learn how to fix dbt 1.10 deprecation warnings for `meta` and `tags` properties, and migrate your project automatically with MetaMove. - [Migrating to dbt Fusion](https://lightdash-mintlify-38246967.mintlify.site/dbt-guides/dbt-fusion-migration.md): Learn how to migrate from dbt Core or dbt Cloud to the new dbt Fusion engine, including preparation steps, requirements, and best practices. - [Lightdash API](https://lightdash-mintlify-38246967.mintlify.site/api-reference/v1/introduction.md) - [Recipes](https://lightdash-mintlify-38246967.mintlify.site/api-reference/v1/recipes.md): A collection of practical, copy-paste examples showing how to combine Lightdash API endpoints to achieve common workflows. ## Optional - [About Us](https://www.lightdash.com/about) - [Community](https://join.slack.com/t/lightdash-community/shared_invite/zt-3pbwqmq5e-vhTc7HHcS787w618ngoPHA) - [Blog](https://www.lightdash.com/blog)