From c8ae8f884c7b114553576cb654e5c04c35924189 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:54:12 +0000 Subject: [PATCH 01/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 53 ++++++++++++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 15 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 5ba7f14d..02200828 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -13,21 +13,44 @@ In Lightdash, metrics are used to summarize dimensions or, sometimes, other metr 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: orders_model - columns: - - name: user_id # dimension your metric is aggregating - meta: - metrics: - distinct_user_ids: # name of your metric - type: count_distinct # metric type - - name: revenue # dimension your metric is aggregating - meta: - metrics: - sum_revenue: # name of your metric - type: sum # metric type -``` + + + ```yaml + models: + - name: orders_model + columns: + - name: user_id # dimension your metric is aggregating + meta: + metrics: + distinct_user_ids: # name of your metric + type: count_distinct # metric type + - name: revenue # dimension your metric is aggregating + meta: + metrics: + sum_revenue: # name of your metric + type: sum # metric type + ``` + + + ```yaml + models: + - name: orders_model + columns: + - name: user_id # dimension your metric is aggregating + config: + meta: + metrics: + distinct_user_ids: # name of your metric + type: count_distinct # metric type + - name: revenue # dimension your metric is aggregating + config: + 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) From 3f41001f4a623de8c20632c4d954598c38c79595 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:54:23 +0000 Subject: [PATCH 02/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 43 ++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 02200828..2b570765 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -58,18 +58,37 @@ Once you've got the hang of what these metrics look like, read more about the [m Sometimes a metric references multiple columns, in these cases you can define the metric at the model level: -```yaml -models: - - name: orders_model - meta: - metrics: - revenue_per_user: - type: number - sql: ${sum_revenue} / ${distinct_user_ids} - sum_total_paid: - type: sum - sql: ${revenue} + ${taxes_paid} -``` + + + ```yaml + models: + - name: orders_model + meta: + metrics: + revenue_per_user: + type: number + sql: ${sum_revenue} / ${distinct_user_ids} + sum_total_paid: + type: sum + sql: ${revenue} + ${taxes_paid} + ``` + + + ```yaml + models: + - name: orders_model + config: + meta: + metrics: + 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. From 1ea83514dabb1106e89d1663afbe4705346b62d8 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:54:43 +0000 Subject: [PATCH 03/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 108 ++++++++++++++++++++++++++++------------- 1 file changed, 75 insertions(+), 33 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 2b570765..5eb5592a 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -132,40 +132,82 @@ Post calculation metrics are computed after aggregate and non-aggregate metrics You can customize your metrics in your dbt model's YAML file. Here's an example of the properties used in defining a metric: -```yaml -models: - - name: sales_stats - meta: - joins: - - join: web_sessions - sql_on: ${web_sessions.date} = ${sales_stats.date} - group_details: - product_details: - label: Product Details - description: 'Fields that have information about the products in the basket.' - item_details: - label: Item Details - description: 'Fields that have information about the items in the basket.' - columns: - - name: revenue - description: 'Total estimated revenue in GBP based on forecasting done by the finance team.' + + + ```yaml + models: + - name: sales_stats meta: - metrics: - total_revenue: - label: 'Total revenue GBP' - type: SUM - description: 'Total revenue in GBP' - sql: 'IF(${revenue} IS NULL, 10, ${revenue})' - groups: ['product_details', 'item_details'] # this would add the metric to a nested group: `product details` --> `item details` - hidden: false - format: '[$£]#,##0.00' # GBP rounded to two decimal points - show_underlying_values: - - revenue - - forecast_date - - web_sessions.session_id # field from joined table - filters: - - is_adjusted: true -``` + joins: + - join: web_sessions + sql_on: ${web_sessions.date} = ${sales_stats.date} + group_details: + product_details: + label: Product Details + description: 'Fields that have information about the products in the basket.' + item_details: + label: Item Details + description: 'Fields that have information about the items in the basket.' + columns: + - name: revenue + description: 'Total estimated revenue in GBP based on forecasting done by the finance team.' + meta: + metrics: + total_revenue: + label: 'Total revenue GBP' + type: SUM + description: 'Total revenue in GBP' + sql: 'IF(${revenue} IS NULL, 10, ${revenue})' + groups: ['product_details', 'item_details'] # this would add the metric to a nested group: `product details` --> `item details` + hidden: false + format: '[$£]#,##0.00' # GBP rounded to two decimal points + show_underlying_values: + - revenue + - forecast_date + - web_sessions.session_id # field from joined table + filters: + - is_adjusted: true + ``` + + + ```yaml + models: + - name: sales_stats + config: + meta: + joins: + - join: web_sessions + sql_on: ${web_sessions.date} = ${sales_stats.date} + group_details: + product_details: + label: Product Details + description: 'Fields that have information about the products in the basket.' + item_details: + label: Item Details + description: 'Fields that have information about the items in the basket.' + columns: + - name: revenue + description: 'Total estimated revenue in GBP based on forecasting done by the finance team.' + config: + meta: + metrics: + total_revenue: + label: 'Total revenue GBP' + type: SUM + description: 'Total revenue in GBP' + sql: 'IF(${revenue} IS NULL, 10, ${revenue})' + groups: ['product_details', 'item_details'] # this would add the metric to a nested group: `product details` --> `item details` + hidden: false + format: '[$£]#,##0.00' # GBP rounded to two decimal points + show_underlying_values: + - revenue + - forecast_date + - web_sessions.session_id # field from joined table + filters: + - is_adjusted: true + ``` + + Here are all of the properties you can customize: From de7b18230f684ac230045b69acd8cbb103711a57 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:54:54 +0000 Subject: [PATCH 04/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 5eb5592a..99b30e2c 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -253,15 +253,31 @@ The `percentile` metric can be used on any numeric dimension or, [for custom SQL For example, this creates a metric `median_price` by taking the 50% percentile of the `item_price` dimension: -```yaml -columns: - - name: item_price - meta: - metrics: - median_price: - type: percentile - percentile: 50 -``` + + + ```yaml + columns: + - name: item_price + meta: + metrics: + median_price: + type: percentile + percentile: 50 + ``` + + + ```yaml + columns: + - name: item_price + config: + meta: + metrics: + median_price: + type: percentile + percentile: 50 + ``` + + ### median From 87bd9518ba92144fdc10ac9e156aa47094cf9df7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:55:02 +0000 Subject: [PATCH 05/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 99b30e2c..b29a326f 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -287,14 +287,29 @@ The `median` metric can be used on any numeric dimension or, [for custom SQL](#u For example, this creates a metric `median_price` by taking the 50% percentile of the `item_price` dimension: -```yaml -columns: - - name: item_price - meta: - metrics: - median_price: - type: median -``` + + + ```yaml + columns: + - name: item_price + meta: + metrics: + median_price: + type: median + ``` + + + ```yaml + columns: + - name: item_price + config: + meta: + metrics: + median_price: + type: median + ``` + + ### average From 4f2de5d61017a05b5fd0e33fa6dd83b6a3ec1ed4 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:55:12 +0000 Subject: [PATCH 06/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index b29a326f..88f4c637 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -319,14 +319,29 @@ The `average` metric can be used on any numeric dimension or, [for custom SQL](# For example, this creates a metric `avg_price` by taking the average of the `item_price` dimension: -```yaml -columns: - - name: item_price - meta: - metrics: - avg_price: - type: average -``` + + + ```yaml + columns: + - name: item_price + meta: + metrics: + avg_price: + type: average + ``` + + + ```yaml + columns: + - name: item_price + config: + meta: + metrics: + avg_price: + type: average + ``` + + ### boolean From 44c0ab559c203163952a1529491624002199b4c2 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:55:20 +0000 Subject: [PATCH 07/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 88f4c637..be5768c5 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -353,17 +353,35 @@ The `boolean` metric can be used on any valid SQL expression that gives you a `T For example, the `avg_price` metric below is an average of all of the `item_price` values in our product table. A second metric called `is_avg_price_above_20` is a `boolean` type metric. The `is_avg_price_above_20` metric has a custom SQL expression that tells us whether the `avg_price` value is greater than 20. -```yaml -columns: - - name: item_price - meta: - metrics: - avg_price: - type: average - is_avg_price_above_20: - type: boolean - sql: 'IF(${avg_price} > 20, TRUE, FALSE)' -``` + + + ```yaml + columns: + - name: item_price + meta: + metrics: + avg_price: + type: average + is_avg_price_above_20: + type: boolean + sql: 'IF(${avg_price} > 20, TRUE, FALSE)' + ``` + + + ```yaml + columns: + - name: item_price + config: + meta: + metrics: + avg_price: + type: average + is_avg_price_above_20: + type: boolean + sql: 'IF(${avg_price} > 20, TRUE, FALSE)' + ``` + + ### count From ef431e24aa7b370f2e6e9ed9b9c934c36849cf3f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:55:32 +0000 Subject: [PATCH 08/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index be5768c5..a5dca021 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -391,14 +391,29 @@ The `count` metric can be used on any dimension or, [for custom SQL](#using-cust For example, this creates a metric `number_of_users` by counting the number of `user_id` values in the table: -```yaml -columns: - - name: user_id - meta: - metrics: - number_of_users: - type: count -``` + + + ```yaml + columns: + - name: user_id + meta: + metrics: + number_of_users: + type: count + ``` + + + ```yaml + columns: + - name: user_id + config: + meta: + metrics: + number_of_users: + type: count + ``` + + ### count_distinct From 5a392196b1459c2c3237154c2b3e5d38d37817e5 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:55:51 +0000 Subject: [PATCH 09/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index a5dca021..6504238c 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -423,14 +423,29 @@ The `count_distinct` metric can be used on any dimension or, [for custom SQL](#u For example, this creates a metric `number_of_unique_users` by counting the number of unique `user_id` values in the table: -```yaml -columns: - - name: user_id - meta: - metrics: - number_of_unique_users: - type: count_distinct -``` + + + ```yaml + columns: + - name: user_id + meta: + metrics: + number_of_unique_users: + type: count_distinct + ``` + + + ```yaml + columns: + - name: user_id + config: + meta: + metrics: + number_of_unique_users: + type: count_distinct + ``` + + ### date From 91331a48ff767ac71fd0f6e312421982d190370e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:56:00 +0000 Subject: [PATCH 10/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 6504238c..1aa0cd8a 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -457,17 +457,35 @@ The `date` metric can be used on any valid SQL expression that gives you a date If you want to create a metric of a maximum or minimum date, you can't use `type: max` or of `type: min` metrics because these are only compatible with numeric type fields. Instead, you can calculate a maximum or minimum date by defining a metric of `type: date` and using some custom sql, like this: -```yaml -columns: - - name: created_at_date - meta: - dimension: - type: date - metrics: - max_created_at_date: - type: date - sql: MAX(${TABLE}.created_at_date) -``` + + + ```yaml + columns: + - name: created_at_date + meta: + dimension: + type: date + metrics: + max_created_at_date: + type: date + sql: MAX(${TABLE}.created_at_date) + ``` + + + ```yaml + columns: + - name: created_at_date + config: + meta: + dimension: + type: date + metrics: + max_created_at_date: + type: date + sql: MAX(${TABLE}.created_at_date) + ``` + + ### max From 52024551241fbda6c49667783a3b57d16148fdf2 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:56:11 +0000 Subject: [PATCH 11/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 1aa0cd8a..371da786 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -497,14 +497,29 @@ Because `type: max` metrics only work with numerical fields, you can't use them For example, this creates a metric `max_delivery_cost` by looking at the `delivery_cost` dimension and taking the largest value it finds: -```yaml -columns: - - name: delivery_cost - meta: - metrics: - max_delivery_cost: - type: max -``` + + + ```yaml + columns: + - name: delivery_cost + meta: + metrics: + max_delivery_cost: + type: max + ``` + + + ```yaml + columns: + - name: delivery_cost + config: + meta: + metrics: + max_delivery_cost: + type: max + ``` + + ### min From 5761090a02c6dbd243a2a64515e7a041a717f4df Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:56:19 +0000 Subject: [PATCH 12/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 371da786..c302ff90 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -531,14 +531,29 @@ Because `type: min` metrics only work with numerical fields, you can't use them For example, this creates a metric `min_delivery_cost` by looking at the `delivery_cost` dimension and taking the smallest value it finds: -```yaml -columns: - - name: delivery_cost - meta: - metrics: - min_delivery_cost: - type: min -``` + + + ```yaml + columns: + - name: delivery_cost + meta: + metrics: + min_delivery_cost: + type: min + ``` + + + ```yaml + columns: + - name: delivery_cost + config: + meta: + metrics: + min_delivery_cost: + type: min + ``` + + ### number From 0cc9281d67f1848cd1e0fee66eac676f9ca7cc0e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:56:35 +0000 Subject: [PATCH 13/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 56 ++++++++++++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index c302ff90..182112cb 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -563,22 +563,46 @@ The `number` metric can be used on any valid SQL expression that gives you a num For example, this creates a metric called `total_gross_profit_margin_percentage` based on the `total_sale_price` and `total_gross_profit_margin` aggregate metrics: -```yaml -columns: - - name: sale_price - meta: - metrics: - total_sale_price: - type: sum - - name: gross_profit_margin - meta: - metrics: - total_gross_profit_margin: - type: sum - total_gross_profit_margin_percentage: - type: number - sql: '(${total_gross_profit_margin}/ NULLIF(${total_sale_price},0))' -``` + + + ```yaml + columns: + - name: sale_price + meta: + metrics: + total_sale_price: + type: sum + - name: gross_profit_margin + meta: + metrics: + total_gross_profit_margin: + type: sum + total_gross_profit_margin_percentage: + type: number + sql: '(${total_gross_profit_margin}/ NULLIF(${total_sale_price},0))' + ``` + + + ```yaml + columns: + - name: sale_price + config: + meta: + metrics: + total_sale_price: + type: sum + - name: gross_profit_margin + config: + meta: + metrics: + total_gross_profit_margin: + type: sum + total_gross_profit_margin_percentage: + type: number + sql: '(${total_gross_profit_margin}/ NULLIF(${total_sale_price},0))' + ``` + + The example above also uses the NULLIF() SQL function to avoid division-by-zero errors. From b307fb432c79559bfc9b4fb615ffec69e3e6534a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:56:45 +0000 Subject: [PATCH 14/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 182112cb..734f93c7 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -614,14 +614,29 @@ The `sum` metric can be used on any numeric dimension or, [for custom SQL](#usin For example, this creates a metric `total_revenue` by adding up the values in the `revenue` dimension: -```yaml -columns: - - name: revenue - meta: - metrics: - total_revenue: - type: sum -``` + + + ```yaml + columns: + - name: revenue + meta: + metrics: + total_revenue: + type: sum + ``` + + + ```yaml + columns: + - name: revenue + config: + meta: + metrics: + total_revenue: + type: sum + ``` + + **What about sum distinct?** Lightdash does not have a `sum_distinct` metric type, but if your database supports it, you can call it directly by adding a number metric and using the `sql` argument (see example below). From 35541e2c553d06d87ecc59cf0141dbdb857bfc37 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:56:52 +0000 Subject: [PATCH 15/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 734f93c7..3cfc857a 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -642,15 +642,31 @@ For example, this creates a metric `total_revenue` by adding up the values in th In most cases it will be more accurate to use [Lightdash fanout protection](/references/joins#handling-fanouts) to de-duplicate values before summing rather than using `SUM(DISTINCT ...)` in your SQL. This is because `SUM(DISTINCT ...)` can give incorrect results if there are multiple rows with the same value. -```yaml -columns: - - name: revenue - meta: - metrics: - total_revenue: - type: number - sql: 'SUM(DISTINCT ${revenue})' -``` + + + ```yaml + columns: + - name: revenue + meta: + metrics: + total_revenue: + type: number + sql: 'SUM(DISTINCT ${revenue})' + ``` + + + ```yaml + columns: + - name: revenue + config: + meta: + metrics: + total_revenue: + type: number + sql: 'SUM(DISTINCT ${revenue})' + ``` + + ### string From 22661a1e5ef7e057b1236bbe9576513146a2e648 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:57:00 +0000 Subject: [PATCH 16/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 3cfc857a..d3fd8110 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -679,15 +679,31 @@ The `string` metric can be used on any valid SQL expression that gives you a str For example, this creates a metric `product_name_group` by combining the unique values of a dimension called `product_name`: -```yaml -columns: - - name: product_name - meta: - metrics: - product_name_group: - type: string - sql: 'GROUP_CONCAT(${TABLE}.product_name)' -``` + + + ```yaml + columns: + - name: product_name + meta: + metrics: + product_name_group: + type: string + sql: 'GROUP_CONCAT(${TABLE}.product_name)' + ``` + + + ```yaml + columns: + - name: product_name + config: + meta: + metrics: + product_name_group: + type: string + sql: 'GROUP_CONCAT(${TABLE}.product_name)' + ``` + + ### percent_of_previous From 8c80615d5d9ff1d150e7050ae4493656dc472f72 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:57:11 +0000 Subject: [PATCH 17/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 43 ++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index d3fd8110..a051e4a3 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -711,18 +711,37 @@ Returns the current value as a percentage of the previous row's value for a refe For example, to calculate the percent of the previous value of total revenue: -```yaml -models: - - name: orders_model - meta: - metrics: - total_revenue: - type: sum - revenue_percent_of_previous: - type: percent_of_previous - sql: ${total_revenue} - format: '0.00%' -``` + + + ```yaml + models: + - name: orders_model + meta: + metrics: + total_revenue: + type: sum + revenue_percent_of_previous: + type: percent_of_previous + sql: ${total_revenue} + format: '0.00%' + ``` + + + ```yaml + models: + - name: orders_model + config: + meta: + metrics: + total_revenue: + type: sum + revenue_percent_of_previous: + type: percent_of_previous + sql: ${total_revenue} + format: '0.00%' + ``` + + Note: If the previous value is 0 or NULL, the result will be NULL to avoid division-by-zero. From 9f659d9d943db93cf81c0a00b9ae54364cd28fdd Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:57:20 +0000 Subject: [PATCH 18/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 43 ++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index a051e4a3..28b54d57 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -754,18 +754,37 @@ Returns the current value as a percentage of the total across the result set (or For example, to calculate each row's percent of total revenue: -```yaml -models: - - name: orders_model - meta: - metrics: - total_revenue: - type: sum - revenue_percent_of_total: - type: percent_of_total - sql: ${total_revenue} - format: '0.00%' -``` + + + ```yaml + models: + - name: orders_model + meta: + metrics: + total_revenue: + type: sum + revenue_percent_of_total: + type: percent_of_total + sql: ${total_revenue} + format: '0.00%' + ``` + + + ```yaml + models: + - name: orders_model + config: + meta: + metrics: + total_revenue: + type: sum + revenue_percent_of_total: + type: percent_of_total + sql: ${total_revenue} + format: '0.00%' + ``` + + **This is a post calculation metric** which is computed after other metrics. It can only reference aggregate and non-aggregate metrics (and cannot reference dimensions or other post calculation metrics). From 1ac2d0b8c72eb4c13a700571e247319e830f154a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:57:28 +0000 Subject: [PATCH 19/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 28b54d57..69be03fe 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -796,17 +796,35 @@ Returns the cumulative total of a referenced metric according to the query's gro For example, to calculate a running total of revenue: -```yaml -models: - - name: orders_model - meta: - metrics: - total_revenue: - type: sum - running_total_revenue: - type: running_total - sql: ${total_revenue} -``` + + + ```yaml + models: + - name: orders_model + meta: + metrics: + total_revenue: + type: sum + running_total_revenue: + type: running_total + sql: ${total_revenue} + ``` + + + ```yaml + models: + - name: orders_model + config: + meta: + metrics: + total_revenue: + type: sum + running_total_revenue: + type: running_total + sql: ${total_revenue} + ``` + + **This is a post calculation metric** which is computed after other metrics. It can only reference aggregate and non-aggregate metrics (and cannot reference dimensions or other post calculation metrics). From 0c1424cff837e4b78e5bc7de28aed7f343e67dde Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:57:43 +0000 Subject: [PATCH 20/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 106 ++++++++++++++++++++++++++++------------- 1 file changed, 74 insertions(+), 32 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 69be03fe..e01e8f68 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -1052,39 +1052,81 @@ You can group your dimensions and metrics in the sidebar using the `groups` para To do this, you need to set up `group_details` in the model's configuration. Then, you can use these groups to organize metrics and dimensions. You can create nested groups up to 2 levels. -```yaml -models: - - name: baskets - meta: - group_details: - product_details: - label: Product Details - description: 'Fields that have information about the products in the basket.' - item_details: - label: Item Details - description: 'Fields that have information about the items in the basket.' - - columns: - - name: basket_item_id - description: 'ID for the product item within the basket.' - meta: - dimension: - groups: ['product_details', 'item_details'] # this would add the dimension to a nested group: `product details` --> `item details` - metrics: - count_total_basket_items: - type: count_distinct - groups: ['product_details', 'item_details'] # this would add the metric to a nested group: `product details` --> `item details` - - name: product_name - description: 'Full name of the product.' + + + ```yaml + models: + - name: baskets meta: - dimension: - label: 'Product name' - groups: ['product_details'] # this would add the dimension under the group label: `product_details` - metrics: - count_total_product_types: - type: count_distinct - groups: ['product_details'] # this would add the metric under the group label: `product_details` -``` + group_details: + product_details: + label: Product Details + description: 'Fields that have information about the products in the basket.' + item_details: + label: Item Details + description: 'Fields that have information about the items in the basket.' + + columns: + - name: basket_item_id + description: 'ID for the product item within the basket.' + meta: + dimension: + groups: ['product_details', 'item_details'] # this would add the dimension to a nested group: `product details` --> `item details` + metrics: + count_total_basket_items: + type: count_distinct + groups: ['product_details', 'item_details'] # this would add the metric to a nested group: `product details` --> `item details` + - name: product_name + description: 'Full name of the product.' + meta: + dimension: + label: 'Product name' + groups: ['product_details'] # this would add the dimension under the group label: `product_details` + metrics: + count_total_product_types: + type: count_distinct + groups: ['product_details'] # this would add the metric under the group label: `product_details` + ``` + + + ```yaml + models: + - name: baskets + config: + meta: + group_details: + product_details: + label: Product Details + description: 'Fields that have information about the products in the basket.' + item_details: + label: Item Details + description: 'Fields that have information about the items in the basket.' + + columns: + - name: basket_item_id + description: 'ID for the product item within the basket.' + config: + meta: + dimension: + groups: ['product_details', 'item_details'] # this would add the dimension to a nested group: `product details` --> `item details` + metrics: + count_total_basket_items: + type: count_distinct + groups: ['product_details', 'item_details'] # this would add the metric to a nested group: `product details` --> `item details` + - name: product_name + description: 'Full name of the product.' + config: + meta: + dimension: + label: 'Product name' + groups: ['product_details'] # this would add the dimension under the group label: `product_details` + metrics: + count_total_product_types: + type: count_distinct + groups: ['product_details'] # this would add the metric under the group label: `product_details` + ``` + + ## Filters From ec4cc8fd01febe2a21ba90d73a52b771f1edaeeb Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:57:54 +0000 Subject: [PATCH 21/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 52 ++++++++++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 15 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index e01e8f68..7b19e95b 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -1134,21 +1134,43 @@ Filters are applied to metrics any time that metric is used in Lightdash. Filter For example, we could add a filter to our users count to make sure it didn't include user IDs with closed accounts, like this: -```yaml -models: - - name: sales_stats - columns: - - name: user_id - description: 'Unique ID for users.' - meta: - dimension: - type: string - metrics: - count_users: - type: count_distinct - filters: - - is_closed_account: false -``` + + + ```yaml + models: + - name: sales_stats + columns: + - name: user_id + description: 'Unique ID for users.' + meta: + dimension: + type: string + metrics: + count_users: + type: count_distinct + filters: + - is_closed_account: false + ``` + + + ```yaml + models: + - name: sales_stats + columns: + - name: user_id + description: 'Unique ID for users.' + config: + meta: + dimension: + type: string + metrics: + count_users: + type: count_distinct + filters: + - is_closed_account: false + ``` + + These filters do not appear in the `Filters` tab in the Explore view, instead, they are applied automatically in the SQL query that fetches your results. That means filters added using the `filter` parameter can't be removed in the UI and won't be visible to users unless they look at the SQL query. From 8ff5cd17437d55c88e38ac58d1e104c8eb6ed578 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:58:03 +0000 Subject: [PATCH 22/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 43 ++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 7b19e95b..48d00c1a 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -1221,18 +1221,37 @@ filters: To filter a field using a list of values you can supply them as an array for that field. For example, if you wanted to filter for orders with order status `completed` or `shipped` you should write the metric like: -```yaml -columns: - - name: order_id - meta: - metrics: - completed_or_shipped_order_count: - type: count_distinct - filters: - - order_status: - - completed - - shipped -``` + + + ```yaml + columns: + - name: order_id + meta: + metrics: + completed_or_shipped_order_count: + type: count_distinct + filters: + - order_status: + - completed + - shipped + ``` + + + ```yaml + columns: + - name: order_id + config: + meta: + metrics: + completed_or_shipped_order_count: + type: count_distinct + filters: + - order_status: + - completed + - shipped + ``` + + ### Filters are joined using `AND` From 3db533c4a8307bfe0b5abc824c0e606fcd9a5591 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:58:19 +0000 Subject: [PATCH 23/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 66 ++++++++++++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 19 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 48d00c1a..a9c03d8e 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -1269,26 +1269,54 @@ Would give you logic like `is_closed_account = TRUE AND is_7d_active = FALSE`. To filter using a field from a joined model, just use the syntax `model_name.field`, like this: -```yaml -models: - - name: sales_stats - meta: - joins: - - join: web_sessions - sql_on: ${web_sessions.date} = ${sales_stats.date} - columns: - - name: user_id - description: 'Unique ID for users.' + + + ```yaml + models: + - name: sales_stats meta: - dimension: - type: string - metrics: - count_users: - type: count_distinct - filters: - - is_closed_account: false - - web_sessions.is_bot_user: false -``` + joins: + - join: web_sessions + sql_on: ${web_sessions.date} = ${sales_stats.date} + columns: + - name: user_id + description: 'Unique ID for users.' + meta: + dimension: + type: string + metrics: + count_users: + type: count_distinct + filters: + - is_closed_account: false + - web_sessions.is_bot_user: false + ``` + + + ```yaml + models: + - name: sales_stats + config: + meta: + joins: + - join: web_sessions + sql_on: ${web_sessions.date} = ${sales_stats.date} + columns: + - name: user_id + description: 'Unique ID for users.' + config: + meta: + dimension: + type: string + metrics: + count_users: + type: count_distinct + filters: + - is_closed_account: false + - web_sessions.is_bot_user: false + ``` + + ### Metric filters cannot be used with non-aggregate metrics From 1924113407a4f884aff3c973c75dafc0cfe39984 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:58:35 +0000 Subject: [PATCH 24/75] Update references/metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/metrics.mdx | 107 +++++++++++++++++++++++++++++------------ 1 file changed, 75 insertions(+), 32 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index a9c03d8e..cfb5fd14 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -1324,37 +1324,80 @@ You can't use filters with non-aggregate metric types. Instead, if your non-aggr Here's an example: imagine you wanted to calculate the average cost per item that had the status `shipped`. You would need to do something like this in your .yml: -```yaml -models: - - name: orders - meta: - metrics: - average_cost_per_item_shipped: - type: number - sql: ${total_cost_of_shipped} / ${count_unique_items_shipped} - columns: - - name: item_id - description: 'Unique ID for items ordered.' + + + ```yaml + models: + - name: orders meta: - dimension: - type: string metrics: - count_unique_items: - type: count_distinct - count_unique_items_shipped: - type: count_distinct - filters: - - status: 'shipped' - - name: item_cost - description: 'Cost for each item ordered.' - meta: - dimension: - type: number - metrics: - total_cost: - type: sum - total_cost_of_shipped: - type: sum - filters: - - status: 'shipped' -``` \ No newline at end of file + average_cost_per_item_shipped: + type: number + sql: ${total_cost_of_shipped} / ${count_unique_items_shipped} + columns: + - name: item_id + description: 'Unique ID for items ordered.' + meta: + dimension: + type: string + metrics: + count_unique_items: + type: count_distinct + count_unique_items_shipped: + type: count_distinct + filters: + - status: 'shipped' + - name: item_cost + description: 'Cost for each item ordered.' + meta: + dimension: + type: number + metrics: + total_cost: + type: sum + total_cost_of_shipped: + type: sum + filters: + - status: 'shipped' + ``` + + + ```yaml + models: + - name: orders + config: + meta: + metrics: + average_cost_per_item_shipped: + type: number + sql: ${total_cost_of_shipped} / ${count_unique_items_shipped} + columns: + - name: item_id + description: 'Unique ID for items ordered.' + config: + meta: + dimension: + type: string + metrics: + count_unique_items: + type: count_distinct + count_unique_items_shipped: + type: count_distinct + filters: + - status: 'shipped' + - name: item_cost + description: 'Cost for each item ordered.' + config: + meta: + dimension: + type: number + metrics: + total_cost: + type: sum + total_cost_of_shipped: + type: sum + filters: + - status: 'shipped' + ``` + + \ No newline at end of file From 5052ce3222ee0af7d984f8b902944caaee034aee Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:58:48 +0000 Subject: [PATCH 25/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 7330e835..0baf28cf 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -12,13 +12,26 @@ Read more about [adding dimensions to your project in our docs here](/get-starte For a dimension to appear in Lightdash, you just need to declare it in your dbt model's YAML file. -```yaml -models: - - name: my_model - columns: - - name: user_id # will be "User id" in LightDash - description: "Unique identifier for a user." -``` + + + ```yaml + models: + - name: my_model + columns: + - name: user_id # will be "User id" in LightDash + description: "Unique identifier for a user." + ``` + + + ```yaml + models: + - name: my_model + columns: + - name: user_id # will be "User id" in LightDash + description: "Unique identifier for a user." + ``` + + ## Dimension configuration From 3597be9e97447559346711ce7974ade493c41424 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:59:10 +0000 Subject: [PATCH 26/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 119 ++++++++++++++++++++++++++------------ 1 file changed, 82 insertions(+), 37 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 0baf28cf..869bd5f0 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -39,44 +39,89 @@ To customize the dimension, you can do it in your dbt model's YAML file. If you want to declare multiple dimensions based on the same column, check [additional dimensions](#additional-dimensions) section. -```yaml -models: - - name: sales_stats - meta: - group_details: - finance: - label: Finance - description: Finance-related fields. - joins: - - join: web_sessions - sql_on: ${web_sessions.date} = ${sales_stats.date} - columns: - - name: revenue_gbp_total_est - description: 'Total estimated revenue in GBP based on forecasting done by the finance team.' - meta: - dimension: - type: number - label: 'Total revenue' # this is the label you'll see in Lightdash - description: 'My custom description' # you can override the description you'll see in Lightdash here - sql: 'IF(${TABLE}.revenue_gbp_total_est = NULL, 0, ${registered_user_email})' # custom SQL applied to the column from dbt used to define the dimension - hidden: false - format: '[$£]#,##0.00' # GBP rounded to two decimal points - groups: ['finance'] - - name: forecast_date - description: 'Date of the forecasting.' + + + ```yaml + models: + - name: sales_stats meta: - dimension: - type: date - time_intervals: ['DAY', 'WEEK', 'MONTH', 'QUARTER'] # not required: the default time intervals for dates are `['DAY', 'WEEK', 'MONTH', 'YEAR']` - urls: - - label: 'Open in forecasting tool' - url: 'https://finance.com/forceasts/weeks/${ value.raw }' - - label: Open in Google Calendar - url: 'https://calendar.google.com/calendar/u/0/r/day/${ value.formatted |split: "-" |join: "/"}' - required_attributes: - is_admin: 'true' - -``` + group_details: + finance: + label: Finance + description: Finance-related fields. + joins: + - join: web_sessions + sql_on: ${web_sessions.date} = ${sales_stats.date} + columns: + - name: revenue_gbp_total_est + description: 'Total estimated revenue in GBP based on forecasting done by the finance team.' + meta: + dimension: + type: number + label: 'Total revenue' # this is the label you'll see in Lightdash + description: 'My custom description' # you can override the description you'll see in Lightdash here + sql: 'IF(${TABLE}.revenue_gbp_total_est = NULL, 0, ${registered_user_email})' # custom SQL applied to the column from dbt used to define the dimension + hidden: false + format: '[$£]#,##0.00' # GBP rounded to two decimal points + groups: ['finance'] + - name: forecast_date + description: 'Date of the forecasting.' + meta: + dimension: + type: date + time_intervals: ['DAY', 'WEEK', 'MONTH', 'QUARTER'] # not required: the default time intervals for dates are `['DAY', 'WEEK', 'MONTH', 'YEAR']` + urls: + - label: 'Open in forecasting tool' + url: 'https://finance.com/forceasts/weeks/${ value.raw }' + - label: Open in Google Calendar + url: 'https://calendar.google.com/calendar/u/0/r/day/${ value.formatted |split: "-" |join: "/"}' + required_attributes: + is_admin: 'true' + ``` + + + ```yaml + models: + - name: sales_stats + config: + meta: + group_details: + finance: + label: Finance + description: Finance-related fields. + joins: + - join: web_sessions + sql_on: ${web_sessions.date} = ${sales_stats.date} + columns: + - name: revenue_gbp_total_est + description: 'Total estimated revenue in GBP based on forecasting done by the finance team.' + config: + meta: + dimension: + type: number + label: 'Total revenue' # this is the label you'll see in Lightdash + description: 'My custom description' # you can override the description you'll see in Lightdash here + sql: 'IF(${TABLE}.revenue_gbp_total_est = NULL, 0, ${registered_user_email})' # custom SQL applied to the column from dbt used to define the dimension + hidden: false + format: '[$£]#,##0.00' # GBP rounded to two decimal points + groups: ['finance'] + - name: forecast_date + description: 'Date of the forecasting.' + config: + meta: + dimension: + type: date + time_intervals: ['DAY', 'WEEK', 'MONTH', 'QUARTER'] # not required: the default time intervals for dates are `['DAY', 'WEEK', 'MONTH', 'YEAR']` + urls: + - label: 'Open in forecasting tool' + url: 'https://finance.com/forceasts/weeks/${ value.raw }' + - label: Open in Google Calendar + url: 'https://calendar.google.com/calendar/u/0/r/day/${ value.formatted |split: "-" |join: "/"}' + required_attributes: + is_admin: 'true' + ``` + + All the properties you can customize: From 6a8a90dc8b28103341a2a888643a41c2b45bf3ea Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:59:17 +0000 Subject: [PATCH 27/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 869bd5f0..f3160738 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -146,12 +146,25 @@ All the properties you can customize: The types of your dimensions are pulled from your data warehouse, automatically. You can override these types using the `type` meta tag in your .yml file. If you run `lightdash generate` to generate your .yml files, then Lightdash will add the `type` from your data warehouse to your .yml files automatically. -```yaml -- name: user_created_date - meta: - dimension: - type: date -``` + + + ```yaml + - name: user_created_date + meta: + dimension: + type: date + ``` + + + ```yaml + - name: user_created_date + config: + meta: + dimension: + type: date + ``` + + We currently support these dimension types: From 10ad7cfddf23ad427d5ca1d0130537cbb8285917 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:59:29 +0000 Subject: [PATCH 28/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 49 ++++++++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index f3160738..880fa86d 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -244,20 +244,41 @@ You can use the `format` parameter to have your dimensions show in a particular To help you build your format expression, we recommend using https://customformats.com/. -```yaml -- name: us_revenue - meta: - dimension: - type: number - description: 'Revenue in USD, with two decimal places, compacted to thousands' - format: '$#,##0.00," K"' # 505,430 will appear as '$505.43 K' - additional_dimensions: - percent_of_global_revenue: - type: number - description: 'Percent of total global revenue coming from US revenue.' - sql: ${us_revenue} / ${global_revenue} - format: '0.00%' # 0.67895243 will appear as '67.89% -``` + + + ```yaml + - name: us_revenue + meta: + dimension: + type: number + description: 'Revenue in USD, with two decimal places, compacted to thousands' + format: '$#,##0.00," K"' # 505,430 will appear as '$505.43 K' + additional_dimensions: + percent_of_global_revenue: + type: number + description: 'Percent of total global revenue coming from US revenue.' + sql: ${us_revenue} / ${global_revenue} + format: '0.00%' # 0.67895243 will appear as '67.89% + ``` + + + ```yaml + - name: us_revenue + config: + meta: + dimension: + type: number + description: 'Revenue in USD, with two decimal places, compacted to thousands' + format: '$#,##0.00," K"' # 505,430 will appear as '$505.43 K' + additional_dimensions: + percent_of_global_revenue: + type: number + description: 'Percent of total global revenue coming from US revenue.' + sql: ${us_revenue} / ${global_revenue} + format: '0.00%' # 0.67895243 will appear as '67.89% + ``` + + ### Example format expressions: From 2f29ac3703a089509c7356a76fc388b7cdcea3ac Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:59:38 +0000 Subject: [PATCH 29/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 880fa86d..12ea35c2 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -316,16 +316,33 @@ To help you build your format expression, we recommend using https://customforma #### Format (legacy) - ```yaml - models: - - name: sales_stats - columns: - - name: revenue - description: 'Total estimated revenue in GBP based on forecasting done by the finance team.' - meta: - dimension: - format: 'gbp' - ``` + + + ```yaml + models: + - name: sales_stats + columns: + - name: revenue + description: 'Total estimated revenue in GBP based on forecasting done by the finance team.' + meta: + dimension: + format: 'gbp' + ``` + + + ```yaml + models: + - name: sales_stats + columns: + - name: revenue + description: 'Total estimated revenue in GBP based on forecasting done by the finance team.' + config: + meta: + dimension: + format: 'gbp' + ``` + + These are the options: From 20cce60c641e2e91dd058fc55d70d7a7e0663ac8 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:59:46 +0000 Subject: [PATCH 30/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 12ea35c2..ba9b7734 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -361,15 +361,31 @@ To help you build your format expression, we recommend using https://customforma You can round values to appear with a certain number of decimal points. - ```yaml - models: - - name: sales - columns: - - name: revenue - meta: - dimension: - round: 0 # equivalent format expression: '#,##0.0' - ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + dimension: + round: 0 # equivalent format expression: '#,##0.0' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + dimension: + round: 0 # equivalent format expression: '#,##0.0' + ``` + + ## Compact From 438cfba90d509769876e8658cf1c753870fd9678 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 15:59:56 +0000 Subject: [PATCH 31/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index ba9b7734..1ba1e6f6 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -392,15 +392,31 @@ To help you build your format expression, we recommend using https://customforma You can compact values in your YAML. For example, if I wanted all of my revenue values to be shown in thousands (e.g. `1,500` appears as `1.50K`), then I would write something like this in my .yml: -```yaml -models: - - name: sales - columns: + + + ```yaml + models: + - name: sales + columns: - name: revenue meta: + dimension: + compact: thousands # You can also use 'K' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: dimension: - compact: thousands # You can also use 'K' -``` + compact: thousands # You can also use 'K' + ``` + + | Value | Alias | Equivalent format expression | Example output | | :-------- | :------------------- | :------------------------------------ | :------------- | From 927daeb1fc4e1b499cd5c95c92c5e58eb7101ad2 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:00:06 +0000 Subject: [PATCH 32/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 1ba1e6f6..b3cb8ed9 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -470,13 +470,27 @@ If you want to turn off time intervals for a dimension, you can simply set the ` In this example, `created` would now appear as a single, timestamp dimension without a drop-down list of time intervals in Lightdash: -```yaml -- name: created - description: 'Timestamp when the user was created.' - meta: - dimension: - time_intervals: OFF -``` + + + ```yaml + - name: created + description: 'Timestamp when the user was created.' + meta: + dimension: + time_intervals: OFF + ``` + + + ```yaml + - name: created + description: 'Timestamp when the user was created.' + config: + meta: + dimension: + time_intervals: OFF + ``` + + ![screenshot-intervals-off](/images/references/screenshot-intervals-off-e786a3290b6c8b8454fe7f223a5682d8.png) From af403d4561db8bc751630a21ec13b4e72c2a6801 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:00:16 +0000 Subject: [PATCH 33/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index b3cb8ed9..0aa4c532 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -500,13 +500,27 @@ In this example, `created` would now appear as a single, timestamp dimension wit If you specify time intervals manually, then this overrides the default time intervals used by Lightdash. -```yaml -- name: created - description: 'Timestamp when the user was created.' - meta: - dimension: - time_intervals: ['DAY', 'DAY_OF_MONTH_NUM', 'MONTH', 'QUARTER_NAME', 'YEAR'] -``` + + + ```yaml + - name: created + description: 'Timestamp when the user was created.' + meta: + dimension: + time_intervals: ['DAY', 'DAY_OF_MONTH_NUM', 'MONTH', 'QUARTER_NAME', 'YEAR'] + ``` + + + ```yaml + - name: created + description: 'Timestamp when the user was created.' + config: + meta: + dimension: + time_intervals: ['DAY', 'DAY_OF_MONTH_NUM', 'MONTH', 'QUARTER_NAME', 'YEAR'] + ``` + + You can see all of the standard interval options for date and timestamp fields below. You can also add custom intervals using _additional dimensions_, there's an example below the following tables. From 1adb19012010cc639eec9b146a22b3e07bf09dec Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:00:28 +0000 Subject: [PATCH 34/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 82 +++++++++++++++++++++++++++------------ 1 file changed, 58 insertions(+), 24 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 0aa4c532..995caf00 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -590,31 +590,65 @@ You can group your dimensions and metrics in the sidebar using the `groups` para To do this, you need to set up `group_details` in the model's configuration. Then, you can use these groups to organize metrics and dimensions. You can create nested groups up to 3 levels. -```yaml -models: - - name: baskets - meta: - group_details: - product_details: - label: Product Details - description: 'Fields that have information about the products in the basket.' - item_details: - label: Item Details - description: 'Fields that have information about the items in the basket.' - - columns: - - name: basket_item_id - description: 'ID for the product item within the basket.' - meta: - dimension: - groups: ['product_details', 'item_details'] # this would add the dimension to a nested group: `product details` --> `item details` - - name: product_name - description: 'Full name of the product.' + + + ```yaml + models: + - name: baskets meta: - dimension: - label: 'Product name' - groups: ['product_details'] # this would add the dimension under the group label: `product_details` -``` + group_details: + product_details: + label: Product Details + description: 'Fields that have information about the products in the basket.' + item_details: + label: Item Details + description: 'Fields that have information about the items in the basket.' + + columns: + - name: basket_item_id + description: 'ID for the product item within the basket.' + meta: + dimension: + groups: ['product_details', 'item_details'] # this would add the dimension to a nested group: `product details` --> `item details` + - name: product_name + description: 'Full name of the product.' + meta: + dimension: + label: 'Product name' + groups: ['product_details'] # this would add the dimension under the group label: `product_details` + ``` + + + ```yaml + models: + - name: baskets + config: + meta: + group_details: + product_details: + label: Product Details + description: 'Fields that have information about the products in the basket.' + item_details: + label: Item Details + description: 'Fields that have information about the items in the basket.' + + columns: + - name: basket_item_id + description: 'ID for the product item within the basket.' + config: + meta: + dimension: + groups: ['product_details', 'item_details'] # this would add the dimension to a nested group: `product details` --> `item details` + - name: product_name + description: 'Full name of the product.' + config: + meta: + dimension: + label: 'Product name' + groups: ['product_details'] # this would add the dimension under the group label: `product_details` + ``` + + This example would look like this in the sidebar: From 329de1f52c56ae78b5680b37999b015085c3a653 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:00:38 +0000 Subject: [PATCH 35/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 995caf00..71e2bdb8 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -661,16 +661,33 @@ This example would look like this in the sidebar: Lightdash users can interact with dimension values by clicking on them. If you're already storing URLs in your models, you can create hyperlinks to those URLs in Lightdash, like so: -```yaml -columns: - - name: candidate_profile_url - label: URL of the candidate profile - meta: - dimension: - urls: - - label: Open in CRM - url: ${ value.raw } -``` + + + ```yaml + columns: + - name: candidate_profile_url + label: URL of the candidate profile + meta: + dimension: + urls: + - label: Open in CRM + url: ${ value.raw } + ``` + + + ```yaml + columns: + - name: candidate_profile_url + label: URL of the candidate profile + config: + meta: + dimension: + urls: + - label: Open in CRM + url: ${ value.raw } + ``` + + ### How to add custom URLs From 75058da727fbc2b571f8fa6cebabd24d7983a131 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:00:50 +0000 Subject: [PATCH 36/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 43 ++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 71e2bdb8..20cb1064 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -700,18 +700,37 @@ By adding custom urls you can configure the actions available to your users. Lik In the example below, users can click on a company name and open a corresponding record in their CRM or search for the company in google or open that company's Slack channel. -```yaml -columns: - - name: company_name - label: Registered trading name of the company - meta: - dimension: - urls: - - label: Search for company in Google - url: 'https://google.com/search?${ value.formatted | url_encode }' - - label: Open in CRM - url: 'https://mycrm.com/companies/${ row.company.company_id.raw | url_encode }' -``` + + + ```yaml + columns: + - name: company_name + label: Registered trading name of the company + meta: + dimension: + urls: + - label: Search for company in Google + url: 'https://google.com/search?${ value.formatted | url_encode }' + - label: Open in CRM + url: 'https://mycrm.com/companies/${ row.company.company_id.raw | url_encode }' + ``` + + + ```yaml + columns: + - name: company_name + label: Registered trading name of the company + config: + meta: + dimension: + urls: + - label: Search for company in Google + url: 'https://google.com/search?${ value.formatted | url_encode }' + - label: Open in CRM + url: 'https://mycrm.com/companies/${ row.company.company_id.raw | url_encode }' + ``` + + The `${ value.formatted }` will be replaced with the value of the company name in the Lightdash UI at query run time. The `${ row.company.company_id.raw }` will be replaced with the value of the company id in the Lightdash UI at query run time. The action will be disabled if the column "company_id" from table "company" is not part of the query. From 90e43b563b8f462a9e6c9218f59d1a345b62626d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:01:01 +0000 Subject: [PATCH 37/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 20cb1064..6fdcd85e 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -739,16 +739,33 @@ The `${ value.formatted }` will be replaced with the value of the company name i You can reference another dimension from your table in your URL. For these URLs to work, the other column you've referenced needs to be included in your results table. For example, say I’ve added a URL to `company_name` and it uses the field `customer_id`: -```yaml -columns: - - name: company_name - label: Registered trading name of the company - meta: - dimension: - urls: - - label: "Open company" - url: "https://example.com/company/${row.customers.customer_id.raw | url_encode }" -``` + + + ```yaml + columns: + - name: company_name + label: Registered trading name of the company + meta: + dimension: + urls: + - label: "Open company" + url: "https://example.com/company/${row.customers.customer_id.raw | url_encode }" + ``` + + + ```yaml + columns: + - name: company_name + label: Registered trading name of the company + config: + meta: + dimension: + urls: + - label: "Open company" + url: "https://example.com/company/${row.customers.customer_id.raw | url_encode }" + ``` + + This URL will only work if I have `customer_id` included in my results table. From 719ad764d05716634f317ee34f85778628cec487 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:01:11 +0000 Subject: [PATCH 38/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 40 ++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 6fdcd85e..5f2a4e19 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -813,17 +813,35 @@ Lightdash can use `user attributes` to limit some dimensions to some users. In the example below, only users with `is_admin` attribute `true` can use the `salary` dimension on `user` table. Users without access to this dimension will not see it or the custom metrics created from this dimension on the `explore page`. -```yaml -columns: - - name: - description: User name - - salary: - description: User salary - meta: - dimension: - required_attributes: - is_admin: "true" -``` + + + ```yaml + columns: + - name: + description: User name + - salary: + description: User salary + meta: + dimension: + required_attributes: + is_admin: "true" + ``` + + + ```yaml + columns: + - name: + description: User name + - salary: + description: User salary + config: + meta: + dimension: + required_attributes: + is_admin: "true" + ``` + + If a user without access to this dimension runs a query that contains this dimension, they will get a `Forbidden` error. From 68891415932a743ea9b2dc4470e184c87b24368e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:01:22 +0000 Subject: [PATCH 39/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 43 ++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 5f2a4e19..7ac4073f 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -860,18 +860,37 @@ Lightdash dimensions and custom metrics are protected by this feature, however, You can predefine colors for your string type dimensions, these colors will be used instead of your default organization colors for the right value when you use a grouped bar chart or a pie chart. -```yaml - - name: status - description: "{{ doc(\"orders_status\") }}" - meta: - dimension: - colors: - "placed": "#e6fa0f" - "completed": "#558B2F" - "shipped": "#29B6F6" - "return_pending": "#FF6F00" - "returned": "#E91E63" -``` + + + ```yaml + - name: status + description: "{{ doc(\"orders_status\") }}" + meta: + dimension: + colors: + "placed": "#e6fa0f" + "completed": "#558B2F" + "shipped": "#29B6F6" + "return_pending": "#FF6F00" + "returned": "#E91E63" + ``` + + + ```yaml + - name: status + description: "{{ doc(\"orders_status\") }}" + config: + meta: + dimension: + colors: + "placed": "#e6fa0f" + "completed": "#558B2F" + "shipped": "#29B6F6" + "return_pending": "#FF6F00" + "returned": "#E91E63" + ``` + + ![](/images/references/pie-chart-color-b5c761ad3dc797717c6397920572b1c4.png) From 4568c623b6228ba2b6af888f6d6a652efee81d3b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:01:36 +0000 Subject: [PATCH 40/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 7ac4073f..aa52a490 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -922,16 +922,33 @@ To display images, you define an `image` property with a URL template in your di If your column already contains complete image URLs, you can simply configure it to display as an image: -```yaml -columns: - - name: image_url - description: "Image URL for the event" - meta: - dimension: - type: string - image: - url: "${value.raw}" -``` + + + ```yaml + columns: + - name: image_url + description: "Image URL for the event" + meta: + dimension: + type: string + image: + url: "${value.raw}" + ``` + + + ```yaml + columns: + - name: image_url + description: "Image URL for the event" + config: + meta: + dimension: + type: string + image: + url: "${value.raw}" + ``` + + **With custom dimensions and fit:** From 8adb930f91684921c6d1498042e7334a57272129 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:01:49 +0000 Subject: [PATCH 41/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 46 ++++++++++++++++++++++++++++----------- 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index aa52a490..8b5da767 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -954,19 +954,39 @@ If your column already contains complete image URLs, you can simply configure it You can control the size and display behavior of images using width, height, and fit options: -```yaml -columns: - - name: product_image_url - description: "Product image URL" - meta: - dimension: - type: string - image: - url: "${value.raw}" - width: 100 - height: 100 - fit: "cover" -``` + + + ```yaml + columns: + - name: product_image_url + description: "Product image URL" + meta: + dimension: + type: string + image: + url: "${value.raw}" + width: 100 + height: 100 + fit: "cover" + ``` + + + ```yaml + columns: + - name: product_image_url + description: "Product image URL" + config: + meta: + dimension: + type: string + image: + url: "${value.raw}" + width: 100 + height: 100 + fit: "cover" + ``` + + **Basic example with URL template:** From 6b9259c77539463f67e9a0019fcbc42b3f611621 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:01:59 +0000 Subject: [PATCH 42/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 43 ++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 8b5da767..6dbb840d 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -990,18 +990,37 @@ You can control the size and display behavior of images using width, height, and **Basic example with URL template:** -```yaml -columns: - - name: product_id - meta: - additional_dimensions: - product_image: - type: string - label: "Product Image" - description: "Product thumbnail image" - image: - url: "https://example.com/images/${value.raw}.jpg" -``` + + + ```yaml + columns: + - name: product_id + meta: + additional_dimensions: + product_image: + type: string + label: "Product Image" + description: "Product thumbnail image" + image: + url: "https://example.com/images/${value.raw}.jpg" + ``` + + + ```yaml + columns: + - name: product_id + config: + meta: + additional_dimensions: + product_image: + type: string + label: "Product Image" + description: "Product thumbnail image" + image: + url: "https://example.com/images/${value.raw}.jpg" + ``` + + **Advanced example with dynamic URLs:** From 7b75d9be25c4d54c8afc1c0c4b89339f56517328 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:02:09 +0000 Subject: [PATCH 43/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 43 ++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 6dbb840d..efd457d3 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -1024,18 +1024,37 @@ You can control the size and display behavior of images using width, height, and **Advanced example with dynamic URLs:** -```yaml -columns: - - name: event_type - meta: - additional_dimensions: - event_image: - type: string - label: "Event Image" - description: "Event banner image" - image: - url: "https://cdn.example.com/${value.raw}-${row.events.event_id.raw | upcase}.png" -``` + + + ```yaml + columns: + - name: event_type + meta: + additional_dimensions: + event_image: + type: string + label: "Event Image" + description: "Event banner image" + image: + url: "https://cdn.example.com/${value.raw}-${row.events.event_id.raw | upcase}.png" + ``` + + + ```yaml + columns: + - name: event_type + config: + meta: + additional_dimensions: + event_image: + type: string + label: "Event Image" + description: "Event banner image" + image: + url: "https://cdn.example.com/${value.raw}-${row.events.event_id.raw | upcase}.png" + ``` + + ### Display behavior From 2e5e5984958d8d5cde4e36cddb346317fd52d8d8 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:02:25 +0000 Subject: [PATCH 44/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 141 ++++++++++++++++++++++++++------------ 1 file changed, 97 insertions(+), 44 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index efd457d3..8cc94565 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -1132,50 +1132,103 @@ image: ### Example: Product catalog with images -```yaml -models: - - name: products - columns: - - name: sku - description: "Product SKU code" - meta: - dimension: - type: string - additional_dimensions: - product_thumbnail: - type: string - label: "Product Image" - description: "Product catalog image" - image: - url: "https://cdn.mystore.com/products/${value.raw}/thumbnail.jpg" - width: 80 - height: 80 - fit: "cover" - - name: category - description: "Product category" - meta: - dimension: - type: string - additional_dimensions: - category_icon: - type: string - label: "Category Icon" - description: "Category icon image" - image: - url: "https://cdn.mystore.com/icons/${value.raw | downcase}.png" - width: 40 - height: 40 - fit: "contain" - - name: hero_image_url - description: "Product hero image URL" - meta: - dimension: - type: string - image: - url: "${value.raw}" - width: 120 - fit: "cover" -``` + + + ```yaml + models: + - name: products + columns: + - name: sku + description: "Product SKU code" + meta: + dimension: + type: string + additional_dimensions: + product_thumbnail: + type: string + label: "Product Image" + description: "Product catalog image" + image: + url: "https://cdn.mystore.com/products/${value.raw}/thumbnail.jpg" + width: 80 + height: 80 + fit: "cover" + - name: category + description: "Product category" + meta: + dimension: + type: string + additional_dimensions: + category_icon: + type: string + label: "Category Icon" + description: "Category icon image" + image: + url: "https://cdn.mystore.com/icons/${value.raw | downcase}.png" + width: 40 + height: 40 + fit: "contain" + - name: hero_image_url + description: "Product hero image URL" + meta: + dimension: + type: string + image: + url: "${value.raw}" + width: 120 + fit: "cover" + ``` + + + ```yaml + models: + - name: products + columns: + - name: sku + description: "Product SKU code" + config: + meta: + dimension: + type: string + additional_dimensions: + product_thumbnail: + type: string + label: "Product Image" + description: "Product catalog image" + image: + url: "https://cdn.mystore.com/products/${value.raw}/thumbnail.jpg" + width: 80 + height: 80 + fit: "cover" + - name: category + description: "Product category" + config: + meta: + dimension: + type: string + additional_dimensions: + category_icon: + type: string + label: "Category Icon" + description: "Category icon image" + image: + url: "https://cdn.mystore.com/icons/${value.raw | downcase}.png" + width: 40 + height: 40 + fit: "contain" + - name: hero_image_url + description: "Product hero image URL" + config: + meta: + dimension: + type: string + image: + url: "${value.raw}" + width: 120 + fit: "cover" + ``` + + ## Using special characters or capital letters in your column names From 4637497d665885c25a951dc69be47643ea406af3 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:02:36 +0000 Subject: [PATCH 45/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 8cc94565..4d8eae93 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -1240,13 +1240,27 @@ column orders.status does not exist To fix this, we can add the quoted column to our `sql` meta tag on dimensions -```yaml -- name: status - meta: - dimension: - type: string - sql: '"orders"."Status"' # you can also use '${TABLE}."Status"' -``` + + + ```yaml + - name: status + meta: + dimension: + type: string + sql: '"orders"."Status"' # you can also use '${TABLE}."Status"' + ``` + + + ```yaml + - name: status + config: + meta: + dimension: + type: string + sql: '"orders"."Status"' # you can also use '${TABLE}."Status"' + ``` + + This will quote the `Status` columns on the SQL query From dbbef5e325023422c1029689fd99b085b21256d1 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:02:47 +0000 Subject: [PATCH 46/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 49 ++++++++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 4d8eae93..f189c511 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -1285,20 +1285,41 @@ All [dimension configurations](#dimension-configuration) are available for addit ### Adding different formatting -```yaml -columns: - - name: revenue - meta: - dimension: - type: number - additional_dimensions: - revenue_in_thousands: - type: number - format: '#,##0," K"' - revenue_in_millions: - type: number - format: '#,##0,," M"' -``` + + + ```yaml + columns: + - name: revenue + meta: + dimension: + type: number + additional_dimensions: + revenue_in_thousands: + type: number + format: '#,##0," K"' + revenue_in_millions: + type: number + format: '#,##0,," M"' + ``` + + + ```yaml + columns: + - name: revenue + config: + meta: + dimension: + type: number + additional_dimensions: + revenue_in_thousands: + type: number + format: '#,##0," K"' + revenue_in_millions: + type: number + format: '#,##0,," M"' + ``` + + ### Comparing or combining columns From 82334e22313fe0006761d318fd3700f5950bfd32 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:03:00 +0000 Subject: [PATCH 47/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 55 +++++++++++++++++++++++++++------------ 1 file changed, 39 insertions(+), 16 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index f189c511..036381a1 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -1325,22 +1325,45 @@ All [dimension configurations](#dimension-configuration) are available for addit When defining additional dimensions, you can reference other dimensions, even from joined tables (`organizations` is a joined table in the example below). -```yaml -columns: - - name: created_date - meta: - dimension: - type: date - additional_dimensions: - days_to_first_query_run: - type: number - description: 'Number of days between a user being created and their first query run.' - sql: ${first_query_date} - ${created_date} - days_to_organization_first_payment: - type: number - description: 'Number of days between a user being created and their organization making its first payment. This will be negative for users who joined after the first payment.' - sql: ${created_date} - ${organizations.first_payment_date} -``` + + + ```yaml + columns: + - name: created_date + meta: + dimension: + type: date + additional_dimensions: + days_to_first_query_run: + type: number + description: 'Number of days between a user being created and their first query run.' + sql: ${first_query_date} - ${created_date} + days_to_organization_first_payment: + type: number + description: 'Number of days between a user being created and their organization making its first payment. This will be negative for users who joined after the first payment.' + sql: ${created_date} - ${organizations.first_payment_date} + ``` + + + ```yaml + columns: + - name: created_date + config: + meta: + dimension: + type: date + additional_dimensions: + days_to_first_query_run: + type: number + description: 'Number of days between a user being created and their first query run.' + sql: ${first_query_date} - ${created_date} + days_to_organization_first_payment: + type: number + description: 'Number of days between a user being created and their organization making its first payment. This will be negative for users who joined after the first payment.' + sql: ${created_date} - ${organizations.first_payment_date} + ``` + + ### Parsing JSON columns From b1b79fd7cddbf9e7cd17608e452ad033ce52b180 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:03:14 +0000 Subject: [PATCH 48/75] Update references/dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- references/dimensions.mdx | 40 ++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 036381a1..f8881985 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -1369,17 +1369,35 @@ When defining additional dimensions, you can reference other dimensions, even fr Usually you'll want to add `hidden:true` for the main JSON dimension since raw JSON is not useful in charts. -```yaml -columns: - - name: metadata # this is a jsonb column with metadata - meta: - dimension: - hidden: true - additional_dimensions: - version: - type: number - sql: JSON_VALUE(${metadata}, '$.version') # custom SQL applied to get the "version" value inside metadata -``` + + + ```yaml + columns: + - name: metadata # this is a jsonb column with metadata + meta: + dimension: + hidden: true + additional_dimensions: + version: + type: number + sql: JSON_VALUE(${metadata}, '$.version') # custom SQL applied to get the "version" value inside metadata + ``` + + + ```yaml + columns: + - name: metadata # this is a jsonb column with metadata + config: + meta: + dimension: + hidden: true + additional_dimensions: + version: + type: number + sql: JSON_VALUE(${metadata}, '$.version') # custom SQL applied to get the "version" value inside metadata + ``` + + ### Adding multiple timezones for the same dimension From 4f7979ae3bef53f0f580cd13c8bf9b10304f41e4 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:19:34 +0000 Subject: [PATCH 49/75] Documentation edits made through Mintlify web editor --- references/metrics.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/references/metrics.mdx b/references/metrics.mdx index cfb5fd14..9c7f68e9 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -18,6 +18,7 @@ To add a metric to Lightdash using the `meta` tag, you define it in your dbt pro ```yaml models: - name: orders_model + meta: columns: - name: user_id # dimension your metric is aggregating meta: From a6f1375fdba7ae686b577d238293474611fd7546 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:21:03 +0000 Subject: [PATCH 50/75] Documentation edits made through Mintlify web editor --- references/metrics.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 9c7f68e9..cfb5fd14 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -18,7 +18,6 @@ To add a metric to Lightdash using the `meta` tag, you define it in your dbt pro ```yaml models: - name: orders_model - meta: columns: - name: user_id # dimension your metric is aggregating meta: From 95f337ff55c57a19f8ae1d97aa85947cff1cdf78 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:30:18 +0000 Subject: [PATCH 51/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 74 ++++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index 7c55a0e3..b1b27055 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -20,29 +20,63 @@ It's easy to hide columns from Lightdash. All you need to do is add two words to In your dbt YAML file, it'll look something like this: -```yaml -models: - - name: users - columns: - - name: first_name - meta: - dimension: - hidden: true -``` + + + ```yaml + models: + - name: users + columns: + - name: first_name + meta: + dimension: + hidden: true + ``` + + + ```yaml + models: + - name: users + columns: + - name: first_name + config: + meta: + dimension: + hidden: true + ``` + + The same thing goes for metrics: -```yaml -models: - - name: users - columns: - - name: first_name - meta: - metrics: - count_unique_first_names: - type: count_distinct - hidden: true -``` + + + ```yaml + models: + - name: users + columns: + - name: first_name + meta: + metrics: + count_unique_first_names: + type: count_distinct + hidden: true + ``` + + + ```yaml + models: + - name: users + columns: + - name: first_name + config: + meta: + metrics: + count_unique_first_names: + type: count_distinct + hidden: true + ``` + + By default, all of your dimensions and metrics have been set to `hidden: false`. From 4d4354f98c55678cc7d568a908e38b8f99307089 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:30:35 +0000 Subject: [PATCH 52/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 120 +++++++++++++++++++++--------- 1 file changed, 83 insertions(+), 37 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index b1b27055..430205df 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -92,44 +92,90 @@ You can group related metrics and dimensions together using the model meta `grou For example you might want to group the percentile metrics into two sub categories one being for over 40 percentiles and the other for under 40 percentiles. You can do this by adding the `group` property to your metrics like so: -```yaml -models: - - name: events - meta: - group_details: - events: - label: Events - description: Event-related fields. - percentile: - label: Percentiles - description: Grouping of percentiles - sub: - label: Percentiles under 40 - description: Grouping of percentiles under 40 - over: - label: Percentiles over 40 - description: Grouping percentiles over 40 - columns: - - name: event_id - description: '' + + + ```yaml + models: + - name: events meta: - dimension: - type: number - groups: ['events'] - metrics: - percentile_25: - type: percentile - percentile: 25 - groups: ['percentile', 'sub'] - percentile_50: - type: percentile - percentile: 50 - groups: ['percentile', 'over'] - percentile_75: - type: percentile - percentile: 75 - groups: ['percentile', 'over'] -``` + group_details: + events: + label: Events + description: Event-related fields. + percentile: + label: Percentiles + description: Grouping of percentiles + sub: + label: Percentiles under 40 + description: Grouping of percentiles under 40 + over: + label: Percentiles over 40 + description: Grouping percentiles over 40 + columns: + - name: event_id + description: '' + meta: + dimension: + type: number + groups: ['events'] + metrics: + percentile_25: + type: percentile + percentile: 25 + groups: ['percentile', 'sub'] + percentile_50: + type: percentile + percentile: 50 + groups: ['percentile', 'over'] + percentile_75: + type: percentile + percentile: 75 + groups: ['percentile', 'over'] + ``` + + + ```yaml + models: + - name: events + config: + meta: + group_details: + events: + label: Events + description: Event-related fields. + percentile: + label: Percentiles + description: Grouping of percentiles + sub: + label: Percentiles under 40 + description: Grouping of percentiles under 40 + over: + label: Percentiles over 40 + description: Grouping percentiles over 40 + columns: + - name: event_id + description: '' + config: + meta: + dimension: + type: number + groups: ['events'] + metrics: + percentile_25: + type: percentile + percentile: 25 + groups: ['percentile', 'sub'] + percentile_50: + type: percentile + percentile: 50 + groups: ['percentile', 'over'] + percentile_75: + type: percentile + percentile: 75 + groups: ['percentile', 'over'] + ``` + + From 4917b0099c009eaa44c90df034686d3e9bda2432 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:30:47 +0000 Subject: [PATCH 53/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 37 ++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index 430205df..aeebbe76 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -191,16 +191,33 @@ You can use groups across metrics and dimensions. In the sidebar, your metrics w By default, Lightdash pulls in the descriptions you've included for your dimensions. But, you can override the description you see in Lightdash using the `description` property. -```yaml -models: - - name: users - columns: - - name: user_id - description: "Id generated by the Lightdash API on user's first login. On legacy systems, SHA64. On new systems since 2012, FARM_FINGERPRINT()" - meta: - dimension: - description: 'Unique identifier for a user' -``` + + + ```yaml + models: + - name: users + columns: + - name: user_id + description: "Id generated by the Lightdash API on user's first login. On legacy systems, SHA64. On new systems since 2012, FARM_FINGERPRINT()" + meta: + dimension: + description: 'Unique identifier for a user' + ``` + + + ```yaml + models: + - name: users + columns: + - name: user_id + description: "Id generated by the Lightdash API on user's first login. On legacy systems, SHA64. On new systems since 2012, FARM_FINGERPRINT()" + config: + meta: + dimension: + description: 'Unique identifier for a user' + ``` + + You can see the descriptions of your dimensions when you hover over the fields in Lightdash. From 33e7b5ed6ff85be2dbf44871926f85b50e155c2b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:30:57 +0000 Subject: [PATCH 54/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 43 ++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index aeebbe76..547c5d5c 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -229,18 +229,37 @@ You can see the descriptions of your dimensions when you hover over the fields i If you don't add a custom description for your metric, Lightdash will show a description for you in the app, by default. To override this default description, you can use the `description` property. -```yaml -models: - - name: users - columns: - - name: user_id - description: "Id generated by the Lightdash API on user's first login. On legacy systems, SHA64. On new systems since 2012, FARM_FINGERPRINT()" - meta: - metrics: - count_unique_users: - type: count_distinct - description: 'Count the unique number of user IDs' -``` + + + ```yaml + models: + - name: users + columns: + - name: user_id + description: "Id generated by the Lightdash API on user's first login. On legacy systems, SHA64. On new systems since 2012, FARM_FINGERPRINT()" + meta: + metrics: + count_unique_users: + type: count_distinct + description: 'Count the unique number of user IDs' + ``` + + + ```yaml + models: + - name: users + columns: + - name: user_id + description: "Id generated by the Lightdash API on user's first login. On legacy systems, SHA64. On new systems since 2012, FARM_FINGERPRINT()" + config: + meta: + metrics: + count_unique_users: + type: count_distinct + description: 'Count the unique number of user IDs' + ``` + + Check out [this doc](/references/metrics#metric-configuration) to see all of the other properties you can customize for metrics. From 5b7be7428ab81800e9d22f3ae46fdddecfc02988 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:31:05 +0000 Subject: [PATCH 55/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 34 +++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index 547c5d5c..8e218093 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -272,15 +272,31 @@ To change the name you'll see for your field in Lightdash, you just use the `lab So, if I had a field `user_id_sha64`, I could relabel it to `User ID`. -```yaml -models: - - name: users - columns: - - name: user_id_sha64 - meta: - dimension: - label: 'User ID' -``` + + + ```yaml + models: + - name: users + columns: + - name: user_id_sha64 + meta: + dimension: + label: 'User ID' + ``` + + + ```yaml + models: + - name: users + columns: + - name: user_id_sha64 + config: + meta: + dimension: + label: 'User ID' + ``` + + Same thing goes for metrics! From 2fab3b903af0d0828c7b5a06628e2618aaeb9571 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:31:15 +0000 Subject: [PATCH 56/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 40 ++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index 8e218093..cf2807b1 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -304,17 +304,35 @@ Same thing goes for metrics! Relabelling a metric will not break any saved charts that use the old metric name. Instead, your saved charts will just use the new metric name in their results tables. -```yaml -models: - - name: users - columns: - - name: user_id_sha64 - meta: - metrics: - count_unique_user_ids: - type: count_distinct - label: 'Total users' -``` + + + ```yaml + models: + - name: users + columns: + - name: user_id_sha64 + meta: + metrics: + count_unique_user_ids: + type: count_distinct + label: 'Total users' + ``` + + + ```yaml + models: + - name: users + columns: + - name: user_id_sha64 + config: + meta: + metrics: + count_unique_user_ids: + type: count_distinct + label: 'Total users' + ``` + + Check out [this doc](/references/dimensions#dimension-configuration) to see all of the other properties you can customize for dimensions, and [this one](/references/metrics#metric-configuration) for all of the other properties you can customize for your metrics. From b77c7afe4afb248044e4bffdfd78cb6eb123e243 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:32:37 +0000 Subject: [PATCH 57/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 74 ++++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index cf2807b1..38b8acb3 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -354,32 +354,66 @@ Here's an example of how different rounding will affect your numbers: Like this: -```yaml -models: - - name: sales - columns: - - name: revenue - meta: - dimension: - format: '0.00' -``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + dimension: + format: '0.00' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + dimension: + format: '0.00' + ``` + + #### Rounding metrics Like this: -```yaml -models: - - name: sales - columns: - - name: revenue - meta: - metrics: - total_revenue: - type: sum - format: '0.00' -``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + metrics: + total_revenue: + type: sum + format: '0.00' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + metrics: + total_revenue: + type: sum + format: '0.00' + ``` + + Check out [this doc](https://docs.lightdash.com/references/metrics#metric-configuration) to see all of the other properties you can customize for metrics. From dc502fb5a7ad0b9db40c6df00f1ba452ffe0741e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:32:48 +0000 Subject: [PATCH 58/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 74 ++++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index 38b8acb3..623dd55f 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -433,15 +433,31 @@ Here's an example of how different compacting will affect your numbers: Like this: -```yaml -models: - - name: sales - columns: - - name: revenue - meta: - dimension: - format: '0," K"' -``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + dimension: + format: '0," K"' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + dimension: + format: '0," K"' + ``` + + As an example, this option will compact the number value from 1,500 to 1.50K. @@ -451,17 +467,35 @@ Check out [this doc](https://docs.lightdash.com/references/dimensions#format) to Like this: -```yaml -models: - - name: sales - columns: - - name: revenue - meta: - metrics: - total_revenue: - type: sum - format: '0.00,,," B"' -``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + metrics: + total_revenue: + type: sum + format: '0.00,,," B"' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + metrics: + total_revenue: + type: sum + format: '0.00,,," B"' + ``` + + As an example, this option will compact the number value from 1,500,000,000 to 1.50B. From 526f8dde5a9afe5d0fc63276f3c1205a9d85511c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:32:59 +0000 Subject: [PATCH 59/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 74 ++++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index 623dd55f..eed39b75 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -518,15 +518,31 @@ Here's an example of how different formats will affect your values: You can add a `format` to your dimensions this: -```yaml -models: - - name: sales - columns: - - name: revenue - meta: - dimension: - format: '[$£]#,##0.00' -``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + dimension: + format: '[$£]#,##0.00' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + dimension: + format: '[$£]#,##0.00' + ``` + + To see which format types are available for dimensions, [check the reference docs here.](/references/dimensions#format). Check out [this doc](/references/dimensions#dimension-configuration) to see all of the other properties you can customize for dimensions. @@ -534,17 +550,35 @@ To see which format types are available for dimensions, [check the reference doc You can add a `format` to your metrics this: -```yaml -models: - - name: sales - columns: - - name: revenue - meta: - metrics: - total_revenue: - type: sum - format: '[$£]#,##0.00' -``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + metrics: + total_revenue: + type: sum + format: '[$£]#,##0.00' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + metrics: + total_revenue: + type: sum + format: '[$£]#,##0.00' + ``` + + To see which format types are available for metrics, [check the reference docs here.](/references/metrics#format)Check out [this doc](/references/metrics#metric-configuration) to see all of the other properties you can customize for metrics. From 9f79053a36f63d77fe61ba343d73916e7bd69815 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:33:07 +0000 Subject: [PATCH 60/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 40 ++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index eed39b75..2375e559 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -612,17 +612,35 @@ parameters: In your model YAML file: -```yaml -models: - - name: sales - columns: - - name: revenue - meta: - metrics: - total_revenue: - type: sum - format: '${ld.parameters.currency_symbol}0,0.00' -``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + metrics: + total_revenue: + type: sum + format: '${ld.parameters.currency_symbol}0,0.00' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + metrics: + total_revenue: + type: sum + format: '${ld.parameters.currency_symbol}0,0.00' + ``` + + The format `'${ld.parameters.currency_symbol}0,0.00'` will substitute the selected currency symbol value directly into the format. From 266f723ed34c79ed23bc0fe8f2fcea37fa16cef0 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:33:25 +0000 Subject: [PATCH 61/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 40 ++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index 2375e559..e075fb87 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -676,17 +676,35 @@ parameters: In your model YAML file: -```yaml -models: - - name: sales - columns: - - name: revenue - meta: - metrics: - total_revenue: - type: sum - format: '${ld.parameters.currency=="usd"?"$":""}${ld.parameters.currency=="eur"?"€":""}${ld.parameters.currency=="eur"?"£":""}0,0.00' -``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + metrics: + total_revenue: + type: sum + format: '${ld.parameters.currency=="usd"?"$":""}${ld.parameters.currency=="eur"?"€":""}${ld.parameters.currency=="eur"?"£":""}0,0.00' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + metrics: + total_revenue: + type: sum + format: '${ld.parameters.currency=="usd"?"$":""}${ld.parameters.currency=="eur"?"€":""}${ld.parameters.currency=="eur"?"£":""}0,0.00' + ``` + + The format uses multiple ternary expressions to check the parameter value: - When `currency` is `"usd"`, displays `$1,234.56` From d3959825b542256055871b1d324acc6540d9f2cc Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:33:36 +0000 Subject: [PATCH 62/75] Update guides/formatting-your-fields.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/formatting-your-fields.mdx | 40 ++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index e075fb87..a2a4c742 100644 --- a/guides/formatting-your-fields.mdx +++ b/guides/formatting-your-fields.mdx @@ -730,17 +730,35 @@ parameters: Then use it in your model YAML file: -```yaml -models: - - name: sales - columns: - - name: revenue - meta: - metrics: - total_revenue: - type: sum - format: '0,0${ld.parameters.decimals=="true"?".00":""}' -``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + meta: + metrics: + total_revenue: + type: sum + format: '0,0${ld.parameters.decimals=="true"?".00":""}' + ``` + + + ```yaml + models: + - name: sales + columns: + - name: revenue + config: + meta: + metrics: + total_revenue: + type: sum + format: '0,0${ld.parameters.decimals=="true"?".00":""}' + ``` + + When `decimals` is `"true"`, numbers display as `$1,234.56`. When `decimals` is `"false"`, numbers display as `$1,235`. From 90d6042376e8f17576934c196a9915cd7fbafe9b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:33:50 +0000 Subject: [PATCH 63/75] Update guides/adding-tables-to-lightdash.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/adding-tables-to-lightdash.mdx | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/guides/adding-tables-to-lightdash.mdx b/guides/adding-tables-to-lightdash.mdx index 35714b0b..3aa58fa5 100644 --- a/guides/adding-tables-to-lightdash.mdx +++ b/guides/adding-tables-to-lightdash.mdx @@ -176,12 +176,24 @@ There may be a specific set of models that you want include as Tables in Lightda You can add tags to your YAML file like this: -```yaml -models: - - name: model_name - config: - tags: ['prod'] -``` + + + ```yaml + models: + - name: model_name + config: + tags: ['prod'] + ``` + + + ```yaml + models: + - name: model_name + config: + tags: ['prod'] + ``` + + Or, to your model's SQL file in the config block: From d9e8f635a93d1ddb6c74fd70a1a91acb72942a3b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:34:15 +0000 Subject: [PATCH 64/75] Update guides/explores.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/explores.mdx | 110 +++++++++++++++++++++++++++++++------------- 1 file changed, 78 insertions(+), 32 deletions(-) diff --git a/guides/explores.mdx b/guides/explores.mdx index ab45e50a..05c4f8e8 100644 --- a/guides/explores.mdx +++ b/guides/explores.mdx @@ -30,43 +30,89 @@ Use the explores config when you want to create tailored versions of the same ta This is your regular dbt model, for example, `deals`. - ```yaml - models: - - name: deals - meta: - primary_key: deal_id - ``` + + + ```yaml + models: + - name: deals + meta: + primary_key: deal_id + ``` + + + ```yaml + models: + - name: deals + config: + meta: + primary_key: deal_id + ``` + + Use the `explores` config to define multiple versions of the table. Each explore has its own `label`, `joins`, joined fields, and access rules. - ```yaml - models: - - name: deals - meta: - primary_key: deal_id - label: Deals (Basic) - description: Basic deals table with no joins - explores: - deals_accounts: - label: Deals w/Accounts - description: Deals table with accounts joined in, limited acount fields included - joins: - - join: accounts - relationship: many-to-one - sql_on: ${deals.account_id} = ${accounts.account_id} - fields: [industry, segment, count_accounts] - deals_exec_view: - label: Deals (Exec View) - description: Deals table with account info, for execs only, all acount fields included - required_attributes: - is_exec: "true" - joins: - - join: accounts - relationship: many-to-one - sql_on: ${deals.account_id} = ${accounts.account_id} - ``` + + + ```yaml + models: + - name: deals + meta: + primary_key: deal_id + label: Deals (Basic) + description: Basic deals table with no joins + explores: + deals_accounts: + label: Deals w/Accounts + description: Deals table with accounts joined in, limited acount fields included + joins: + - join: accounts + relationship: many-to-one + sql_on: ${deals.account_id} = ${accounts.account_id} + fields: [industry, segment, count_accounts] + deals_exec_view: + label: Deals (Exec View) + description: Deals table with account info, for execs only, all acount fields included + required_attributes: + is_exec: "true" + joins: + - join: accounts + relationship: many-to-one + sql_on: ${deals.account_id} = ${accounts.account_id} + ``` + + + ```yaml + models: + - name: deals + config: + meta: + primary_key: deal_id + label: Deals (Basic) + description: Basic deals table with no joins + explores: + deals_accounts: + label: Deals w/Accounts + description: Deals table with accounts joined in, limited acount fields included + joins: + - join: accounts + relationship: many-to-one + sql_on: ${deals.account_id} = ${accounts.account_id} + fields: [industry, segment, count_accounts] + deals_exec_view: + label: Deals (Exec View) + description: Deals table with account info, for execs only, all acount fields included + required_attributes: + is_exec: "true" + joins: + - join: accounts + relationship: many-to-one + sql_on: ${deals.account_id} = ${accounts.account_id} + ``` + + Once you commit and deploy your dbt changes: From a503310ddcf97338942d49a0d8d0c532b67335c6 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:34:25 +0000 Subject: [PATCH 65/75] Update guides/explores.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/explores.mdx | 58 ++++++++++++++++++++++++++++++++------------- 1 file changed, 41 insertions(+), 17 deletions(-) diff --git a/guides/explores.mdx b/guides/explores.mdx index 05c4f8e8..86b92a8e 100644 --- a/guides/explores.mdx +++ b/guides/explores.mdx @@ -156,23 +156,47 @@ Use `additional_dimensions` to define dimensions that are scoped only to a speci ### Example -```yaml -models: - - name: orders - meta: - primary_key: order_id - explores: - orders_with_custom_dims: - label: Orders with Custom Dimensions - joins: - - join: customers - sql_on: ${orders.customer_id} = ${customers.customer_id} - additional_dimensions: - full_name: - type: string - sql: "CONCAT(${customers.first_name}, ' ', ${customers.last_name})" - label: Customer Full Name -``` + + + ```yaml + models: + - name: orders + meta: + primary_key: order_id + explores: + orders_with_custom_dims: + label: Orders with Custom Dimensions + joins: + - join: customers + sql_on: ${orders.customer_id} = ${customers.customer_id} + additional_dimensions: + full_name: + type: string + sql: "CONCAT(${customers.first_name}, ' ', ${customers.last_name})" + label: Customer Full Name + ``` + + + ```yaml + models: + - name: orders + config: + meta: + primary_key: order_id + explores: + orders_with_custom_dims: + label: Orders with Custom Dimensions + joins: + - join: customers + sql_on: ${orders.customer_id} = ${customers.customer_id} + additional_dimensions: + full_name: + type: string + sql: "CONCAT(${customers.first_name}, ' ', ${customers.last_name})" + label: Customer Full Name + ``` + + ### Available properties From 47e4934e1ca988ae4c45d974ee4816d4bdc31305 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:34:43 +0000 Subject: [PATCH 66/75] Update get-started/develop-in-lightdash/how-to-create-dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- .../how-to-create-dimensions.mdx | 33 ++++++++++++++----- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/get-started/develop-in-lightdash/how-to-create-dimensions.mdx b/get-started/develop-in-lightdash/how-to-create-dimensions.mdx index 84999847..d1298cec 100644 --- a/get-started/develop-in-lightdash/how-to-create-dimensions.mdx +++ b/get-started/develop-in-lightdash/how-to-create-dimensions.mdx @@ -76,15 +76,30 @@ We recommend using the CLI because it's faster and more reliable. But, if you're For example, if I had a column in my dbt model called `source` and I wanted to add it as a dimension to Lightdash, I would just add the column to my .yml file like so: -```yaml -models: - - name: Pages - description: "A table of all page views on Lightdash webpages." - columns: - - name: source - description: "The source of the page view: the demo site, docs site, or lightdash.com" - ... -``` + + + ```yaml + models: + - name: Pages + description: "A table of all page views on Lightdash webpages." + columns: + - name: source + description: "The source of the page view: the demo site, docs site, or lightdash.com" + ... + ``` + + + ```yaml + models: + - name: Pages + description: "A table of all page views on Lightdash webpages." + columns: + - name: source + description: "The source of the page view: the demo site, docs site, or lightdash.com" + ... + ``` + + *** From 60957f6c55ebb93d90c14acb385d7f268acf8870 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:34:55 +0000 Subject: [PATCH 67/75] Update get-started/develop-in-lightdash/how-to-create-dimensions.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- .../how-to-create-dimensions.mdx | 46 +++++++++++++------ 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/get-started/develop-in-lightdash/how-to-create-dimensions.mdx b/get-started/develop-in-lightdash/how-to-create-dimensions.mdx index d1298cec..cbb24e9e 100644 --- a/get-started/develop-in-lightdash/how-to-create-dimensions.mdx +++ b/get-started/develop-in-lightdash/how-to-create-dimensions.mdx @@ -123,19 +123,39 @@ Then `cmd` + `click` to open the preview link from your terminal. Once you're in You can jazz up your dimensions by configuring them in your .yml files. These dimension configurations live under the `meta` tag of your columns, under `dimension`: -```yaml -models: - - name: orders - description: "A table of all orders." - columns: - - name: status - description: "Status from org256 settings codes. Referenced at delivery from stat5 zone." - meta: - dimension: - label: "Status latest" - description: "Status of an order: ordered/processed/complete" - ...etc -``` + + + ```yaml + models: + - name: orders + description: "A table of all orders." + columns: + - name: status + description: "Status from org256 settings codes. Referenced at delivery from stat5 zone." + meta: + dimension: + label: "Status latest" + description: "Status of an order: ordered/processed/complete" + ...etc + ``` + + + ```yaml + models: + - name: orders + description: "A table of all orders." + columns: + - name: status + description: "Status from org256 settings codes. Referenced at delivery from stat5 zone." + config: + meta: + dimension: + label: "Status latest" + description: "Status of an order: ordered/processed/complete" + ...etc + ``` + + Things like the format, the label that people see in Lightdash, rounding, etc. - these are all configurations that you can apply to your dimensions. From 4a33669cc5716343c6a8934f1d4b6735087584d2 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:35:13 +0000 Subject: [PATCH 68/75] Update get-started/develop-in-lightdash/how-to-create-metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- .../how-to-create-metrics.mdx | 62 +++++++++++++------ 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/get-started/develop-in-lightdash/how-to-create-metrics.mdx b/get-started/develop-in-lightdash/how-to-create-metrics.mdx index 4017369d..64dbd9a1 100644 --- a/get-started/develop-in-lightdash/how-to-create-metrics.mdx +++ b/get-started/develop-in-lightdash/how-to-create-metrics.mdx @@ -12,24 +12,50 @@ If dimensions segment your data into groups, metrics calculate interesting stati For example, if we have a dimension, `status`, to split orders by their `status`, we may want to know the "Total number of orders" or the "Total sales" of the orders. These calculations are metrics: -```yaml -models: - - name: 'orders' - description: 'A table of all orders.' - columns: - - name: 'status' - description: 'Status of an order: ordered/processed/complete' - - name: 'order_id' - meta: - metrics: - total_order_count: - type: count_distinct - - name: 'order_value' - meta: - metrics: - total_sales: - type: sum -``` + + + ```yaml + models: + - name: 'orders' + description: 'A table of all orders.' + columns: + - name: 'status' + description: 'Status of an order: ordered/processed/complete' + - name: 'order_id' + meta: + metrics: + total_order_count: + type: count_distinct + - name: 'order_value' + meta: + metrics: + total_sales: + type: sum + ``` + + + ```yaml + models: + - name: 'orders' + description: 'A table of all orders.' + columns: + - name: 'status' + description: 'Status of an order: ordered/processed/complete' + - name: 'order_id' + config: + meta: + metrics: + total_order_count: + type: count_distinct + - name: 'order_value' + config: + meta: + metrics: + total_sales: + type: sum + ``` + + You can [see the full list of metric types](/references/metrics#metric-types) that you can use in your Lightdash project. From 7d3aee1a7b9262a49e0e591699549ed810c351c5 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:35:21 +0000 Subject: [PATCH 69/75] Update get-started/develop-in-lightdash/how-to-create-metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- .../how-to-create-metrics.mdx | 40 ++++++++++++++----- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/get-started/develop-in-lightdash/how-to-create-metrics.mdx b/get-started/develop-in-lightdash/how-to-create-metrics.mdx index 64dbd9a1..59e1138d 100644 --- a/get-started/develop-in-lightdash/how-to-create-metrics.mdx +++ b/get-started/develop-in-lightdash/how-to-create-metrics.mdx @@ -94,17 +94,35 @@ We'd suggest starting out simple, like a `count` for a primary key in your table For example: -```yaml -models: - - name: 'orders' - columns: - - name: 'status' - - name: 'order_id' - meta: - metrics: - total_order_count: - type: count -``` + + + ```yaml + models: + - name: 'orders' + columns: + - name: 'status' + - name: 'order_id' + meta: + metrics: + total_order_count: + type: count + ``` + + + ```yaml + models: + - name: 'orders' + columns: + - name: 'status' + - name: 'order_id' + config: + meta: + metrics: + total_order_count: + type: count + ``` + + ### Preview your changes using `lightdash preview` From 7e6bfe11525cd957cb67342350f50fbe80bfde08 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:35:36 +0000 Subject: [PATCH 70/75] Update get-started/develop-in-lightdash/how-to-create-metrics.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- .../how-to-create-metrics.mdx | 58 +++++++++++++------ 1 file changed, 41 insertions(+), 17 deletions(-) diff --git a/get-started/develop-in-lightdash/how-to-create-metrics.mdx b/get-started/develop-in-lightdash/how-to-create-metrics.mdx index 59e1138d..e5967de5 100644 --- a/get-started/develop-in-lightdash/how-to-create-metrics.mdx +++ b/get-started/develop-in-lightdash/how-to-create-metrics.mdx @@ -142,23 +142,47 @@ Then `cmd` + `click` to open the preview link from your terminal. Once you're in You can jazz up your metrics by configuring them in your .yml files. These metric configurations live under the `meta` tag of your columns, under `metrics`: -```yaml -models: - - name: "orders" - description: "A table of all orders." - columns: - - name: "status" - description: "Status of an order: ordered/processed/complete" - - name: "order_value" - meta: - metrics: - total_sales: - type: sum - label: "Total sales (USD)" - groups: ["Sales metrics"] - round: 2 - ...etc. -``` + + + ```yaml + models: + - name: "orders" + description: "A table of all orders." + columns: + - name: "status" + description: "Status of an order: ordered/processed/complete" + - name: "order_value" + meta: + metrics: + total_sales: + type: sum + label: "Total sales (USD)" + groups: ["Sales metrics"] + round: 2 + ...etc. + ``` + + + ```yaml + models: + - name: "orders" + description: "A table of all orders." + columns: + - name: "status" + description: "Status of an order: ordered/processed/complete" + - name: "order_value" + config: + meta: + metrics: + total_sales: + type: sum + label: "Total sales (USD)" + groups: ["Sales metrics"] + round: 2 + ...etc. + ``` + + Things like the format, the label that people see in Lightdash, rounding, etc. - these are all configurations that you can apply to your metrics. From edff73b4a7eda04adf418c132bcdd78e651aca36 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:41:52 +0000 Subject: [PATCH 71/75] Documentation edits made through Mintlify web editor --- guides/adding-tables-to-lightdash.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guides/adding-tables-to-lightdash.mdx b/guides/adding-tables-to-lightdash.mdx index 3aa58fa5..9e96ae8d 100644 --- a/guides/adding-tables-to-lightdash.mdx +++ b/guides/adding-tables-to-lightdash.mdx @@ -181,8 +181,7 @@ You can add tags to your YAML file like this: ```yaml models: - name: model_name - config: - tags: ['prod'] + tags: ['prod'] ``` From 5c4a707a61945df71bb9103ee0441156f6759796 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:48:38 +0000 Subject: [PATCH 72/75] Update guides/period-over-period.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/period-over-period.mdx | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/guides/period-over-period.mdx b/guides/period-over-period.mdx index 9d501ce0..74464881 100644 --- a/guides/period-over-period.mdx +++ b/guides/period-over-period.mdx @@ -238,6 +238,8 @@ To do this, you: 1. **Set up your date range / period parameter** + + ``` yaml models: - name: dbt_orders @@ -253,6 +255,26 @@ To do this, you: - "last 30 days" default: "last 7 days" ``` + + + ``` yaml + models: + - name: dbt_orders + description: 'This table contains information on all the confirmed orders and their status' + config: + meta: + parameters: + date_range: + label: "Date Range" + description: "Choose a date range" + options: + - "yesterday" + - "last 7 days" + - "last 30 days" + default: "last 7 days" + ``` + + You can also take a look at the `Date Range` parameter setup in our demo dbt project [here](https://github.com/lightdash/lightdash-demo-data-gardening/blob/06ec6e4a87286ec7504d20b10f4b919bd267ebae/dbt-bigquery/models/dbt_orders.yml#L15-L22). From 3026cbfb03ec8a89c94ab5d0b7ba250100dc0d4c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:49:07 +0000 Subject: [PATCH 73/75] Update guides/period-over-period.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/period-over-period.mdx | 69 +++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/guides/period-over-period.mdx b/guides/period-over-period.mdx index 74464881..4ab88ff6 100644 --- a/guides/period-over-period.mdx +++ b/guides/period-over-period.mdx @@ -283,6 +283,8 @@ To do this, you: Next, you need to create an additional dimension inside the `dbt_orders` model that calculates the period selected in the `date_range` parameter using conditional case statements. + + ``` yaml models: - name: dbt_orders @@ -344,6 +346,73 @@ To do this, you: else 'out of range' end ``` + + + ``` yaml + models: + - name: dbt_orders + description: 'This table contains information on all the confirmed orders and their status' + config: + meta: + parameters: + date_range: + label: "Date Range" + description: "Choose a date range" + options: + - "yesterday" + - "last 7 days" + - "last 30 days" + default: "last 7 days" + label: Orders + columns: + - name: order_date + description: 'Timestamp of order placement by user.' + config: + meta: + dimension: + time_intervals: [ + 'HOUR', 'MINUTE_OF_HOUR_NUM', 'HOUR_OF_DAY_NUM', + 'DAY', 'DAY_OF_WEEK_INDEX', 'DAY_OF_MONTH_NUM', 'DAY_OF_YEAR_NUM', + 'DAY_OF_WEEK_NAME', 'WEEK', 'WEEK_NUM', + 'MONTH', 'MONTH_NUM', 'MONTH_NAME', + 'QUARTER', 'QUARTER_NUM', 'QUARTER_NAME', + 'YEAR' ] + type: timestamp + additional_dimensions: + order_date_period: + description: Date period (current period or previous period or previous year or out of range) chosen by the date_range parameter + type: string + sql: > + case + -- current period + when ( + (${lightdash.parameters.dbt_orders.date_range} = 'yesterday' and date(${order_date}) = date_sub(current_date(), interval 1 day)) or + (${lightdash.parameters.dbt_orders.date_range} = 'last 7 days' and date(${order_date}) between date_sub(current_date(), interval 7 day) and date_sub(current_date(), interval 1 day)) or + (${lightdash.parameters.dbt_orders.date_range} = 'last 30 days' and date(${order_date}) between date_sub(current_date(), interval 30 day) and date_sub(current_date(), interval 1 day)) + ) + then 'current period' + + -- previous period + when ( + (${lightdash.parameters.dbt_orders.date_range} = 'yesterday' and date(${order_date}) = date_sub(current_date(), interval 2 day)) or + (${lightdash.parameters.dbt_orders.date_range} = 'last 7 days' and date(${order_date}) between date_sub(current_date(), interval 14 day) and date_sub(current_date(), interval 8 day)) or + (${lightdash.parameters.dbt_orders.date_range} = 'last 30 days' and date(${order_date}) between date_sub(current_date(), interval 60 day) and date_sub(current_date(), interval 31 day)) + ) + then 'previous period' + + -- previous year + when ( + (${lightdash.parameters.dbt_orders.date_range} = 'yesterday' and date(${order_date}) = date_sub(date_sub(current_date(), interval 1 year), interval 1 day)) or + (${lightdash.parameters.dbt_orders.date_range} = 'last 7 days' and date(${order_date}) between date_sub(date_sub(current_date(), interval 1 year), interval 7 day) and date_sub(date_sub(current_date(), interval 1 year), interval 1 day)) or + (${lightdash.parameters.dbt_orders.date_range} = 'last 30 days' and date(${order_date}) between date_sub(date_sub(current_date(), interval 1 year), interval 30 day) and date_sub(date_sub(current_date(), interval 1 year), interval 1 day)) + ) + then 'previous year' + + else 'out of range' + end + ``` + + You can also take a look at the `order_date_period` dimension setup in our demo dbt project [here](https://github.com/lightdash/lightdash-demo-data-gardening/blob/06ec6e4a87286ec7504d20b10f4b919bd267ebae/dbt-bigquery/models/dbt_orders.yml#L57-L87). From d2c050a08bbeaf00dca2ed8f650c9b1823f4eb4c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:49:15 +0000 Subject: [PATCH 74/75] Update guides/period-over-period.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/period-over-period.mdx | 42 +++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/guides/period-over-period.mdx b/guides/period-over-period.mdx index 4ab88ff6..b48f6d39 100644 --- a/guides/period-over-period.mdx +++ b/guides/period-over-period.mdx @@ -441,17 +441,41 @@ Similar to above, you can also set up a custom date range parameter that allows Below is the code needed for the parameter and the additional dimension to categorize the date periods for a custom date range: + + ``` yaml -parameters: - custom_range_start: - label: "Start of custom date range" - description: "The start of the custom date range" - type: date - custom_range_end: - label: "End of custom date range" - description: "The end of the custom date range" - type: date +models: + - name: dbt_orders + meta: + parameters: + custom_range_start: + label: "Start of custom date range" + description: "The start of the custom date range" + type: date + custom_range_end: + label: "End of custom date range" + description: "The end of the custom date range" + type: date ``` + + +``` yaml +models: + - name: dbt_orders + config: + meta: + parameters: + custom_range_start: + label: "Start of custom date range" + description: "The start of the custom date range" + type: date + custom_range_end: + label: "End of custom date range" + description: "The end of the custom date range" + type: date +``` + + From b1032dc425399c3142df2f18440035dd5f29be9e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 16:49:49 +0000 Subject: [PATCH 75/75] Update guides/period-over-period.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/period-over-period.mdx | 148 +++++++++++++++++++++++----------- 1 file changed, 103 insertions(+), 45 deletions(-) diff --git a/guides/period-over-period.mdx b/guides/period-over-period.mdx index b48f6d39..6913e9e5 100644 --- a/guides/period-over-period.mdx +++ b/guides/period-over-period.mdx @@ -480,55 +480,113 @@ models: + + ``` yaml -- name: order_date - description: 'Date of order placement by user.' - meta: - dimension: - type: date - additional_dimensions: - order_date_custom_period: - description: Date period bucket based on custom Start date and End date parameters - type: string - sql: | - case - --invalid date range - when ${lightdash.parameters.dbt_orders.custom_range_start} is null - or ${lightdash.parameters.dbt_orders.custom_range_end} is null - or ${lightdash.parameters.dbt_orders.custom_range_start} > ${lightdash.parameters.dbt_orders.custom_range_end} - then 'invalid date range' - - --current period - when ${order_date_day} >= ${lightdash.parameters.dbt_orders.custom_range_start} - and ${order_date_day} <= ${lightdash.parameters.dbt_orders.custom_range_end} - then 'current period' - - --previous period - when ${order_date_day} between date_sub( - ${lightdash.parameters.dbt_orders.custom_range_start}, - interval (date_diff( - ${lightdash.parameters.dbt_orders.custom_range_end}, +columns: + - name: order_date + description: 'Date of order placement by user.' + meta: + dimension: + type: date + additional_dimensions: + order_date_custom_period: + description: Date period bucket based on custom Start date and End date parameters + type: string + sql: | + case + --invalid date range + when ${lightdash.parameters.dbt_orders.custom_range_start} is null + or ${lightdash.parameters.dbt_orders.custom_range_end} is null + or ${lightdash.parameters.dbt_orders.custom_range_start} > ${lightdash.parameters.dbt_orders.custom_range_end} + then 'invalid date range' + + --current period + when ${order_date_day} >= ${lightdash.parameters.dbt_orders.custom_range_start} + and ${order_date_day} <= ${lightdash.parameters.dbt_orders.custom_range_end} + then 'current period' + + --previous period + when ${order_date_day} between date_sub( ${lightdash.parameters.dbt_orders.custom_range_start}, - day - ) + 1) day - ) and date_sub( - ${lightdash.parameters.dbt_orders.custom_range_end}, - interval (date_diff( + interval (date_diff( + ${lightdash.parameters.dbt_orders.custom_range_end}, + ${lightdash.parameters.dbt_orders.custom_range_start}, + day + ) + 1) day + ) and date_sub( ${lightdash.parameters.dbt_orders.custom_range_end}, - ${lightdash.parameters.dbt_orders.custom_range_start}, - day - ) + 1) day - ) - then 'previous period' - - --previous year - when date(${order_date_day}) between date_sub(${lightdash.parameters.dbt_orders.custom_range_start}, interval 1 year) - and date_sub(${lightdash.parameters.dbt_orders.custom_range_end}, interval 1 year) - then 'previous year' - - else 'out of range' - end + interval (date_diff( + ${lightdash.parameters.dbt_orders.custom_range_end}, + ${lightdash.parameters.dbt_orders.custom_range_start}, + day + ) + 1) day + ) + then 'previous period' + + --previous year + when date(${order_date_day}) between date_sub(${lightdash.parameters.dbt_orders.custom_range_start}, interval 1 year) + and date_sub(${lightdash.parameters.dbt_orders.custom_range_end}, interval 1 year) + then 'previous year' + + else 'out of range' + end +``` + + +``` yaml +columns: + - name: order_date + description: 'Date of order placement by user.' + config: + meta: + dimension: + type: date + additional_dimensions: + order_date_custom_period: + description: Date period bucket based on custom Start date and End date parameters + type: string + sql: | + case + --invalid date range + when ${lightdash.parameters.dbt_orders.custom_range_start} is null + or ${lightdash.parameters.dbt_orders.custom_range_end} is null + or ${lightdash.parameters.dbt_orders.custom_range_start} > ${lightdash.parameters.dbt_orders.custom_range_end} + then 'invalid date range' + + --current period + when ${order_date_day} >= ${lightdash.parameters.dbt_orders.custom_range_start} + and ${order_date_day} <= ${lightdash.parameters.dbt_orders.custom_range_end} + then 'current period' + + --previous period + when ${order_date_day} between date_sub( + ${lightdash.parameters.dbt_orders.custom_range_start}, + interval (date_diff( + ${lightdash.parameters.dbt_orders.custom_range_end}, + ${lightdash.parameters.dbt_orders.custom_range_start}, + day + ) + 1) day + ) and date_sub( + ${lightdash.parameters.dbt_orders.custom_range_end}, + interval (date_diff( + ${lightdash.parameters.dbt_orders.custom_range_end}, + ${lightdash.parameters.dbt_orders.custom_range_start}, + day + ) + 1) day + ) + then 'previous period' + + --previous year + when date(${order_date_day}) between date_sub(${lightdash.parameters.dbt_orders.custom_range_start}, interval 1 year) + and date_sub(${lightdash.parameters.dbt_orders.custom_range_end}, interval 1 year) + then 'previous year' + + else 'out of range' + end ``` + + The code examples above will give you the following parameter options in the Lightdash UI that will output the custom period labels shown in the chart: