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..cbb24e9e 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" + ... + ``` + + *** @@ -108,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. 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..e5967de5 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. @@ -68,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` @@ -98,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. diff --git a/guides/adding-tables-to-lightdash.mdx b/guides/adding-tables-to-lightdash.mdx index 35714b0b..9e96ae8d 100644 --- a/guides/adding-tables-to-lightdash.mdx +++ b/guides/adding-tables-to-lightdash.mdx @@ -176,12 +176,23 @@ 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 + tags: ['prod'] + ``` + + + ```yaml + models: + - name: model_name + config: + tags: ['prod'] + ``` + + Or, to your model's SQL file in the config block: diff --git a/guides/explores.mdx b/guides/explores.mdx index ab45e50a..86b92a8e 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: @@ -110,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 diff --git a/guides/formatting-your-fields.mdx b/guides/formatting-your-fields.mdx index 7c55a0e3..a2a4c742 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`. @@ -58,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'] + ``` + + @@ -111,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. @@ -132,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. @@ -156,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! @@ -172,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. @@ -204,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. @@ -249,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. @@ -267,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. @@ -300,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. @@ -316,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. @@ -360,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. @@ -406,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` @@ -442,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`. diff --git a/guides/period-over-period.mdx b/guides/period-over-period.mdx index 9d501ce0..6913e9e5 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). @@ -261,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 @@ -322,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). @@ -350,70 +441,152 @@ 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 +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 -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 + 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 ``` + + + + ``` 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: diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 7330e835..f8881985 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 @@ -26,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: @@ -88,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: @@ -173,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: @@ -224,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: @@ -252,30 +361,62 @@ 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 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 | | :-------- | :------------------- | :------------------------------------ | :------------- | @@ -329,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) @@ -345,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. @@ -421,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.' + + + ```yaml + models: + - name: baskets 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` -``` + 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: @@ -458,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 @@ -480,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. @@ -500,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. @@ -557,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. @@ -586,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) @@ -629,64 +922,139 @@ 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:** 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:** -```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:** -```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 @@ -764,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 @@ -819,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 @@ -850,57 +1285,119 @@ 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 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 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 diff --git a/references/metrics.mdx b/references/metrics.mdx index 5ba7f14d..cfb5fd14 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) @@ -35,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. @@ -90,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: @@ -169,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 @@ -187,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 @@ -204,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 @@ -223,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 @@ -243,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 @@ -260,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 @@ -279,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 @@ -301,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 @@ -320,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 @@ -337,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. @@ -364,28 +614,59 @@ 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). 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 @@ -398,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 @@ -414,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. @@ -438,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). @@ -461,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). @@ -699,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.' + + + ```yaml + models: + - name: baskets 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` -``` + 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 @@ -739,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. @@ -804,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` @@ -833,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 @@ -860,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.' - 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.' + + + ```yaml + models: + - name: orders 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