diff --git a/analytics.js b/analytics.js
new file mode 100644
index 0000000..dfa06d2
--- /dev/null
+++ b/analytics.js
@@ -0,0 +1,121 @@
+(function () {
+ "use strict";
+ window.RudderSnippetVersion = "3.0.60";
+ var identifier = "rudderanalytics";
+ if (!window[identifier]) {
+ window[identifier] = [];
+ }
+ var rudderanalytics = window[identifier];
+ if (Array.isArray(rudderanalytics)) {
+ if (rudderanalytics.snippetExecuted === true && window.console && console.error) {
+ console.error("RudderStack JavaScript SDK snippet included more than once.");
+ } else {
+ rudderanalytics.snippetExecuted = true;
+ window.rudderAnalyticsBuildType = "legacy";
+ var sdkBaseUrl = "https://cdn.rudderlabs.com";
+ var sdkVersion = "v3";
+ var sdkFileName = "rsa.min.js";
+ var scriptLoadingMode = "async";
+ var methods = ["setDefaultInstanceKey", "load", "ready", "page", "track", "identify", "alias", "group", "reset", "setAnonymousId", "startSession", "endSession", "consent"];
+ for (var i = 0; i < methods.length; i++) {
+ var method = methods[i];
+ rudderanalytics[method] = function (methodName) {
+ return function () {
+ if (Array.isArray(window[identifier])) {
+ rudderanalytics.push([methodName].concat(Array.prototype.slice.call(arguments)));
+ } else {
+ var _methodName;
+ (_methodName = window[identifier][methodName]) === null || _methodName === undefined || _methodName.apply(window[identifier], arguments);
+ }
+ };
+ }(method);
+ }
+ try {
+ new Function('class Test{field=()=>{};test({prop=[]}={}){return prop?(prop?.property??[...prop]):import("");}}');
+ window.rudderAnalyticsBuildType = "modern";
+ } catch (e) {
+ }
+ var head = document.head || document.getElementsByTagName("head")[0];
+ var body = document.body || document.getElementsByTagName("body")[0];
+ window.rudderAnalyticsAddScript = function (url, extraAttributeKey, extraAttributeVal) {
+ var scriptTag = document.createElement("script");
+ scriptTag.src = url;
+ scriptTag.setAttribute("data-loader", "RS_JS_SDK");
+ if (extraAttributeKey && extraAttributeVal) {
+ scriptTag.setAttribute(extraAttributeKey, extraAttributeVal);
+ }
+ if (scriptLoadingMode === "async") {
+ scriptTag.async = true;
+ } else if (scriptLoadingMode === "defer") {
+ scriptTag.defer = true;
+ }
+ if (head) {
+ head.insertBefore(scriptTag, head.firstChild);
+ } else {
+ body.insertBefore(scriptTag, body.firstChild);
+ }
+ };
+ window.rudderAnalyticsMount = function () {
+ (function () {
+ if (typeof globalThis === "undefined") {
+ var getGlobal = function getGlobal() {
+ if (typeof self !== "undefined") {
+ return self;
+ }
+ if (typeof window !== "undefined") {
+ return window;
+ }
+ return null;
+ };
+ var global = getGlobal();
+ if (global) {
+ Object.defineProperty(global, "globalThis", {
+ value: global,
+ configurable: true
+ });
+ }
+ }
+ })();
+ window.rudderAnalyticsAddScript("".concat(sdkBaseUrl, "/").concat(sdkVersion, "/").concat(window.rudderAnalyticsBuildType, "/").concat(sdkFileName), "data-rsa-write-key", "1tLM5JN9u3GhRUidt5zjU0Uc5Qf");
+ };
+ if (typeof Promise === "undefined" || typeof globalThis === "undefined") {
+ window.rudderAnalyticsAddScript("https://polyfill-fastly.io/v3/polyfill.min.js?version=3.111.0&features=Symbol%2CPromise&callback=rudderAnalyticsMount");
+ } else {
+ window.rudderAnalyticsMount();
+ }
+ var loadOptions = {};
+ rudderanalytics.load("1tLM5JN9u3GhRUidt5zjU0Uc5Qf", "https://analytics.lightdash.com", loadOptions);
+ }
+ }
+
+ // Store current URL
+ let currentUrl = undefined;
+
+ // Store the original pushState and replaceState functions
+ const originalPushState = history.pushState;
+ const originalReplaceState = history.replaceState;
+
+ // Function to call RudderStack's page view
+ function trackPageView() {
+ // Double-check if the URL has changed
+ if( currentUrl !== window.location.href) {
+ currentUrl = window.location.href;
+ window.rudderanalytics.page();
+ }
+ }
+
+ // Override pushState to track page view
+ history.pushState = function () {
+ originalPushState.apply(this, arguments);
+ trackPageView();
+ };
+
+ // Override replaceState to track page view
+ history.replaceState = function () {
+ originalReplaceState.apply(this, arguments);
+ trackPageView();
+ };
+
+ // Listen for popstate event (browser back/forward buttons) to track page view
+ window.addEventListener('popstate', trackPageView);
+})();
\ No newline at end of file
diff --git a/dbt-guides/dbt-1.10-migration.mdx b/dbt-guides/dbt-1.10-migration.mdx
new file mode 100644
index 0000000..4b48f5f
--- /dev/null
+++ b/dbt-guides/dbt-1.10-migration.mdx
@@ -0,0 +1,321 @@
+---
+title: 'Migrating to dbt 1.10: Fix Meta and Tags Configuration Warnings'
+description: 'Learn how to fix dbt 1.10 deprecation warnings for `meta` and `tags` properties, and migrate your project automatically with MetaMove.'
+sidebarTitle: 'Migrate to dbt 1.10'
+---
+
+When you upgrade to dbt 1.10, you'll likely encounter deprecation warnings that look like this:
+
+```
+Warning: while parsing model config: Ignore unexpected key "meta"
+Warning: while parsing model config: Ignore unexpected key "tags"
+```
+
+These warnings indicate that dbt is changing how `meta` and `tags` should be structured in your YAML files. Instead of manually updating potentially hundreds of files, you can use MetaMove - a CLI tool specifically designed to automate this migration.
+
+## What Changed in dbt 1.10?
+
+Starting in dbt 1.10, you will receive deprecation warnings for dbt code that will become invalid in the future, including custom inputs like unrecognized resource properties and configurations. Some properties are moving to configs, including `meta` and `tags`.
+
+The key change affects how you define `meta` and `tags` properties across your dbt project:
+
+**Before (dbt < 1.10):**
+```yaml
+models:
+ - name: my_model
+ meta:
+ owner: "Data Team"
+ priority: "high"
+ tags: ["core", "customer"]
+ columns:
+ - name: id
+ meta:
+ is_primary_key: true
+ tags: ["identifier"]
+```
+
+**After (dbt 1.10+):**
+```yaml
+models:
+ - name: my_model
+ config:
+ meta:
+ owner: "Data Team"
+ priority: "high"
+ tags: ["core", "customer"]
+ columns:
+ - name: id
+ config:
+ meta:
+ is_primary_key: true
+ tags: ["identifier"]
+```
+
+## Why This Change Matters
+
+Previously, dbt allowed you to configure inputs largely unconstrained. Without a set of strictly defined inputs, it becomes challenging to validate your project's configuration, creating unintended issues such as silently ignoring misspelled properties and configurations.
+
+This change provides several benefits:
+
+- **Better Validation**: dbt can now catch misspelled properties and configurations
+- **Consistent Structure**: All custom attributes must be nested under the `meta` config
+- **Future-Proofing**: Prevents conflicts when dbt introduces new reserved properties
+
+## Automated Migration with MetaMove
+
+Rather than manually updating your YAML files, use MetaMove - a CLI tool built specifically for this migration. MetaMove automatically transforms your files while preserving comments and formatting.
+
+### Installation
+
+Install MetaMove using pipx (recommended):
+
+```bash
+pip install pipx # if you don't have it
+pipx install metamove
+```
+
+### Basic Usage
+
+Transform a single YAML file:
+```bash
+metamove models/my_model.yml
+```
+
+Transform multiple files:
+```bash
+metamove models/* seeds/* snapshots/*
+```
+
+Transform all YAML files in your dbt project:
+```bash
+metamove models/**/* seeds/**/* snapshots/**/*
+```
+
+### Safe Migration Process
+
+MetaMove follows a safe-by-default approach:
+
+1. **Test First**: By default, transformed files are saved to a `transformed` directory:
+ ```bash
+ metamove models/* # saves to ./transformed/
+ ```
+
+2. **Review Changes**: Compare the original and transformed files to ensure accuracy.
+
+3. **Apply In-Place**: Once confident, transform files in place:
+ ```bash
+ metamove models/* -i
+ ```
+
+### Advanced Options
+
+Specify a custom output directory:
+```bash
+metamove models/* -o my_transformed_models
+```
+
+The tool automatically processes only `.yml` and `.yaml` files, so wildcards work safely:
+```bash
+# Transform specific model directories
+metamove models/marts/* models/staging/*
+
+# Transform all nested directories
+metamove models/**/*
+```
+
+## What MetaMove Handles
+
+MetaMove intelligently processes:
+
+- **Nested Structures**: `meta` and `tags` at any nesting level, including inside `columns`
+- **Existing Config Blocks**: Merges new values into existing `config` sections
+- **All YAML Types**: Dictionaries, lists, and scalar values
+- **Formatting Preservation**: Maintains your comments and whitespace
+- **Complex Cases**: Handles edge cases following dbt precedence rules
+
+## Manual Migration (If Needed)
+
+If you prefer to migrate manually or need to understand the changes, here are the key transformations:
+
+### Model-Level Changes
+
+**Before:**
+```yaml
+models:
+ - name: customer_metrics
+ description: "Customer analytics model"
+ meta:
+ owner: "analytics_team"
+ sla: "daily"
+ tags: ["core", "customer", "metrics"]
+```
+
+**After:**
+```yaml
+models:
+ - name: customer_metrics
+ description: "Customer analytics model"
+ config:
+ meta:
+ owner: "analytics_team"
+ sla: "daily"
+ tags: ["core", "customer", "metrics"]
+```
+
+### Column-Level Changes
+
+**Before:**
+```yaml
+models:
+ - name: customers
+ columns:
+ - name: customer_id
+ description: "Unique customer identifier"
+ meta:
+ is_primary_key: true
+ data_type: "uuid"
+ tags: ["pii", "identifier"]
+```
+
+**After:**
+```yaml
+models:
+ - name: customers
+ columns:
+ - name: customer_id
+ description: "Unique customer identifier"
+ config:
+ meta:
+ is_primary_key: true
+ data_type: "uuid"
+ tags: ["pii", "identifier"]
+```
+
+### Source-Level Changes
+
+**Before:**
+```yaml
+sources:
+ - name: raw_data
+ schema: staging
+ meta:
+ loader: "fivetran"
+ freshness_sla: "1 hour"
+ tags: ["external", "raw"]
+ tables:
+ - name: users
+ meta:
+ row_count: 50000
+ tags: ["pii"]
+```
+
+**After:**
+```yaml
+sources:
+ - name: raw_data
+ schema: staging
+ config:
+ meta:
+ loader: "fivetran"
+ freshness_sla: "1 hour"
+ tags: ["external", "raw"]
+ tables:
+ - name: users
+ config:
+ meta:
+ row_count: 50000
+ tags: ["pii"]
+```
+
+## Other dbt 1.10 Changes to Consider
+
+While migrating `meta` and `tags`, be aware of other properties moving to configs:
+
+- `freshness` (for sources)
+- `docs`
+- `group`
+- `access`
+
+These properties should now be set under the `config` block following the same pattern as `meta` and `tags`.
+
+## Handling Warnings During Migration
+
+If you're using `--warn-error` flags that promote warnings to errors, you may need to adjust your configuration during migration:
+
+```yaml
+# In dbt_project.yml
+flags:
+ warn_error_options:
+ warn: ["Deprecations"] # Keep deprecation warnings as warnings
+ error: ["other_warning_types"] # Promote other warnings to errors
+```
+
+This allows you to continue working while addressing deprecation warnings gradually.
+
+## Testing Your Migration
+
+After migrating your files:
+
+1. **Run dbt parse**: Ensure your project parses without errors:
+ ```bash
+ dbt parse
+ ```
+
+2. **Check for Warnings**: Run a simple command to verify warnings are resolved:
+ ```bash
+ dbt compile --select my_model
+ ```
+
+3. **Run Tests**: Execute your test suite to ensure functionality is preserved:
+ ```bash
+ dbt test
+ ```
+
+## Best Practices
+
+- **Backup First**: Always backup your project before running any migration tool
+- **Test in Development**: Run the migration in a development branch first
+- **Review Changes**: Use git diff to review all changes before committing
+- **Migrate Incrementally**: For large projects, consider migrating one directory at a time
+- **Update CI/CD**: Ensure your deployment processes work with the new structure
+
+## Troubleshooting Common Issues
+
+### "Config block already exists" Errors
+
+If you have existing `config` blocks, MetaMove will merge the new properties. However, if you encounter conflicts:
+
+1. Review the specific file causing issues
+2. Manually resolve conflicts between existing and new config properties
+3. Re-run MetaMove on the corrected file
+
+### Unexpected YAML Structure
+
+If your YAML files have unusual structures that MetaMove doesn't handle:
+
+1. Note the problematic files in the tool output
+2. Manually migrate these files using the patterns shown above
+3. Use MetaMove for the remaining standard files
+
+### Performance with Large Projects
+
+For projects with hundreds of YAML files:
+
+1. Run MetaMove on subdirectories rather than the entire project at once
+2. Use the `-o` flag to organize transformed files by directory
+3. Process files in batches to make review manageable
+
+## Conclusion
+
+Migrating to dbt 1.10's new `meta` and `tags` structure is essential for maintaining a robust, future-proof dbt project. MetaMove makes this migration straightforward by automating the tedious work while preserving your careful formatting and comments.
+
+The goal is to enable you to work with more safety, feedback, and confidence going forward. By moving `meta` and `tags` under `config` blocks, dbt can provide better validation and prevent the subtle issues that arise from misspelled properties or unintended conflicts.
+
+Start your migration today:
+
+```bash
+pipx install metamove
+metamove models/* --help
+```
+
+For more information about dbt 1.10 changes and package management best practices, check out the [official dbt upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10) and explore [MetaMove on GitHub](https://github.com/lightdash/metamove) for advanced usage and contributing opportunities.
\ No newline at end of file
diff --git a/dbt-guides/dbt-package-lock.mdx b/dbt-guides/dbt-package-lock.mdx
new file mode 100644
index 0000000..7f70ebe
--- /dev/null
+++ b/dbt-guides/dbt-package-lock.mdx
@@ -0,0 +1,140 @@
+---
+title: "Guide to package-lock.yml in dbt"
+description: "Learn what dbt's package-lock.yml file does, why it matters for your data projects, and how to manage it effectively."
+---
+
+When you run `dbt deps` in your dbt project, you might notice a new file appearing in your project directory: `package-lock.yml`. This file is automatically generated by dbt-core and plays a crucial role in ensuring your dbt project runs consistently across different environments and team members.
+
+## What is package-lock.yml?
+
+The `package-lock.yml` file is dbt's dependency lock file, automatically created when you run `dbt deps` to install your project dependencies. This file records the exact versions of all dbt packages that were installed in your project, creating a "snapshot" of your dependency tree at a specific point in time.
+
+Think of it as a detailed receipt for your dbt packages - it doesn't just list what you bought, but the exact version, where it came from, and when it was obtained.
+
+## Understanding Package Versioning
+
+Before diving deeper into lock files, it's helpful to understand how package versioning works in dbt.
+
+### Semantic Versioning
+
+Most dbt packages follow semantic versioning (semver), which uses a three-part version number: `MAJOR.MINOR.PATCH` (e.g., `1.2.3`).
+
+- **MAJOR**: Incremented for breaking changes that aren't backward compatible
+- **MINOR**: Incremented for new features that are backward compatible
+- **PATCH**: Incremented for backward-compatible bug fixes
+
+### Version Ranges in packages.yml
+
+In your `packages.yml` file, you might specify dependencies using version ranges:
+
+```yaml
+packages:
+ - package: dbt-labs/dbt_utils
+ version: [">=1.0.0", "<2.0.0"]
+ - package: calogica/dbt_expectations
+ version: ">=0.8.0"
+```
+
+These ranges give dbt flexibility to install compatible versions, but this flexibility can lead to inconsistency.
+
+## Why Package Pinning Matters
+
+Package pinning means locking dependencies to specific, exact versions rather than version ranges. This is crucial for several reasons:
+
+### Reproducible Builds
+
+Without pinned versions, running `dbt deps` on different machines or at different times might install different package versions, even with the same `packages.yml` file. This can lead to:
+
+- Models that work on one machine but fail on another
+- Unexpected behavior changes when a package updates
+- Difficult-to-debug issues in production environments
+
+### Team Consistency
+
+When your entire team uses the same pinned versions, everyone works with identical package dependencies. This eliminates the "it works on my machine" problem that can plague data teams.
+
+### Controlled Updates
+
+With pinned versions, package updates become intentional decisions rather than accidental side effects. You can test updates in development before they reach production.
+
+## How package-lock.yml Works
+
+When you run `dbt deps`, dbt:
+
+1. Reads your `packages.yml` file
+2. Resolves all dependencies and their version ranges
+3. Downloads and installs the packages
+4. Records the exact versions installed in `package-lock.yml`
+
+The lock file includes detailed information about each package:
+
+```yaml
+packages:
+- package: dbt-labs/dbt_utils
+ version: 1.1.1
+ name: dbt_utils
+- package: calogica/dbt_expectations
+ version: 0.10.1
+ name: dbt_expectations
+sha1_hash: b980d166c84935d6d661192cf31db5144295c1af
+```
+
+### Understanding the SHA1 Hash
+
+You'll notice the `sha1_hash` at the bottom of the lock file. This is a unique fingerprint that represents the exact state of all your dependencies combined. Think of it like a tamper-evident seal on a package - if anything changes about your dependencies (versions, packages added or removed), this hash will change too.
+
+The SHA1 hash serves as a quick way to verify that two environments have identical dependency setups. If two team members have the same hash, dbt can be confident they're working with exactly the same package versions without having to check each package individually.
+
+On subsequent runs of `dbt deps`, dbt will use the versions specified in the lock file rather than resolving ranges from `packages.yml`, ensuring consistency.
+
+## Should You Commit package-lock.yml to Version Control?
+
+**Yes, you should commit `package-lock.yml` to your version control system (Git).** Here's why:
+
+### Benefits of Committing
+
+- **Team synchronization**: All team members get the same package versions
+- **Environment consistency**: Development, staging, and production use identical dependencies
+- **Deployment reliability**: CI/CD pipelines install predictable package versions
+- **Audit trail**: Track when and how package versions change over time
+
+### Best Practices
+
+- Commit the lock file alongside changes to `packages.yml`
+- Include lock file updates in your code review process
+- Regenerate the lock file when intentionally updating packages
+
+## Managing Package Updates
+
+To update your packages while using a lock file:
+
+1. **Update packages.yml** with new version ranges if needed
+2. **Delete package-lock.yml** to force fresh resolution
+3. **Run dbt deps** to generate a new lock file with updated versions
+4. **Test thoroughly** to ensure compatibility
+5. **Commit both files** together
+
+
+## Troubleshooting Common Issues
+
+### Lock File Conflicts
+
+If team members have different lock files:
+1. Delete the lock file
+2. Run `dbt deps` to generate a fresh one
+3. Commit the new lock file
+
+### Package Version Conflicts
+
+If packages have conflicting dependencies:
+1. Review your `packages.yml` version ranges
+2. Consider updating to more recent package versions
+3. Check package documentation for compatibility information
+
+## Conclusion
+
+The `package-lock.yml` file is a powerful tool for maintaining consistent, reproducible dbt projects. By automatically pinning your package versions, it eliminates a major source of environment-related issues and makes your dbt projects more reliable.
+
+Remember to commit your lock file to version control, and be prepared for the format changes coming in dbt 1.10. With proper lock file management, you'll spend less time debugging package-related issues and more time building valuable data models.
+
+For more information about dbt package management and best practices, check out the [official dbt documentation](https://docs.getdbt.com/docs/build/packages).
\ No newline at end of file
diff --git a/docs.json b/docs.json
index 7204efb..ad88c5d 100644
--- a/docs.json
+++ b/docs.json
@@ -46,6 +46,7 @@
"get-started/develop-in-lightdash/how-to-create-dimensions",
"get-started/develop-in-lightdash/how-to-create-metrics",
"get-started/develop-in-lightdash/sharing-insights"
+
]
},
{
@@ -100,7 +101,8 @@
"guides/how-to-join-tables",
"guides/filtering-dashboard-in-url",
"guides/vs-code-yaml-validation",
- "guides/how-to-promote-content"
+ "guides/how-to-promote-content",
+ "guides/renaming-models-and-fields"
]
},
{
@@ -246,6 +248,14 @@
}
]
},
+ {
+ "tab": "dbt guides",
+ "group": "How to",
+ "pages": [
+ "dbt-guides/dbt-package-lock",
+ "dbt-guides/dbt-1.10-migration"
+ ]
+ },
{
"tab": "API",
"groups": [
diff --git a/get-started/setup-lightdash/connect-project.mdx b/get-started/setup-lightdash/connect-project.mdx
index 5891a67..1f5bef6 100644
--- a/get-started/setup-lightdash/connect-project.mdx
+++ b/get-started/setup-lightdash/connect-project.mdx
@@ -96,29 +96,9 @@ Then, you should see all of the projects and their project IDs in your organizat
For the project you want to connect Lightdash to, just copy its `id` and pop it into the `project` field in the Warehouse Connection form in Lightdash.
-#### Data set
-
-This is the default dataset used by dbt to compile and run your dbt project. You can find this in the dbt cloud IDE or your local `profiles.yml` file.
-
-If you're a dbt cloud user you can find this under your profile in the dbt cloud IDE:
-
-
- 
-
-
-If you work with dbt locally, then check your `profiles.yml` file at `~/.dbt/profiles.yml` and look for a field named `dataset`:
+#### Authentication type
-```yaml
-my-profile:
- target: dev
- outputs:
- dev:
- type: bigquery
- method: oauth
- project: abc-123
- dataset: my_dataset # look for this one!
- ...
-```
+You can choose to connect to BigQuery with a user account (using "Sign in with Google") or with a service account using a JSON key file
#### Location
@@ -132,7 +112,7 @@ You can find the location of the dataset you're using for your dbt project [in y
-#### Key File
+#### Key File + permissions
To connect to BigQuery, you'll need to have a service account that you can use with Lightdash. You can read more about [creating and managing service accounts with Google BigQuery in their docs](https://cloud.google.com/iam/docs/creating-managing-service-accounts).
diff --git a/guides/limiting-data-using-filters.mdx b/guides/limiting-data-using-filters.mdx
index fc3ac1c..fdc768f 100644
--- a/guides/limiting-data-using-filters.mdx
+++ b/guides/limiting-data-using-filters.mdx
@@ -245,6 +245,26 @@ And if they want to drill-down into the data, they can always change the filters
To add saved filters to your dashboard, you must be an `editor` or an `admin` for your project.
+### Filtering charts created in the SQL Runner
+
+Dashboard filters can be applied to SQL Runner-based charts as well as charts from the Explorer. There are two different ways this can be done:
+
+- On a dashboard with both Explorer and SQL Runner charts, filters are created the same way as above — you choose a field and create a filter.
+ Then, in the **Chart tiles** tab, you can apply the filter to a SQL chart tile and choose the column you want that filter to apply to.
+
+- On a dashboard with **only** SQL Runner-based tiles, filters are created a little differently since SQL charts are based on columns instead of semantic fields.
+
+#### To create a filter on a dashboard with only SQL charts:
+
+1. Choose a column from the list of all columns available across all charts.
+2. Choose a filter label to give your filter a recognizable name.
+3. Choose your filter operator and values as you would for any other filter.
+
+By default, the new filter will be applied to every column on the dashboard that has the same name as the filtered column.
+You can also choose, in the **Chart tiles** tab of the filter dropdown, exactly which tiles and columns to apply it to.
+
+Note that as with Explorer-chart filters, you can only apply fitlers to dimensions (in this case, non-aggregated columns).
+
### Some things worth mentioning about dashboard filters
##### Sharing your dashboard with overrides
diff --git a/guides/renaming-models-and-fields.mdx b/guides/renaming-models-and-fields.mdx
new file mode 100644
index 0000000..405a9c8
--- /dev/null
+++ b/guides/renaming-models-and-fields.mdx
@@ -0,0 +1,76 @@
+---
+title: "Renaming models, metrics, and dimensions"
+---
+
+This guide explains how to rename metrics, dimensions, or models across your entire project. All field or model references will be updated across charts, dashboards, and scheduled deliveries. This feature is useful when you need to standardize naming conventions, update your dashboards after making model changes or just fix some typos quickly.
+
+
+ Content can also be renamed using [Dashboards as code](/references/dashboards-as-code). However, the rename methods in this doc require fewer steps and will automatically respect the right syntax for different field types.
+
+ Chart names and descriptions will not be updated using these rename workflows. If you want to update those in bulk, we recommend using Dashboards as code.
+
+
+## Rename in Lightdash
+
+If you change field or table names in dbt that are being used in content in Lightdash, you will receive validation errors in the Lightdash application. You can fix these directly in the validation page by renaming references to the broken charts. You can access the validation page by clicking on the bell on the navigation bar.
+
+
+
+On the navigation page, hover over the chart you want to fix, and click on the **Fix** button.
+
+
+
+You can now choose to rename a field or model using the list of **existing** values.
+
+
+
+You also have the option to **Fix all occurrences, **which allows you to rename the same field or table in all affected content, such as other charts, dashboards and scheduled deliveries.
+
+If you have made multiple field or table changes to the same chart (e.g., you changed two metrics), you will need to perform multiple rename actions.
+
+After renaming, you can rerun validation to ensure everything works as expected.
+
+## Rename in the CLI
+
+The Lightdash CLI offers an alternative and more flexible approach to renaming models or fields across your project. This is a more advanced option than the UI and affects all the content in the project. The CLI will also allow you to rename content before changes happen to dbt.
+
+### Important CLI callouts
+
+- Renaming is project-wide by default, but can be scoped to a specific model using the `--model` option.
+- Always use `--dry-run` first to understand the impact of your changes.
+- You can use `--list` on your actual run to get a full list of everything that was updated.
+- Only lowercase letters (a-z) and underscores `_` are allowed in field and table names.
+
+### Example CLI Workflow
+
+This is a sample of how you can take the most from this feature, when renaminig content on your dbt project.
+
+1. Rename a field in your dbt project YML file: `user_id` becomes `customer_id`.
+2. Create a preview environment to test those changes.
+3. Existing charts will fail, you can go into validation to confirm which ones are affected.
+4. Run `lightdash rename --type field --from user_id --to customer_id -p --dry-run` to list the affected charts.
+5. If you are happy with the changes, run rename without `--dry-run`.
+6. Confirm all charts are referencing new fields (they might still error if you haven't updated your warehouses using dbt run).
+7. Merge the code, run dbt, then run `lightdash rename --type field --from user_id --to customer_id -p --list` on your main project.
+
+- The `--list` option gives you a full list of content that was changed.
+
+The CLI will show you which charts, dashboards, alerts, and dashboard schedulers will be updated and also, we will generate a JSON log that contains the affected chart and dashboard names and UUIDs, you can use those UUIDs to manually revert some of the charts to a previous version.
+
+
+
+[Read the CLI reference doc](/references/lightdash-cli#lightdash-rename) for all arguments and more examples.
+
+## Reverting changes
+
+When renaming, a new chart version is created with the new changes. If you make a mistake during renaming, you can restore individual charts by using [version history](https://docs.lightdash.com/guides/version-history#chart-version-history).
\ No newline at end of file
diff --git a/images/Screenshot2025-06-04at09.57.24.png b/images/Screenshot2025-06-04at09.57.24.png
new file mode 100644
index 0000000..7857cce
Binary files /dev/null and b/images/Screenshot2025-06-04at09.57.24.png differ
diff --git a/images/references/access-spaces-674f6783cea4fffea02864351729cd9a.png b/images/references/access-spaces-674f6783cea4fffea02864351729cd9a.png
deleted file mode 100644
index 089d0c8..0000000
Binary files a/images/references/access-spaces-674f6783cea4fffea02864351729cd9a.png and /dev/null differ
diff --git a/images/references/add-modal-cc9dfc08cb340d9bdd98447b767b165d.png b/images/references/add-modal-cc9dfc08cb340d9bdd98447b767b165d.png
deleted file mode 100644
index 81bfc8a..0000000
Binary files a/images/references/add-modal-cc9dfc08cb340d9bdd98447b767b165d.png and /dev/null differ
diff --git a/images/references/add-within-space-d19600ecb7e73e49eed411e256a3c8fa.png b/images/references/add-within-space-d19600ecb7e73e49eed411e256a3c8fa.png
deleted file mode 100644
index b069d18..0000000
Binary files a/images/references/add-within-space-d19600ecb7e73e49eed411e256a3c8fa.png and /dev/null differ
diff --git a/images/references/move-between-space-0903e4e87ebf93ded0b4710031c5bc18.png b/images/references/move-between-space-0903e4e87ebf93ded0b4710031c5bc18.png
deleted file mode 100644
index 53c4cba..0000000
Binary files a/images/references/move-between-space-0903e4e87ebf93ded0b4710031c5bc18.png and /dev/null differ
diff --git a/images/references/rename-delete-space-f6db364127de5e969a0b8e728c2c0f58.png b/images/references/rename-delete-space-f6db364127de5e969a0b8e728c2c0f58.png
deleted file mode 100644
index eabaf89..0000000
Binary files a/images/references/rename-delete-space-f6db364127de5e969a0b8e728c2c0f58.png and /dev/null differ
diff --git a/images/references/spaces-dcc5cc3b9435883e0ef36ea4f0c2a090.png b/images/references/spaces-dcc5cc3b9435883e0ef36ea4f0c2a090.png
deleted file mode 100644
index 13ac74a..0000000
Binary files a/images/references/spaces-dcc5cc3b9435883e0ef36ea4f0c2a090.png and /dev/null differ
diff --git a/images/references/spaces/1-view-spaces.png b/images/references/spaces/1-view-spaces.png
new file mode 100644
index 0000000..805f32c
Binary files /dev/null and b/images/references/spaces/1-view-spaces.png differ
diff --git a/images/references/spaces/2-view-all-spaces.png b/images/references/spaces/2-view-all-spaces.png
new file mode 100644
index 0000000..89a2a96
Binary files /dev/null and b/images/references/spaces/2-view-all-spaces.png differ
diff --git a/images/references/spaces/3-1-transfer-to-space-bulk.png b/images/references/spaces/3-1-transfer-to-space-bulk.png
new file mode 100644
index 0000000..2fc5f09
Binary files /dev/null and b/images/references/spaces/3-1-transfer-to-space-bulk.png differ
diff --git a/images/references/spaces/3-transfer-to-space.png b/images/references/spaces/3-transfer-to-space.png
new file mode 100644
index 0000000..3913ce5
Binary files /dev/null and b/images/references/spaces/3-transfer-to-space.png differ
diff --git a/images/references/spaces/4-transfer-to-space-2.png b/images/references/spaces/4-transfer-to-space-2.png
new file mode 100644
index 0000000..9f4d4e4
Binary files /dev/null and b/images/references/spaces/4-transfer-to-space-2.png differ
diff --git a/images/references/spaces/5-add-to-space.png b/images/references/spaces/5-add-to-space.png
new file mode 100644
index 0000000..1696efa
Binary files /dev/null and b/images/references/spaces/5-add-to-space.png differ
diff --git a/images/references/spaces/6-edit-delete-space.png b/images/references/spaces/6-edit-delete-space.png
new file mode 100644
index 0000000..bf63bf2
Binary files /dev/null and b/images/references/spaces/6-edit-delete-space.png differ
diff --git a/images/rename-validation-errors.png b/images/rename-validation-errors.png
new file mode 100644
index 0000000..9042e0e
Binary files /dev/null and b/images/rename-validation-errors.png differ
diff --git a/images/rename_cli_list.png b/images/rename_cli_list.png
new file mode 100644
index 0000000..e6d8625
Binary files /dev/null and b/images/rename_cli_list.png differ
diff --git a/images/rename_fix_button.png b/images/rename_fix_button.png
new file mode 100644
index 0000000..2be9a38
Binary files /dev/null and b/images/rename_fix_button.png differ
diff --git a/images/rename_modal.png b/images/rename_modal.png
new file mode 100644
index 0000000..e48f072
Binary files /dev/null and b/images/rename_modal.png differ
diff --git a/references/google-sheets.mdx b/references/google-sheets.mdx
index cf35203..ef0c85e 100644
--- a/references/google-sheets.mdx
+++ b/references/google-sheets.mdx
@@ -15,19 +15,18 @@ If you're using Lightdash Cloud, this is already set up and available for you to
## Creating a Sync
-All users with editor access or above can create Syncs.. To create a Sync, click on the three-dot menu in the top-right corner of your chart, then click on `Google Sheets Sync`.
+All users with editor access or above can create Syncs. To do this, open your chart in view or edit mode, click the three-dot menu in the top-right corner, then click on `Google Sheets Sync`.
-
+ 
-
The pop-up shows you a list of any existing Syncs for the saved chart, you also have the option to `Create new Sync`.
-
+
Clicking `Create new Sync` takes you to the configuration screen to setup a new Google Sheets Sync.
@@ -42,9 +41,9 @@ When you create a Sync, Lightdash also creates a special tab in your Google Shee
## Sync options
-* **Name**: this is the name of your Sync in Lightdash
-* **Frequency**: this is how often your Google Sheet will be synced. You can make this hourly, daily, weekly, monthly, or custom - each frequency has its own options. For example, with a monthly schedule, you set the day of the month and the time that you want your Sync to be happen. The custom frequency lets you write out your own custom Cron expression if you need something more specific than our standard options. All times for the scheduler are in UTC.
-* **Select Google Sheet**: Use the file picker to select the Google Sheet that you'd like to sync your chart results to. Note: You need to sync to an existing Google Sheet, so ensure you have created it before you can select it here.
+- **Name**: this is the name of your Sync in Lightdash
+- **Frequency**: this is how often your Google Sheet will be synced. You can make this hourly, daily, weekly, monthly, or custom - each frequency has its own options. For example, with a monthly schedule, you set the day of the month and the time that you want your Sync to be happen. The custom frequency lets you write out your own custom Cron expression if you need something more specific than our standard options. All times for the scheduler are in UTC.
+- **Select Google Sheet**: Use the file picker to select the Google Sheet that you'd like to sync your chart results to. Note: You need to sync to an existing Google Sheet, so ensure you have created it before you can select it here.
This is what a Sync looks like when it's been set up:
@@ -73,6 +72,7 @@ To access the overview page, just head to your Project Settings, then to the `Sy
+
Here, you can also click on the three-dot-menu beside each Sync to edit or delete it.
@@ -83,4 +83,4 @@ Editing a Sync from the overview page will bring you to the same configuration s
## Google API Services User Data Policy
-Lightdash's use and transfer of information received from Google APIs adhere to [Google API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy), including the Limited Use requirements.
+Lightdash's use and transfer of information received from Google APIs adhere to [Google API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy), including the Limited Use requirements.
\ No newline at end of file
diff --git a/references/groups.mdx b/references/groups.mdx
index e0b1f46..9ad82d6 100644
--- a/references/groups.mdx
+++ b/references/groups.mdx
@@ -4,15 +4,15 @@ description: "Groups are a way to manage access to multiple users at the same ti
---
-**Groups are only available on Lightdash Cloud Pro, Enterprise plans, and Self-Hosted instances.**
+ **Groups are only available on Lightdash Cloud Pro and Enterprise plans.**
-For more information on our plans, visit our [pricing page](https://www.lightdash.com/pricing).
+ For more information on our plans, visit our [pricing page](https://www.lightdash.com/pricing).
To view and manage your groups, go to the `Organization Settings` \> `Users & groups` tab. Only users with an `organization admin` role can manage groups.
- 
+ 
## Creating groups
@@ -40,21 +40,19 @@ You can assign user attributes to groups as well as individual users. To learn m
## Using OKTA to manage groups in Lightdash
-**This feature is deprecated and will be removed in a future release.**
-
+ **This feature is deprecated and will be removed in a future release.**
+
For more information on how to provision users and groups in Lightdash, see the [SCIM integration](/references/scim-integration) documentation.
If your Lightdash instance is configured to [use OKTA as an authentication provider](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#okta), then users will automatically be assigned to the same groups in Lightdash as they are in OKTA. See the guide to [setting up OKTA](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#okta) for more information on setting the correct environment variables as well as Okta configuration: with/without custom authorization server.
-
-Note that users will only be assigned to groups that exist in Lightdash (groups won't be created automatically) and exactly match the name of the group in OKTA.
-
+ Note that users will only be assigned to groups that exist in Lightdash (groups won't be created automatically) and exactly match the name of the group in OKTA.
To manage groups in Lightdash using OKTA, you'll need to:
1. [Setup groups in your directory in OKTA](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-bulk-assign-group-people.htm)
2. [Allow groups to login in to Lightdash from Okta](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-assign-app-group.htm)
-3. Finally for group sync to work you need to [configure Okta to share groups with Lightdash](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/#add-a-groups-claim-for-a-custom-authorization-server)
+3. Finally for group sync to work you need to [configure Okta to share groups with Lightdash](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/#add-a-groups-claim-for-a-custom-authorization-server)
\ No newline at end of file
diff --git a/references/lightdash-cli.mdx b/references/lightdash-cli.mdx
index a3e3980..3f2b782 100644
--- a/references/lightdash-cli.mdx
+++ b/references/lightdash-cli.mdx
@@ -5,22 +5,23 @@ description: "The Lightdash CLI is the recommended way to develop your Lightdash
## Dependencies
-The Lightdash CLI requires the [dbt core](https://docs.getdbt.com/docs/core/installation-overview) or the [dbt cloud CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) to be installed and available under the `dbt` command.
+The Lightdash CLI requires Node, NPM, and the [dbt core](https://docs.getdbt.com/docs/core/installation-overview) or [dbt cloud](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) CLI to be installed and available under the `dbt` command.
-### Known limitations when using **dbt cloud CLI**
+### Known limitations when using dbt cloud CLI
-#### Warehouse credentials dependency for some commands
+**Warehouse credentials dependency for some commands**
Affected commands: `lightdash generate`, `lightdash preview` and `lightdash start-preview`
These commands rely on the warehouse credentials from the active project, as the dbt Cloud CLI does not expose credentials directly. Ensure the project's credentials have access to all development and staging schemas for a seamless experience.
-#### Empty warehouse credentials for new projects
+**Empty warehouse credentials for new projects**
Affected commands: `lightdash deploy --create`
When using this command to create a new project that is not a preview, the warehouse credentials will not be populated automatically. Users must update the warehouse credentials manually in the project settings page after the project is created.
+
## Global options
There are three global options that can be used with any Lightdash CLI command: [version](#version), [help](#help), and [verbose](#verbose).
@@ -96,13 +97,13 @@ For examples and command-specific options, click through the command in the tabl
|[`lightdash stop-preview`](/references/lightdash-cli#lightdash-stop-preview) | Shut down an open preview project |
|[`lightdash deploy`](/references/lightdash-cli#lightdash-deploy) | Compile and deploy a Lightdash project using your local project and credentials |
|[`lightdash refresh`](/references/lightdash-cli#lightdash-refresh) | Refresh Lightdash project with remote repository |
-|[`lightdash validate`](/references/lightdash-cli#lightdash-validate) | Validates content from your active project against your local project files |
-|[`lightdash generate`](/references/lightdash-cli#lightdash-generate) | Generates or updates schema.yml file(s) for the selected model(s) |
-|[`lightdash dbt run`](/references/lightdash-cli#lightdash-dbt-run) | Runs dbt and then generates or updates schema.yml file(s) for the selected model(s)|
-|[`lightdash generate-exposures`](/references/lightdash-cli#lightdash-generate-exposures) | [Experimental command] Generates a .yml file for Lightdash exposures |
-|[`lightdash download`](/references/lightdash-cli#lightdash-download) | Downloads all charts and dashboards from your Lightdash project as code |
-|[`lightdash upload`](/references/lightdash-cli#lightdash-upload) | Uploads all updates to charts and dashboards as code to your Lightdash project |
-
+|[`lightdash validate`](/references/lightdash-cli#lightdash-validate) | Validate content from your active project against your local project files |
+|[`lightdash generate`](/references/lightdash-cli#lightdash-generate) | Generate or update `schema.yml` file(s) for the selected model(s) |
+|[`lightdash dbt run`](/references/lightdash-cli#lightdash-dbt-run) | Run dbt, then generate or update `schema.yml` file(s) for the selected model(s) |
+|[`lightdash generate-exposures`](/references/lightdash-cli#lightdash-generate-exposures) | [Experimental command] Generates a YAML file for Lightdash exposures |
+|[`lightdash download`](/references/lightdash-cli#lightdash-download) | Download all charts and dashboards from your Lightdash project as code |
+|[`lightdash upload`](/references/lightdash-cli#lightdash-upload) | Upload charts and dashboards as code to your Lightdash project |
+|[`lightdash rename`](/references/lightdash-cli#lightdash-rename) | Rename model or field names across all your Lightdash content |
---
### `lightdash login`
@@ -365,6 +366,7 @@ All standard [dbt options](#dbt-options) work with `lightdash validate`.
- (default: ["charts","dashboards","tables"])
- Specify project elements to validate.
+
**Example:**
Validate only dashboards and use the existing compiled dbt manifest:
@@ -373,12 +375,14 @@ Validate only dashboards and use the existing compiled dbt manifest:
lightdash validate --only ["dashboards"] --skip-dbt-compile
```
+
### `lightdash generate`
Generates a new `schema.yml` file or updates existing `schema.yml` for selected model(s).
All standard [dbt options](#dbt-options) work with `lightdash generate`.
+
**Options:**
- `-y` or `--assume-yes`
@@ -387,6 +391,10 @@ All standard [dbt options](#dbt-options) work with `lightdash generate`.
- `--exclude-meta`
- (default: false)
- exclude Lightdash metadata from the generated .yml
+- `--preserve-column-case`
+ - (default: false)
+ - preserve original casing of column names in generated schema files
+
**Example:**
@@ -408,6 +416,7 @@ Generates a `schema.yml` file for Lightdash exposures.
This command does not support using dbt options.
+
**Options:**
- `--project-dir [path]`
@@ -416,6 +425,7 @@ This command does not support using dbt options.
- `--output [path]`
- The path where the output exposures YAML file will be written
+
**Example:**
Create or update YAML file called `lightdash-exposures.yml` in the current directory with all exposures in Lightdash:
@@ -424,12 +434,14 @@ Create or update YAML file called `lightdash-exposures.yml` in the current direc
lightdash generate-exposures --output ./lightdash-exposures.yml
```
+
### `lightdash dbt run`
Runs dbt and then generates or updates `schema.yml` file(s) for models that have columns missing or changed from the existing `schema.yml` files.
Any dbt option that works with `dbt run` will also work with `lightdash dbt run`. That includes all the [Lightdash dbt options](#dbt-options), and more ([see dbt run docs](https://docs.getdbt.com/reference/commands/run)).
+
**Options:**
- `--exclude-meta`
@@ -439,8 +451,12 @@ Any dbt option that works with `dbt run` will also work with `lightdash dbt run`
- assume yes to prompts (default: false)
- `-no` or `--assume-no`
- assume no to prompts (default: false)
+- `--preserve-column-case`
+ - (default: false)
+ - preserve original casing of column names in generated schema files
-**Examples:**
+
+**Example:**
Run a single model and create or update its `schema.yml` file:
@@ -448,6 +464,7 @@ Run a single model and create or update its `schema.yml` file:
lightdash dbt run --select mymodel
```
+
### `lightdash download`
Downloads all charts and dashboards from your Lightdash project as code. A `lightdash` directory is created in your working directory and all of the charts and dashboards are written there as .yml files.
@@ -456,6 +473,7 @@ E.g. if you're running this command inside your dbt directory (eg: `/home/javi/d
You can make changes to the code and upload these changes back to your Lightdash project. Content that's been downloaded as code can still be managed in the Lightdash UI.
+
**Options:**
- `--charts` or `-c`
@@ -467,6 +485,7 @@ You can make changes to the code and upload these changes back to your Lightdash
- `--project `
- download all charts and dashboards from a specific project. You can find the project UUID for a project from a Lightdash URL. E.g. here, the project UUID is `123-project-uuid` `https://app.lightdash.cloud/projects/123-project-uuid/`
+
**Examples:**
Download all charts and dashboards from your project.
@@ -478,7 +497,7 @@ lightdash download
Download a specific dashboard from your Lightdash project.
```bash
-lightdash upload -d https://app.lightdash.cloud/my-dashboard-url
+lightdash download -d https://app.lightdash.cloud/my-dashboard-url
```
Download all content from a project to the directory `/Users/katiehindson/lightdash/lightdash-analytics/`
@@ -507,6 +526,7 @@ Uploads charts and dashboards that you've made changes to from the `lightdash/`
If there have been changes made to a chart or dashboard in the application that is being uploaded from code, `lightdash upload` will overwrite the changes.
+
**Options:**
- `--force`
@@ -520,6 +540,7 @@ If there have been changes made to a chart or dashboard in the application that
- `--project `
- upload all charts and dashboards from a specific project. You can find the project UUID for a project from a Lightdash URL. E.g. here, the project UUID is `123-project-uuid` `https://app.lightdash.cloud/projects/123-project-uuid/`
+
**Examples:**
Upload all charts and dashboards in code from your `lightdash/` directory to your Lightdash project.
@@ -554,6 +575,60 @@ Upload all charts and dashboards from your `lightdash/` directory to a specific
lightdash upload --project 21eef0b9-5bae-40f3-851e-9554588e71a6
```
+
+### `lightdash rename`
+
+Rename model or field names across all content in your Lightdash project. This command will do a full find and replace on a field or table so all references in chart fields, dashboard filters, table calculations, custom metrics, etc. can be changed at once.
+
+
+**Arguments:**
+
+- `--type`
+ - Specify what you're renaming
+ - Accepted values: `field` or `model`
+- `--from`
+ - The current name of the table or field you want to change (this is the slug from your YAML definition, i.e. `num_users`)
+- `--to`
+ - The new name you want to use (must match the new slug in your YAML for this field or table, i.e. `count_distinct_user_id`)
+
+
+**Options:**
+
+- `--project`, `-p`
+ - Project UUID to target a specific project.
+ - (default: The most recent project you set with `lightdash config set-project`)
+- `--model`, `-m`
+ - The model to target for field renaming. This is only needed if the current field name is not unique in your project.
+- `--dry-run`
+ - List all content the rename action will change, no changes will be made.
+- `--list`
+ - List all charts and dashboards that were renamed after the command is complete.
+- `--assume-yes`, `-y`
+ - Assume yes to all prompts.
+
+
+**Examples:**
+
+Rename the field `num_users` to `count_distinct_user_id`.
+
+```bash
+lightdash rename --type field --from num_users --to count_distinct_user_id
+```
+
+Do a dry run of changing the table reference from `users_mart_v1` to `users`.
+
+```bash
+lightdash rename --type model --from users_mart_v1 --to users --dry-run
+```
+
+Rename the field `count` to `count_distinct_order_id` in the `orders` model and list all affected content when complete:
+
+```bash
+lightdash rename --type field --model orders --from count --to count_distinct_order_id --list
+```
+
+---
+
## dbt options
These are options from the dbt Core CLI that also work with some Lightdash CLI commands.
diff --git a/references/metrics.mdx b/references/metrics.mdx
index 44d02e9..a18b0e7 100644
--- a/references/metrics.mdx
+++ b/references/metrics.mdx
@@ -7,47 +7,65 @@ A metric is a value that describes or summarizes features from a collection of d
In Lightdash, metrics are used to summarize dimensions or, sometimes, other metrics.
+
## Adding metrics to your project using the `meta` tag.
-### 1. Using the column `meta` tag (Suggested)
+
+### 1. Using the column `meta` tag
To add a metric to Lightdash using the `meta` tag, you define it in your dbt project under the dimension name you're trying to describe/summarize.
```yaml
models:
- - name: my_model
+ - name: orders_model
columns:
- - name: user_id # dimension name of your metric
+ - name: user_id # dimension your metric is aggregating
meta:
metrics:
- num_unique_user_ids: # name of your metric
+ distinct_user_ids: # name of your metric
type: count_distinct # metric type
- num_user_ids:
- type: count
+ - name: revenue # dimension your metric is aggregating
+ meta:
+ metrics:
+ sum_revenue: # name of your metric
+ type: sum # metric type
```
+
+
Once you've got the hang of what these metrics look like, read more about the [metric types you can use below.](#metric-types)
+
### 2. Using the model `meta` tag
-Sometimes a metric references many columns, in these cases you can define the metric at the model level:
+Sometimes a metric references multiple columns, in these cases you can define the metric at the model level:
```yaml
-version: 2
-
models:
- - name: my_model
+ - name: orders_model
meta:
metrics:
- num_unique_user_ids:
- type: count_distinct
- sql: ${TABLE}.user_id
+ revenue_per_user:
+ type: number
+ sql: ${sum_revenue} / ${distinct_user_ids}
+ sum_total_paid:
+ type: sum
+ sql: ${revenue} + ${taxes_paid}
```
+
+ **Non-aggregate metrics** (`number`, `boolean`, etc.) can only reference other metrics in `sql:` since they are inserted directly into the generated SQL query without being wrapped in an aggregate function.
+
+ **Aggregate metrics** (`sum`, `count_distinct`, etc.) can only reference dimensions since they are wrapped in an aggregate function before being added to the generated SQL query. Wrapping an aggreate function in another aggregate function will cause an error.
+
+
+Read on to learn more about aggregate vs non-aggregate metrics!
+
## Metric Categories
Each metric type falls into one of these categories. The metric categories tell you whether the metric type is an aggregation and what type of fields the metric can reference:
+
### Aggregate metrics
Aggregate metric types perform (surprise, surprise) aggregations. Sums and averages are examples of aggregate metrics: they are measurements summarizing a collection of data points.
diff --git a/references/roles.mdx b/references/roles.mdx
index 6080d5b..b661465 100644
--- a/references/roles.mdx
+++ b/references/roles.mdx
@@ -16,8 +16,8 @@ Project Admins can invite users to their project and assign users or [groups](/r
| Action | Project Admin | Project Developer | Project Editor | Project Interactive Viewer | Project Viewer |
| :----------------------------------------------------: | :-------------------------------------------: | :-------------------------------------------: | :-------------------------------------------: | :-------------------------------------------: | :-------------------------------------------: |
-| View charts and dashboards | | | | | |
-| Export results visible in a chart to CSV | | | | | |
+| View charts and dashboards | | | | | |
+| Export results visible in a chart to CSV | | | | | |
| Export results visible in a chart to Google Sheets | | | | | |
| Export results to CSV and override the limit | | | | | |
| Export results to Google Sheets and override the limit | | | | | |
@@ -47,7 +47,7 @@ Organization Admins can assign roles to organization members, which gives access
| Edit content in **all** projects | | | | | | |
| Create new projects | | | | | | |
| Create a preview from a project | | | | | | |
-| Update **all** project connections | | | | | | |
+| Update **all** project connections | | | | | | |
| Admin for **all** projects | | | | | | |
| Invite users to organization | | | | | | |
| Manage organization access and permissions | | | | | | |
diff --git a/references/spaces.mdx b/references/spaces.mdx
index 402c99e..91bb9c6 100644
--- a/references/spaces.mdx
+++ b/references/spaces.mdx
@@ -3,45 +3,43 @@ title: "Spaces"
description: "Once you've used Lightdash for a while, your team will probably end up with a lot of saved charts and dashboards. Spaces let you organize your saved charts and dashboards."
---
-Spaces are kind of like folders except you can't put a Space inside of a Space (no nesting ). All saved charts and dashboards exist in a Space and can only be in one Space at a time.
+Spaces are kind of like folders. All saved charts and dashboards exist in a Space and can only be in one Space at a time.
-
-
-
+
To access Spaces, you can either select a Space from the drop-down list in `Browse` or you can click on the Lightdash icon and select your Space from the homepage.
-
-
-
+
## Moving items between Spaces
-To move a saved chart or dashboard between Spaces, you can click on the three dot menu (`...`) to the right of the item and pick the `Move to Space` action.
+To move a saved chart, dashboard or space between Spaces, you can click on the three dot menu (`...`) to the right of the item and pick the `Move` action. Or select items using checkboxes on the left and click `Move to Space`.
- 
+ 
+
+
+ 
-You can also add items to a Space from within the Space. Just click on the `Add` button by the saved charts or the dashboards section of the page. If you select an item that's in another Space, it will get moved to the Space you're adding it to.
-
+
+
- 
+ 
+
-You select multiple items to add at the same time to your Space.
+You can also add items to a Space from within the Space. Just click on the `Add` button on the space page.
-
- 
-
+
## Updating and deleting Spaces
-You can rename or delete your Space on the homescreen by clicking on the three-dot menu (`...`) for the Space.
+You can rename or delete your Space from All Spaces view or on the homescreen by clicking on the three-dot menu (`...`) for the Space.
- 
+ 
@@ -53,9 +51,9 @@ Deleting a Space will delete all of the content in that Space.
## Managing access to a Space
-By default, when you create a Space, it is restricted so only you can access it. You can edit a Space to make it Restricted Access or Public Access.
+By default, when you create a Space, it is restricted so only you can access it (however, if you create a nested Space, it automatically inherits permissions from its parent). You can edit a Space to make it Restricted Access or Public Access.
-To edit access to a Space, navigate into the Space, then click the `share` button. From there, you can choose to make a space `Restricted Access` or `Public Access`.
+To edit access to a Space, navigate into the Space, then click the `share` button. From there, you can choose to make a space `Restricted Access` or `Public Access` (Only top level space access can be edited, nested spaces inherit permissions from their parent spaces).
diff --git a/references/sql-runner.mdx b/references/sql-runner.mdx
index e4bb09a..1be1f3a 100644
--- a/references/sql-runner.mdx
+++ b/references/sql-runner.mdx
@@ -5,18 +5,18 @@ description: "The SQL runner is used to build ad-hoc queries or charts using tot
A query built in the SQL runner can be:
-* used to power a single saved chart
-* turned into a virtual view so it becomes a reusable table
-* written back to dbt as a model
+- used to power a single saved chart
+- turned into a virtual view so it becomes a reusable table
+- written back to dbt as a model
-Only users with [`developer` or `admin` access](/references/roles) can use the SQL runner.
+Only users with [``developer or admin access``](/references/roles) can use the SQL runner.
## Getting started with the SQL Runner
-The SQL Runner can be accessed from the `New` --> `Query using SQL Runner` option in your navigation bar.
+The SQL Runner can be accessed from the `New` --\> `Query using SQL Runner` option in your navigation bar.
- 
+ 
Once you're in the SQL Runner, you'll see four key components:
@@ -27,7 +27,7 @@ Once you're in the SQL Runner, you'll see four key components:
4. The results from your latest SQL query.
- 
+ 
To build a query in the SQL Runner, just write your query in the SQL query builder, then hit `Run query` to see the results.
@@ -35,14 +35,14 @@ To build a query in the SQL Runner, just write your query in the SQL query build
You can access your **Query history** from your session by clicking on the `SQL Query history` button beside `Run query`.
- 
+ 
Once you've run your query, you can either:
-1. [Build and save a **Chart**](#building-charts-in-the-sql-runner)
-2. [Create a **Virtual View** so your query becomes a reusable table in Lightdash](/references/virtual-views)
-3. [**Write-back to dbt** so your query is saved as a governed model.](/references/dbt-write-back)
+1. [**Build and save a Chart**](#building-charts-in-the-sql-runner)
+2. [**Create a Virtual View so your query becomes a reusable table in Lightdash**](/references/virtual-views)
+3. [**Write-back to dbt so your query is saved as a governed model.**](/references/dbt-write-back)
4. Click the link icon in the top-right to share your query draft with a coworker (or save it yourself to return to later).
## Saved charts in the SQL Runner
@@ -51,15 +51,17 @@ Once you've run your query, you can build a chart by clicking on the `chart` tab
The charts in the SQL Runner are built from the data that you generated in your query. The chart builder automatically aggregates the data from your query results using the aggregation type that you choose. Depending on the column type, the aggregation options are:
-* count (which is a distinct count and will ignore duplicates)
-* any (which will count and include duplicates)
-* sum
-* average
-* max
-* min
+- count (which is a distinct count and will ignore duplicates)
+- any (which will count and include duplicates)
+- sum
+- average
+- max
+- min
- 
+ 
Once you've configured your chart, you can save it, add it to a space, and add it to a dashboard by hitting `save chart`.
+
+SQL runner charts on a dashbaord can be filtered in the UI. See the [filter documentation](/guides/limiting-data-using-filters) for more information.
\ No newline at end of file
diff --git a/references/tables.mdx b/references/tables.mdx
index dcd16e8..8a0f484 100644
--- a/references/tables.mdx
+++ b/references/tables.mdx
@@ -1,7 +1,7 @@
---
title: "Tables reference"
description: "You can run queries against the tables in your Lightdash project."
-sidebarTitle: Tables
+sidebarTitle: "Tables"
---
Tables are built from dbt models (either one, or many joined together).
@@ -46,18 +46,19 @@ models:
Here are all of the properties you can customize:
-| Property | Value | Note |
-| :--------------------------------------------------------- | :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
-| label | string | Custom label. This is what you'll see in Lightdash instead of the Table name. |
-| [order\_fields\_by](#order-fields-by) | 'index' or 'label' | How the fields will be sorted in the sidebar. [Read more about the order rules in here](#order-fields-by) |
-| [joins](/references/joins) | array | Join logic to join other data models to the Table. [Read more about joins in here.](/references/joins) |
-| [metrics](/references/metrics#2-using-the-model-meta-tag) | object | Model metrics. [Read more about model metrics in here](/references/metrics#2-using-the-model-meta-tag) |
-| [group\_label](#group-label) | string | Group tables in the sidebar. [Read more about the group label in here](#group-label) |
-| [sql\_filter](#sql-filter) | string | A permanent filter that will always be applied when querying this table directly. Read more about sql\_filter [below](#sql-filter) |
-| [sql\_where](#sql-filter) | string | Alias for sql\_filter |
-| [required\_attributes](#required-attributes) | Object with \{ user_attribute, value } | Limits access to users with those attributes. [Read more about user attributes in here](/references/user-attributes) |
-| group\_details | Object with \{ label, description } | Describes the groups for dimensions and metrics |
-| [required\_filters](#required-filters) | Array of \{filter field: value} | Dimension filters that will be applied when no other filter on those dimension exists. Read more about required\_filters [below](#required-filters) |
+| Property | Value | Note |
+| :-------------------------------------------------------- | :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- |
+| label | string | Custom label. This is what you'll see in Lightdash instead of the Table name. |
+| [order_fields_by](#order-fields-by) | 'index' or 'label' | How the fields will be sorted in the sidebar. [Read more about the order rules in here](#order-fields-by) |
+| [joins](/references/joins) | array | Join logic to join other data models to the Table. [Read more about joins in here.](/references/joins) |
+| [metrics](/references/metrics#2-using-the-model-meta-tag) | object | Model metrics. [Read more about model metrics in here](/references/metrics#2-using-the-model-meta-tag) |
+| [group_label](#group-label) | string | Group tables in the sidebar. [Read more about the group label in here](#group-label) |
+| [sql_filter](#sql-filter) | string | A permanent filter that will always be applied when querying this table directly. Read more about sql_filter [below](#sql-filter) |
+| [sql_where](#sql-filter) | string | Alias for sql_filter |
+| [required_attributes](#required-attributes) | Object with \{ user_attribute, value } | Limits access to users with those attributes. [Read more about user attributes in here](/references/user-attributes) |
+| group_details | Object with \{ label, description } | Describes the groups for dimensions and metrics |
+| [default_filters](#default-filters) | Array of \{ filter field value } | Dimension filters that will be applied when no other filter on those dimension exists. Read more about default_filters [below](#default-filters) |
+
### If you've added a new dbt model to your project, you need to do `dbt run` \+ `dbt refresh` before it will appear in Lightdash
@@ -65,8 +66,8 @@ Lightdash gets information about your data models from dbt. But it gets informat
This means that if you add a new dbt model to your project or update a model so that you're making changes to the table it generates, then you need to do two things before your changes will appear in Lightdash:
-1. **Materialize the new table/changes to the table (using `dbt run`).** You basically want the data in your data warehouse to be the new table you're expecting. So you need to do `dbt run` to update the table from the data model you just changed.
-2. **Click `dbt refresh` in Lightdash.** This will re-sync your dbt project in Lightdash so that any changes you made to your dbt models is shown in Lightdash (e.g. adding a new table).
+1. **`Materialize the new table/changes to the table (using dbt run).`** You basically want the data in your data warehouse to be the new table you're expecting. So you need to do `dbt run` to update the table from the data model you just changed.
+2. **`Click dbt refresh in Lightdash.`** This will re-sync your dbt project in Lightdash so that any changes you made to your dbt models is shown in Lightdash (e.g. adding a new table).
### Order fields by
@@ -87,20 +88,20 @@ models:
So, in the example above, the fields in the sidebar for "My Table" would appear in the order:
-* user\_id
-* product\_id
-* account\_id
+- user_id
+- product_id
+- account_id
Instead of being listed alphabetically.
Here are some other things worth mentioning about the `order_fields_by` parameter:
-* By default, `order_fields_by` is set to `label`, which means that your fields will appear in the table listed alphabetically.
-* Since metrics can be declared in multiple places within your .yml (as a dbt metric, in the model `meta` tag, under a dimension's `meta`), we force the following order on metrics if you set `order_fields_by` to `index`:
- * dbt metrics appear first
- * then, metrics defined in the model's `meta`
- * then, metrics defined in the dimensions' `meta`
-* Group labels inherit the index of the first dimension that use them.
+- By default, `order_fields_by` is set to `label`, which means that your fields will appear in the table listed alphabetically.
+- Since metrics can be declared in multiple places within your .yml (as a dbt metric, in the model `meta` tag, under a dimension's `meta`), we force the following order on metrics if you set `order_fields_by` to `index`:
+ - dbt metrics appear first
+ - then, metrics defined in the model's `meta`
+ - then, metrics defined in the dimensions' `meta`
+- Group labels inherit the index of the first dimension that use them.
### Group label
@@ -108,12 +109,12 @@ If you set this property, the table will be grouped in the sidebar with other ta
The tables in your sidebar will appear in the following order:
-* Group labels appear first, alphabetically
-* Ungrouped tables appear after the grouped tables in the sidebar, alphabetically
-* Tables within the groups are also ordered alphabetically
+- Group labels appear first, alphabetically
+- Ungrouped tables appear after the grouped tables in the sidebar, alphabetically
+- Tables within the groups are also ordered alphabetically
- 
+ 
### SQL filter (row-level security)
@@ -156,18 +157,18 @@ models:
For example:
-* Table A is joined to Table B
-* Table B has a `sql_filter` applied to it
-* A user queries Table A and adds a field from the joined table (Table B) to their query
-* the `sql_filter` from Table B will **not** be applied to the query (you would need to add this as a `sql_filter` to Table A directly for it to apply)
+- Table A is joined to Table B
+- Table B has a `sql_filter` applied to it
+- A user queries Table A and adds a field from the joined table (Table B) to their query
+- the `sql_filter` from Table B will **not** be applied to the query (you would need to add this as a `sql_filter` to Table A directly for it to apply)
##### If you reference a dimension from a joined table in your `sql_filter`, the referenced table will always be joined in your queries.
For example:
-* You have Table A which is joined to Table B
-* In Table A, you've added a `sql_filter: ${TABLE}.sales_region = 'EMEA' OR ${table_b}.sales_region IS NULL`
-* Table B will always be joined to Table A in your queries (even if there are no fields from Table B selected in your results table)
+- You have Table A which is joined to Table B
+- In Table A, you've added a `sql_filter: ${TABLE}.sales_region = 'EMEA' OR ${table_b}.sales_region IS NULL`
+- Table B will always be joined to Table A in your queries (even if there are no fields from Table B selected in your results table)
### Required attributes
@@ -186,27 +187,21 @@ models:
If a user without access to this table runs a query that contains this table, they will get a `Forbidden` error.
-## Required Filters
-
-Use `required_filters` to define filters on Dimensions that will be applied when no other user-defined filter on those Dimensions exists. This allows to enforce a default filter on a Dimension when querying a table. This defined `required_filters` will be replaced by any user-defined filter on the same Dimension making sure at least one filter is applied to the Dimension.
+## Default filters
-This is particularly useful when you want to enforce a default filter to save on query time and potential warehouse costs.
-
-
+Use `default_filters` to define filters on Dimensions that will be applied when no other user-defined filter on those Dimensions exists. Default filters will show apply to tables on load and can be populated with a pre-determined value. User them to suggest to users the kind of filters they might want to consider, or provide a default filtered view of a table that can be changed if needed.
-A required filter's field reference can't be changed, but its operator (is, is not, etc.) and value can be changed when querying the table.
-
+An optional `required` flag can be added - in which case the filter _cannot_ be removed. This can be particulalry useful if you have a large table and want to force users to filter on a partitioned date.
-For example, the defined `required_filters` on the date Dimension will be in place unless there is another user-defined filter on the date Dimension when querying the orders table, like this:
+Below you can see there is a default filter with the optional required flag, that will have show the last 14 days of data by default.
```yaml
-version: 2
-
models:
- name: orders
meta:
- required_filters:
+ default_filters:
- date: 'inThePast 14 days'
+ required: true
columns:
- name: date
description: 'Order date'
@@ -215,15 +210,17 @@ models:
type: date
```
-### If you have many filters in your list, they will be joined using `AND`
+
+ A _required_ filter's field reference can't be changed, but its operator (is, is not, etc.) and value can be changed when querying the table from the UI
+
-For example:
+### If you have many filters in your list, they will be joined using `AND`
```yaml
version: 2
- name: orders
meta:
- required_filters:
+ default_filters:
- date: 'inThePast 14 days'
- status: "completed"
columns:
@@ -239,25 +236,43 @@ version: 2
type: string
```
-In the example above, the `orders` table will have a default filter of `date` in the past 14 days **and** `status` completed.
+In the example above, the `orders` table will have a default filter of `date` in the past 14 days **and** `status` completed. Both can be removed by the user, as the `required` flag is not present.
+
+Note that we do also support a _legacy_ structure for defining required filters, see below:
+
+```yaml
+version: 2
+
+models:
+ - name: orders
+ meta:
+ required_filters:
+ - date: 'inThePast 14 days'
+ columns:
+ - name: date
+ description: 'Order date'
+ meta:
+ dimension:
+ type: date
+```
### Available filter types
| Type | Example (in English) | Example (as code) |
-| :----------------------------- | :---------------------------------------------- | :--------------------------- |
-| is | User name is equal to katie | user\_name: "katie" |
-| is not | User name is not equal to katie | user\_name: "!katie" |
-| contains | User name contains katie | user\_name: "%katie%" |
-| does not contain | User name does not contain katie | user\_name: "!%katie%" |
-| starts with | User name starts with katie | user\_name: "katie%" |
-| ends with | User name ends with katie | user\_name: "%katie" |
-| is greater than (number) | Number of orders is greater than 4 | num\_orders: "> 4" |
+| :---------------------------- | :--------------------------------------------- | :-------------------------- |
+| is | User name is equal to katie | user_name: "katie" |
+| is not | User name is not equal to katie | user_name: "\!katie" |
+| contains | User name contains katie | user_name: "%katie%" |
+| does not contain | User name does not contain katie | user_name: "\!%katie%" |
+| starts with | User name starts with katie | user_name: "katie%" |
+| ends with | User name ends with katie | user_name: "%katie" |
+| is greater than (number) | Number of orders is greater than 4 | num_orders: "\> 4" |
| in the past (date) (interval) | Date is before x (days / months / years) | date: "inThePast 14 months" |
| in the next (date) (interval) | Date is after x (days / months / years) | date: "inTheNext 14 days" |
-| is greater than or equal to | Number of orders is greater than or equal to 4 | num\_orders: ">= 4" |
-| is less than | Number of orders is less than 4 | num\_orders: "< 4" |
-| is less than or equal to | Number of orders is less than or equal to 4 | num\_orders: "\<= 4" |
+| is greater than or equal to | Number of orders is greater than or equal to 4 | num_orders: "\>= 4" |
+| is less than | Number of orders is less than 4 | num_orders: "\< 4" |
+| is less than or equal to | Number of orders is less than or equal to 4 | num_orders: "\<= 4" |
| is null | Status is NULL | status: "null" |
-| is not null | Status is not NULL | status: "!null" |
-| is \[boolean\] | Is complete is true | is\_complete: "true" |
-| is not \[boolean\] | Is complete is false or null | is\_complete: "!true" |
+| is not null | Status is not NULL | status: "\!null" |
+| is [boolean] | Is complete is true | is_complete: "true" |
+| is not [boolean] | Is complete is false or null | is_complete: "\!true" |
\ No newline at end of file
diff --git a/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage.mdx b/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage.mdx
index 76093fd..8600fec 100644
--- a/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage.mdx
+++ b/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage.mdx
@@ -5,9 +5,8 @@ sidebarTitle: "External storage"
On Lightdash, we generate some files like:
-- Images for Slack unfurl
-- Images on scheduled deliveries
-- Results on CSV format.
+- Images for Slack unfurl and scheduled deliveries
+- Results on JSONL/CSV/Excel format
These files need to be stored in a S3 Compatible Cloud storage. Some options are GCP Buckets, S3 Storage and MinIO.
@@ -64,19 +63,21 @@ MinIO needs path style bucket URLs, for this you will need to set `S3_FORCE_PATH
## Configure Lightdash to use S3 credentials
-Now you have the bucket and the S3 credentials for your cloud storage, you can provide the following ENV variables to Lightdash so it can use the cloud storage using S3 library
+To enable Lightdash to use your S3 bucket for cloud storage, you'll need to set the following environment variables:
```bash
-S3_REGION
-S3_ACCESS_KEY
-S3_SECRET_KEY
-S3_BUCKET
-S3_ENDPOINT
-S3_EXPIRATION_TIME
+S3_ENDPOINT # required
+S3_REGION # required
+S3_BUCKET # required
+S3_ACCESS_KEY # optional if using IAM role
+S3_SECRET_KEY # optional if using IAM role
+S3_EXPIRATION_TIME # optional, defaults to 259200 seconds (3 days)
```
-We also support IAM roles. If you don't provide `S3_ACCESS_KEY` and `S3_SECRET_KEY` the S3 library will try to use IAM roles, see this [AWS documentation](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html) for more details.
+For a comprehensive list of all possible S3-related environment variables and other configurations, please visit the [Environment Variables documentation](https://docs.lightdash.com/self-host/customize-deployment/environment-variables#s3).
-The expiration time is optional and defaults to 259200 (seconds).
+### Using IAM roles
-If you try to customize this expiration time, you should keep in mind that link to your object url will be available for the maximum of 7 days due to signed url limitations if you use IAM role to generate it.
\ No newline at end of file
+Lightdash also supports authentication via IAM roles. If you omit the `S3_ACCESS_KEY` and `S3_SECRET_KEY` variables, the S3 library will automatically attempt to use IAM roles. For more details on how this works, refer to the [AWS SDK for JavaScript documentation on setting credentials in Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html).
+
+If you are using an IAM role to generate signed URLs, be aware that these URLs have a maximum validity of 7 days due to AWS limitations, independently of the `S3_EXPIRATION_TIME` configuration.
diff --git a/self-host/customize-deployment/environment-variables.mdx b/self-host/customize-deployment/environment-variables.mdx
index cd389b0..a95dfd5 100644
--- a/self-host/customize-deployment/environment-variables.mdx
+++ b/self-host/customize-deployment/environment-variables.mdx
@@ -87,32 +87,43 @@ These variables enable you to control Single Sign On (SSO) functionality.
These variables allow you to configure [S3 Object Storage](/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage).
-| Variable | Description | Required? | Default |
-| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :---------: |
-| `S3_ENDPOINT` | S3 endpoint for storing cached results | | |
-| `S3_BUCKET` | Name of the S3 bucket for storing files | | |
-| `S3_REGION` | Region where the S3 bucket is located | | |
-| `S3_ACCESS_KEY` | Access key for authenticating with the S3 bucket | | |
-| `S3_SECRET_KEY` | Secret key for authenticating with the S3 bucket | | |
-| `S3_EXPIRATION_TIME` | Expiration time for scheduled deliveries files | | 259200 (3d) |
-| `S3_FORCE_PATH_STYLE` | Force path style addressing, needed for MinIO setup e.g. `http://your.s3.domain/BUCKET/KEY` instead of `http://BUCKET.your.s3.domain/KEY` | | `false` |
+| Variable | Description | Required? | Default |
+| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :------------: |
+| `S3_ENDPOINT` | S3 endpoint for storing results | | |
+| `S3_BUCKET` | Name of the S3 bucket for storing files | | |
+| `S3_REGION` | Region where the S3 bucket is located | | |
+| `S3_ACCESS_KEY` | Access key for authenticating with the S3 bucket | | |
+| `S3_SECRET_KEY` | Secret key for authenticating with the S3 bucket | | |
+| `S3_EXPIRATION_TIME` | Expiration time for scheduled deliveries files | | 259200 (3d) |
+| `S3_FORCE_PATH_STYLE` | Force path style addressing, needed for MinIO setup e.g. `http://your.s3.domain/BUCKET/KEY` instead of `http://BUCKET.your.s3.domain/KEY` | | `false` |
+| `RESULTS_S3_BUCKET` | Name of the S3 bucket used for storing query results | | `S3_BUCKET` |
+| `RESULTS_S3_REGION` | Region where the S3 query storage bucket is located | | `S3_REGION` |
+| `RESULTS_S3_ACCESS_KEY`| Access key for authenticating with the S3 query storage bucket | | `S3_ACCESS_KEY`|
+| `RESULTS_S3_SECRET_KEY`| Secret key for authenticating with the S3 query storage bucket | | `S3_SECRET_KEY`|
## Cache
+
+ Note that you will need an Enterprise License Key for this functionality.
+
+
| Variable | Description | Required? | Default |
| :---------------------------- | :------------------------------------------------------------------------- | :-------: | :-------------: |
| `RESULTS_CACHE_ENABLED` | Enables caching for chart results | | `false` |
| `AUTOCOMPLETE_CACHE_ENABLED` | Enables caching for filter autocomplete results | | `false` |
-| `RESULTS_CACHE_S3_BUCKET` | Name of the S3 bucket used for caching query results | | `S3_BUCKET` |
-| `RESULTS_CACHE_S3_REGION` | Region where the S3 bucket is located | | `S3_REGION` |
-| `RESULTS_CACHE_S3_ACCESS_KEY` | Access key for authenticating with the S3 bucket | | `S3_ACCESS_KEY` |
-| `RESULTS_CACHE_S3_SECRET_KEY` | Secret key for authenticating with the S3 bucket | | `S3_SECRET_KEY` |
| `CACHE_STALE_TIME_SECONDS` | Defines how long cached results remain valid before being considered stale | | 86400 (24h) |
- Note that you will need an Enterprise License Key for this functionality.
+ These variables are **deprecated**; use the `RESULTS_S3_*` versions instead.
+| Variable | Description | Required? | Default |
+| :---------------------------- | :------------------------------------------------------------------------- | :-------: | :-------------: |
+| `RESULTS_CACHE_S3_BUCKET` | Deprecated - use RESULTS_S3_BUCKET | | `S3_BUCKET` |
+| `RESULTS_CACHE_S3_REGION` | Deprecated - use RESULTS_S3_REGION | | `S3_REGION` |
+| `RESULTS_CACHE_S3_ACCESS_KEY` | Deprecated - use RESULTS_S3_ACCESS_KEY | | `S3_ACCESS_KEY` |
+| `RESULTS_CACHE_S3_SECRET_KEY` | Deprecated - use RESULTS_S3_SECRET_KEY | | `S3_SECRET_KEY` |
+
## Logging
| Variable | Description | Required? | Default |
@@ -168,10 +179,6 @@ These variables enable you to configure the [AI Analyst functionality](guides/ai
| `OPENAI_EMBEDDING_MODEL_NAME` | Required for AI Analyst | | |
| `AI_COPILOT_ENABLED` | Required for AI Analyst | | |
| `AI_COPILOT_EMBEDDING_SEARCH_ENABLED` | Required for AI Analyst | | |
-| `LANGCHAIN_TRACING_V2` | Required for AI Analyst | | |
-| `LANGCHAIN_ENDPOINT` | Required for AI Analyst | | |
-| `LANGCHAIN_API_KEY` | Required for AI Analyst | | |
-| `LANGCHAIN_PROJECT` | Required for AI Analyst | | |
### Slack Integration
@@ -204,4 +211,46 @@ These variables allow you to customize the default appearance settings for your
| Variable | Description | Required? | Default |
| :------------------------------ | :---------------------------------------------------------------------------------------- | :-------: | :-----: |
| `OVERRIDE_COLOR_PALETTE_NAME` | Name of the default color palette | | |
-| `OVERRIDE_COLOR_PALETTE_COLORS` | Comma-separated list of hex color codes for the default color palette (must be 20 colors) | | |
\ No newline at end of file
+| `OVERRIDE_COLOR_PALETTE_COLORS` | Comma-separated list of hex color codes for the default color palette (must be 20 colors) | | |
+
+### Initialize instance
+
+When a new Lightdash instance is created, and there are no orgs and projects. You can initialize a new org and project using ENV variables to simplify the deployment process.
+
+
+ Currently we only support Databricks project types and Github dbt configuration.
+
+
+| Variable | Description | Required? | Default |
+| :----------------------------------- | :------------------------------------------------------------------------------------------------ | :-------------------------------------------: | :----------: |
+| `LD_SETUP_ADMIN_NAME` | Name of the admin user for initial setup | | `Admin User` |
+| `LD_SETUP_ADMIN_EMAIL` | Email of the admin user for initial setup | | |
+| `LD_SETUP_ORGANIZATION_EMAIL_DOMAIN` | Email domain for the organization whitelisting | | |
+| `LD_SETUP_ORGANIZATION_DEFAULT_ROLE` | Default role for new organization members | | `viewer` |
+| `LD_SETUP_ORGANIZATION_NAME` | Name of the organization | | |
+| `LD_SETUP_ADMIN_API_KEY` | API key for the admin user | | |
+| `LD_SETUP_API_KEY_EXPIRATION` | Number of days until API key expires (0 for no expiration) | | `30` |
+| `LD_SETUP_PROJECT_NAME` | Name of the project | | |
+| `LD_SETUP_PROJECT_CATALOG` | Catalog name for Databricks project | | |
+| `LD_SETUP_PROJECT_SCHEMA` | Schema/database name for the project | | |
+| `LD_SETUP_PROJECT_HOST` | Hostname for the Databricks server | | |
+| `LD_SETUP_PROJECT_HTTP_PATH` | HTTP path for Databricks connection | | |
+| `LD_SETUP_PROJECT_PAT` | Personal access token for Databricks | | |
+| `LD_SETUP_START_OF_WEEK` | Day to use as start of week | | `SUNDAY` |
+| `LD_SETUP_PROJECT_COMPUTE` | JSON string with Databricks compute configuration like `{"name": "string", "httpPath": "string"}` | | |
+| `LD_SETUP_DBT_VERSION` | Version of dbt to use (eg: v1.8) | | `latest` |
+| `LD_SETUP_GITHUB_PAT` | GitHub personal access token | | |
+| `LD_SETUP_GITHUB_REPOSITORY` | GitHub repository for dbt project | | |
+| `LD_SETUP_GITHUB_BRANCH` | GitHub branch for dbt project | | |
+| `LD_SETUP_GITHUB_PATH` | Subdirectory path within GitHub repository | | `/` |
+
+
+ In order to login as the admin user using SSO, you must enable the following ENV variable too:
+
+ ```typescript
+ AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true
+ ```
+
+ This will alow you to link your SSO account with the email provided without using an invitation code. \
+ This email will be trusted, and any user with an OIDC account with that email will access the admin user.
+
\ No newline at end of file
diff --git a/self-host/self-host-lightdash.mdx b/self-host/self-host-lightdash.mdx
index ecb5d51..3423b0d 100644
--- a/self-host/self-host-lightdash.mdx
+++ b/self-host/self-host-lightdash.mdx
@@ -40,8 +40,9 @@ kubectl create namespace lightdash
At minimum you should configure:
* `secrets.LIGHTDASH_SECRET` - this variable is used by Lightdash to encrypt data at rest in the database. You must keep this secret. If this is lost, you will not be able to access your data in Lightdash.
+* `config.S3_REGION`, `config.S3_BUCKET`, `config.S3_ENDPOINT`, `secrets.S3_ACCESS_KEY` and `secrets.S3_SECRET_KEY` - These variables are for configuring external object storage with S3. For detailed information, refer to the [external object storage documentation](/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage).
* `service.type` - by default the Lightdash UI and API is exposed on a `ClusterIP` service. This means that it is only accessible from within the Kubernetes cluster. If you want to access Lightdash from outside the cluster, you can change this to `LoadBalancer` or `NodePort`. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) for more information.
-* `SITE_URL` - if you know the URL that Lightdash will be accessible at, you can set this variable. This will ensure that all links in Lightdash are correct. If you don't know the URL yet, you can leave this blank and update it later.
+* `config.SITE_URL` - if you know the URL that Lightdash will be accessible at, you can set this variable. This will ensure that all links in Lightdash are correct. If you don't know the URL yet, you can leave this blank and update it later.
Example `values.yaml` file containing our configuration:
@@ -49,9 +50,14 @@ Example `values.yaml` file containing our configuration:
# values.yaml
secrets:
LIGHTDASH_SECRET: notverysecret
+ S3_ACCESS_KEY: secret # not required if using IAM role
+ S3_SECRET_KEY: secret # not required if using IAM role
configMap:
SITE_URL: https://lightdash.mycompany.com
+ S3_REGION: us
+ S3_BUCKET: lightdash
+ S3_ENDPOINT: https://storage.provider.com
service:
type: NodePort
@@ -80,12 +86,15 @@ Visit your `SITE_URL` to access Lightdash!
Now you have a working Lightdash instance, you can customise it to your needs. The following docs cover the most common configuration options, including those we recommend before going to production:
+**Required configuration**
+
+* [Configure Lightdash to use external object storage](/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage)
+
**Recommended for production usage**
* [Secure Lightdash with HTTPS](/self-host/customize-deployment/secure-lightdash-with-https)
* [Configure Lightdash to use an external database](/self-host/customize-deployment/configure-lightdash-to-use-an-external-database)
* [Configure SMTP for email notifications](/self-host/customize-deployment/configure-smtp-for-lightdash-email-notifications)
-* [Configure Lightdash to use external object storage](/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage)
* [Resource recommendations](/self-host/customize-deployment/recommended-resources/)
**Optional configuration**