From 9c9dece83a35d7faef8d53f2cadbb418fe630687 Mon Sep 17 00:00:00 2001 From: Jake Peterson <5532776+jpetey75@users.noreply.github.com> Date: Fri, 30 Oct 2026 09:14:17 -0500 Subject: [PATCH] docs: add product facts from the final brain how-to audit (AE-1449) Co-Authored-By: Claude Opus 5.5 --- agents/set-up-agents.mdx | 2 ++ agents/use-ai-agents.mdx | 2 ++ data-apps/download-data-apps-as-code.mdx | 2 ++ data-apps/external-connections.mdx | 2 ++ explore/dashboards.mdx | 2 ++ self-host/customize-deployment/environment-variables.mdx | 1 + workflow/content-as-code.mdx | 2 ++ workspace-admin/export-limits.mdx | 2 +- workspace-admin/project-compilation-history.mdx | 2 ++ workspace-admin/sso/setup.mdx | 2 +- workspace-admin/usage-analytics-project.mdx | 4 ++++ 11 files changed, 21 insertions(+), 2 deletions(-) diff --git a/agents/set-up-agents.mdx b/agents/set-up-agents.mdx index 9ee696f4f..d3fe375cf 100644 --- a/agents/set-up-agents.mdx +++ b/agents/set-up-agents.mdx @@ -157,6 +157,8 @@ To run Ask AI on Claude models in your own AWS account and keep inference in one You can add several credentials. The organization default serves everything without its own selection, including Slack routing and thread titles. Organization admins and developers can point a project at another credential in **Project settings** → **AI region**, and, when there's more than one credential, an agent under **AI provider credential** in its settings. +If custom AI providers aren't enabled for your organization, **Project settings** → **AI region** shows *Custom AI providers are not enabled for this organization.* A project already pointed at another credential then has no AI features until you clear the selection or custom providers are turned on. + While a default Bedrock credential is set, Bedrock is the only provider Ask AI uses and nothing falls back to other providers. Agents set to another provider's model stop working until you change their model, and verified-answer search and [AI writeback](/agents/ai-writeback) are unavailable. #### Key-gated models diff --git a/agents/use-ai-agents.mdx b/agents/use-ai-agents.mdx index 2c3392a3b..bdfc3cf8d 100644 --- a/agents/use-ai-agents.mdx +++ b/agents/use-ai-agents.mdx @@ -388,3 +388,5 @@ Agents can create tables, bar charts, vertical bar charts, line charts, scatter Agent access to your data is controlled through tags in your dbt models and by the asking user's user attributes. If certain fields aren't accessible, check that they have the appropriate tags assigned to your agent, and that the user's attributes allow them. See [Who can see what](/agents/data-access#who-can-see-what) for how the controls stack, including [SQL mode](#sql-mode). Agents don't remember context between different conversation sessions. Each chat starts fresh. + +When an agent can use 15 or fewer explores, Lightdash includes the list of them in the agent's context. With more than 15, the agent searches for the fields it needs instead. diff --git a/data-apps/download-data-apps-as-code.mdx b/data-apps/download-data-apps-as-code.mdx index ce73b0553..7b462d960 100644 --- a/data-apps/download-data-apps-as-code.mdx +++ b/data-apps/download-data-apps-as-code.mdx @@ -111,6 +111,8 @@ the app will show "building" until the server finishes. The server rebuilds the app in its sandbox and publishes the new version once the build succeeds. If the build fails, the error shows up in the app's version history in the UI. +If the upload fails with `Data apps are not enabled`, data apps aren't turned on for your organization. On a self-hosted instance, see [Self-hosting data apps](/self-host/enterprise-features/data-apps). + That's the whole loop: edit `src/`, upload, repeat. ## Creating a new app locally diff --git a/data-apps/external-connections.mdx b/data-apps/external-connections.mdx index a11e4837f..bb9ab1f5a 100644 --- a/data-apps/external-connections.mdx +++ b/data-apps/external-connections.mdx @@ -31,6 +31,8 @@ A connection is scoped to a project and stores: Configuring a connection (create, edit, delete) requires the admin-only `manage:ExternalConnection` scope. Viewing the list — so an app builder can pick a connection to link — is available to Interactive Viewer and above, and only shows connections set to **Data app and chart type builders**; admins see all of them. +**Who can link it** controls who can attach a connection to an app, not who can use it afterwards. Once a connection is linked, anyone who can view the app, including embedded viewers, can make requests through it with the connection's credential. To limit what they can reach, narrow the connection's **Allowed methods** and **Allowed paths**, or turn on [**Forward viewer identity**](#forwarding-viewer-identity) so the external service applies its own per-user rules. + ## Auth types Pick the auth method that matches the target API. The secret is encrypted at rest and never returned to the client after it's saved — the proxy decrypts it server-side only when actually making a request. diff --git a/explore/dashboards.mdx b/explore/dashboards.mdx index 19df69936..548108abc 100644 --- a/explore/dashboards.mdx +++ b/explore/dashboards.mdx @@ -258,6 +258,8 @@ As a dashboard grows it may end up supporting multiple teams and use cases. Tabs - **Separate views for different audiences**, e.g. Executive Summary vs. Team-level detail - **Avoid clutter and performance issues in dashboards with lots of tiles**, e.g. split 30+ charts into three tabs based on priority or groupings like the first and second bullets above +Tiles on a tab load only when someone opens that tab, so the queries behind other tabs don't run until a viewer switches to them. + While editing, click **Add tile**, then **Add tab**. diff --git a/self-host/customize-deployment/environment-variables.mdx b/self-host/customize-deployment/environment-variables.mdx index 2d2957cc4..41ff9d0f4 100644 --- a/self-host/customize-deployment/environment-variables.mdx +++ b/self-host/customize-deployment/environment-variables.mdx @@ -412,6 +412,7 @@ Enterprise-only. For setup steps (which provider to pick, how to point at an LLM | `AI_TOOL_DESCRIPTION_MAX_CHARS` | Maximum tool-result description length sent to the AI agent (default=600). | | `AI_ANALYTICS_PROJECT_UUID` | UUID of the project used to render the internal AI usage analytics dashboard. | | `AI_ANALYTICS_DASHBOARD_UUID` | UUID of the dashboard used to render the internal AI usage analytics dashboard. | +| `ANALYTICS_EMBED_SECRET` | Secret used to sign the embed token for the AI usage analytics dashboard. [**Insights**](/agents/visibility) can't load until this, `AI_ANALYTICS_PROJECT_UUID` and `AI_ANALYTICS_DASHBOARD_UUID` are all set. | | `AI_AGENT_MCP_ALLOW_PRIVATE_ADDRESSES` | When `true`, allows AI agent [MCP server](/agents/connect-external-mcp-servers) URLs to point at private/internal network addresses (e.g. `127.0.0.1`, RFC1918 ranges). Useful for self-hosted deployments where MCP servers run inside the same private network. Leave unset or `false` to enforce public-address-only validation (default=false). | The AI Analyst supports multiple providers. Provide credentials for the provider set in `AI_DEFAULT_PROVIDER`. OpenAI and Anthropic are the most tested. For which provider to pick and end-to-end setup, see [AI agents](/self-host/enterprise-features/ai-agents). diff --git a/workflow/content-as-code.mdx b/workflow/content-as-code.mdx index 03a617ad3..39bd7f7be 100644 --- a/workflow/content-as-code.mdx +++ b/workflow/content-as-code.mdx @@ -210,6 +210,8 @@ To see a single chart's or dashboard's YAML without the CLI, open its **⋯** me From the [Lightdash CLI](/workflow/cli/reference), you can use the command `lightdash upload` to upload any changes you've made to your charts or dashboards as code. To upload new charts that you've created as code to your Lightdash project, you need to run `lightdash upload --force` +When a chart or dashboard file's keys aren't in alphabetical order, `lightdash upload` prints a warning such as `Warning: weekly-revenue.yml has unsorted YAML keys. Re-download to fix, or sort keys alphabetically.` The warning doesn't block the upload. + ### Select specific items to upload ##### Use `lightdash upload -c` or `lightdash upload --charts` to select specific charts diff --git a/workspace-admin/export-limits.mdx b/workspace-admin/export-limits.mdx index 797219ca0..136bf2eb8 100644 --- a/workspace-admin/export-limits.mdx +++ b/workspace-admin/export-limits.mdx @@ -38,7 +38,7 @@ A tab trimmed by either limit is still created and still contains data — it's ## Set per-organization limits -1. Go to **Settings → Organization → Export limits**. +1. Go to **Settings → Organization → Limits**, which opens **Query and export limits**. 2. Enter a value for **Maximum query rows**, **Maximum CSV/Excel cells**, or both. 3. Click **Save**. diff --git a/workspace-admin/project-compilation-history.mdx b/workspace-admin/project-compilation-history.mdx index 0df5f405d..178b563bb 100644 --- a/workspace-admin/project-compilation-history.mdx +++ b/workspace-admin/project-compilation-history.mdx @@ -22,6 +22,8 @@ To view the compilation logs for your project: The compilation history displays a list of all project compilations, showing when each compilation occurred, who triggered it, and the source (such as `Refresh dbt`, `CLI Deploy`). +Compilation history is a read-only record. Lightdash keeps only the latest compiled version of your project, so you can't restore an earlier compilation from here. To undo a bad deploy, deploy again from the version of your dbt project you want, with `lightdash deploy` or `Refresh dbt`. + ### Viewing compilation details Click on any log entry to view detailed information about that compilation, including: diff --git a/workspace-admin/sso/setup.mdx b/workspace-admin/sso/setup.mdx index 5575b219e..82fbf5c95 100644 --- a/workspace-admin/sso/setup.mdx +++ b/workspace-admin/sso/setup.mdx @@ -103,7 +103,7 @@ Google works differently from the other providers. On **Lightdash Cloud**, Googl Google sign-in is **on by default** for your verified domains whenever no other provider takes over. Because of this, the Google panel is also where you **opt out** of Google: set it up and toggle it off to remove the "Sign in with Google" button — and block Google sign-in server-side — for your verified domains. This is useful to enforce a dedicated provider (Okta, Azure AD, etc.) instead of Google. - **Self-hosted instances** don't use a shared Google app. Create your own Google Cloud OAuth client — set the authorized redirect URI to `{{ lightdash_url }}/api/v1/oauth/redirect/google` following Google's [Create an OAuth web client ID](https://support.google.com/workspacemigrate/answer/9222992?hl=en) guide — and provide the credentials via environment variables. See [Google SSO configuration](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#google). + **Self-hosted instances** don't use a shared Google app. Create your own Google Cloud OAuth client — set the authorized redirect URI to `{{ lightdash_url }}/api/v1/oauth/redirect/google` following Google's [Create an OAuth web client ID](https://support.google.com/workspacemigrate/answer/9222992?hl=en) guide — and provide the credentials via environment variables. The **Google** panel appears under **Single Sign-On** only once the client ID and secret are set and `AUTH_GOOGLE_ENABLED=true`. See [Google SSO configuration](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#google). ## SSO account linking diff --git a/workspace-admin/usage-analytics-project.mdx b/workspace-admin/usage-analytics-project.mdx index 63245fe5e..a018b4f3f 100644 --- a/workspace-admin/usage-analytics-project.mdx +++ b/workspace-admin/usage-analytics-project.mdx @@ -208,6 +208,10 @@ The analytics project's settings can't be edited. While **Lightdash analytics** To change your own project's connection or run a compile, select that project in the project selector first. +### "No analytics data is available yet" + +This error appears until captured events for your organization have been through the [daily processing](#data-freshness-and-history). Try again after the next daily update. On a self-hosted instance, if it persists, check that usage capture is [configured](/self-host/enterprise-features/usage-analytics): an enterprise license, usage storage, and the organization flag. + ### A dashboard is empty or missing fields Check the selected dates, whether the relevant activity occurred after capture began, and whether the nightly refresh has completed. Use **Sync content** when it is offered to update the installed definitions. Sync does not force a data refresh. If a field remains missing after an instance upgrade, contact the Lightdash team.