From 9eb9d313101a4c699ad78e6f6ebc68849193fd59 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 31 May 2024 16:36:53 +0100 Subject: [PATCH 1/6] Update 5-semantic-layer-marts.md adding semantic models configuration guidance and naming guidance per slack thread: https://dbt-labs.slack.com/archives/C03KHQRQUBX/p1716313470074679 --- .../how-we-structure/5-semantic-layer-marts.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md index 62e07a72e36..06e3ac4bb93 100644 --- a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md +++ b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md @@ -36,6 +36,17 @@ models └── stg_supplies.yml ``` +## Semantic Layer: Where and why? + +- πŸ“‚ Directory structure: Add your semantic models in `models/semantic_models` with directories corresponding to the models/marts files. This organization makes it easier to search and find what you can join. It also supports better maintenance and reduces repeated code. + +## Naming conventions + +- 🏷️ Semantic model names: Use the `sem_` prefix for semantic model names, such as `sem_cloud_user_account_activity`. This follows the same pattern as other naming conventions like `fct_` for fact tables and `dim_` for dimension tables. +- 🧩 Entity names: Do not use prefixes for entity names within the semantic model. This keeps the names clear and focused on their specific purpose without unnecessary prefixes. + +This guidance helps you make sure your dbt project is organized, maintainable, and scalable, allowing you to take full advantage of the capabilities offered by the dbt Semantic Layer. + ## When to make a mart - ❓ If we can go directly to staging models and it's better to serve normalized models to the Semantic Layer, then when, where, and why would we make a mart? From 8126d7b4734485c4516cfc406725dfbe11713b3c Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 31 May 2024 16:37:17 +0100 Subject: [PATCH 2/6] Update website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md --- .../best-practices/how-we-structure/5-semantic-layer-marts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md index 06e3ac4bb93..ab0896ad83e 100644 --- a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md +++ b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md @@ -40,7 +40,7 @@ models - πŸ“‚ Directory structure: Add your semantic models in `models/semantic_models` with directories corresponding to the models/marts files. This organization makes it easier to search and find what you can join. It also supports better maintenance and reduces repeated code. -## Naming conventions +## Naming convention - 🏷️ Semantic model names: Use the `sem_` prefix for semantic model names, such as `sem_cloud_user_account_activity`. This follows the same pattern as other naming conventions like `fct_` for fact tables and `dim_` for dimension tables. - 🧩 Entity names: Do not use prefixes for entity names within the semantic model. This keeps the names clear and focused on their specific purpose without unnecessary prefixes. From 746ae6931d2079adb8a8d2213c1ade09bf23e8e7 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 3 Jun 2024 10:41:41 +0100 Subject: [PATCH 3/6] add codde example for best practice --- .../5-semantic-layer-marts.md | 29 +++++++++++++++++-- website/docs/guides/sl-snowflake-qs.md | 8 ++--- 2 files changed, 30 insertions(+), 7 deletions(-) diff --git a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md index ab0896ad83e..0bb030a4416 100644 --- a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md +++ b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md @@ -38,12 +38,35 @@ models ## Semantic Layer: Where and why? -- πŸ“‚ Directory structure: Add your semantic models in `models/semantic_models` with directories corresponding to the models/marts files. This organization makes it easier to search and find what you can join. It also supports better maintenance and reduces repeated code. +- πŸ“‚ **Directory structure**: Add your semantic models in the `models/semantic_models` with directories corresponding to the models/marts files. This type of organization makes it easier to search and find what you can join. It also supports better maintenance and reduces repeated code. + + + + ```yaml + semantic_models: + - name: orders + defaults: + agg_time_dimension: order_date + description: | + Order fact table. This table’s grain is one row per order. + model: ref('fct_orders') + entities: + - name: order_id + type: primary + - name: customer_id + type: foreign + dimensions: + - name: order_date + type: time + type_params: + time_granularity: day + ``` + ## Naming convention -- 🏷️ Semantic model names: Use the `sem_` prefix for semantic model names, such as `sem_cloud_user_account_activity`. This follows the same pattern as other naming conventions like `fct_` for fact tables and `dim_` for dimension tables. -- 🧩 Entity names: Do not use prefixes for entity names within the semantic model. This keeps the names clear and focused on their specific purpose without unnecessary prefixes. +- 🏷️ **Semantic model names**: Use the `sem_` prefix for semantic model names, such as `sem_cloud_user_account_activity`. This follows the same pattern as other naming conventions like `fct_` for fact tables and `dim_` for dimension tables. +- 🧩 **Entity names**: Entity names don't use prefixes within the semantic model. This keeps the names clear and focused on their specific purpose without unnecessary prefixes. This guidance helps you make sure your dbt project is organized, maintainable, and scalable, allowing you to take full advantage of the capabilities offered by the dbt Semantic Layer. diff --git a/website/docs/guides/sl-snowflake-qs.md b/website/docs/guides/sl-snowflake-qs.md index 2fb63f0296d..746ce906910 100644 --- a/website/docs/guides/sl-snowflake-qs.md +++ b/website/docs/guides/sl-snowflake-qs.md @@ -698,10 +698,10 @@ semantic_models: type: foreign # Newly added dimensions: - - name: order_date - type: time - type_params: - time_granularity: day + - name: order_date + type: time + type_params: + time_granularity: day ``` From bf97d06e3421f5daa7f65208f543b5e04d817072 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 3 Jun 2024 10:47:40 +0100 Subject: [PATCH 4/6] add links to guide. --- .../how-we-structure/5-semantic-layer-marts.md | 2 +- website/docs/docs/build/semantic-models.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md index 0bb030a4416..9acf22766bd 100644 --- a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md +++ b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md @@ -3,7 +3,7 @@ title: "Marts for the Semantic Layer" id: "5-semantic-layer-marts" --- -The Semantic Layer alters some fundamental principles of how you organize your project. Using dbt without the Semantic Layer necessitates creating the most useful combinations of your building block components into wide, denormalized marts. On the other hand, the Semantic Layer leverages MetricFlow to denormalize every possible combination of components we've encoded dynamically. As such we're better served to bring more normalized models through from the logical layer into the Semantic Layer to maximize flexibility. This section will assume familiarity with the best practices laid out in the [How we build our metrics](/best-practices/how-we-build-our-metrics/semantic-layer-1-intro) guide, so check that out first for a more hands-on introduction to the Semantic Layer. +The [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) alters some fundamental principles of how you organize your project. Using dbt without the Semantic Layer necessitates creating the most useful combinations of your building block components into wide, denormalized marts. On the other hand, the Semantic Layer leverages MetricFlow to denormalize every possible combination of components we've encoded dynamically. As such we're better served to bring more normalized models through from the logical layer into the Semantic Layer to maximize flexibility. This section will assume familiarity with the best practices laid out in the [How we build our metrics](/best-practices/how-we-build-our-metrics/semantic-layer-1-intro) guide, so check that out first for a more hands-on introduction to the Semantic Layer. ## Semantic Layer: Files and folders diff --git a/website/docs/docs/build/semantic-models.md b/website/docs/docs/build/semantic-models.md index 627d95c1636..1cb21a3144e 100644 --- a/website/docs/docs/build/semantic-models.md +++ b/website/docs/docs/build/semantic-models.md @@ -15,7 +15,7 @@ Semantic models are the foundation for data definition in MetricFlow, which powe - MetricFlow uses YAML configuration files to create this graph for querying metrics. - Each semantic model corresponds to a dbt model in your DAG, requiring a unique YAML configuration for each semantic model. - You can create multiple semantic models from a single dbt model (SQL or Python), as long as you give each semantic model a unique name. -- Configure semantic models in a YAML file within your dbt project directory. +- Configure semantic models in a YAML file within your dbt project directory. Refer to the [best practices guide](/best-practices/how-we-structure/5-semantic-layer-marts) for more info on project structuring. - Organize them under a `metrics:` folder or within project sources as needed. @@ -60,6 +60,8 @@ semantic_models: if the semantic model has no primary entity, then this property is required. #Optional if a primary entity exists, otherwise Required ``` +You can refer to the [best practices guide](/best-practices/how-we-structure/5-semantic-layer-marts) for more info on project structuring. + The following example displays a complete configuration and detailed descriptions of each field: ```yaml @@ -252,8 +254,6 @@ import MeasuresParameters from '/snippets/_sl-measures-parameters.md'; - - import SetUpPages from '/snippets/_metrics-dependencies.md'; @@ -264,3 +264,4 @@ import SetUpPages from '/snippets/_metrics-dependencies.md'; - [Dimensions](/docs/build/dimensions) - [Entities](/docs/build/entities) - [Measures](/docs/build/measures) +- [Project structure best practices guide](/best-practices/how-we-structure/5-semantic-layer-marts) From 2e89485cd639e18d4cd317807126a5b68746d812 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 6 Jun 2024 16:15:40 +0100 Subject: [PATCH 5/6] Update website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md Co-authored-by: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> --- .../best-practices/how-we-structure/5-semantic-layer-marts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md index 9acf22766bd..eae708b83e0 100644 --- a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md +++ b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md @@ -38,7 +38,7 @@ models ## Semantic Layer: Where and why? -- πŸ“‚ **Directory structure**: Add your semantic models in the `models/semantic_models` with directories corresponding to the models/marts files. This type of organization makes it easier to search and find what you can join. It also supports better maintenance and reduces repeated code. +- πŸ“‚ **Directory structure**: Add your semantic models to `models/semantic_models` with directories corresponding to the models/marts files. This type of organization makes it easier to search and find what you can join. It also supports better maintenance and reduces repeated code. From 7823c6f511e5935e2c4c9433f2e1e01a19417507 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 6 Jun 2024 16:17:01 +0100 Subject: [PATCH 6/6] Update website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md Co-authored-by: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> --- .../best-practices/how-we-structure/5-semantic-layer-marts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md index eae708b83e0..7694c9a94af 100644 --- a/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md +++ b/website/docs/best-practices/how-we-structure/5-semantic-layer-marts.md @@ -66,7 +66,7 @@ models ## Naming convention - 🏷️ **Semantic model names**: Use the `sem_` prefix for semantic model names, such as `sem_cloud_user_account_activity`. This follows the same pattern as other naming conventions like `fct_` for fact tables and `dim_` for dimension tables. -- 🧩 **Entity names**: Entity names don't use prefixes within the semantic model. This keeps the names clear and focused on their specific purpose without unnecessary prefixes. +- 🧩 **Entity names**: Don't use prefixes in Entity within the semantic model. This keeps the names clear and focused on their specific purpose without unnecessary prefixes. This guidance helps you make sure your dbt project is organized, maintainable, and scalable, allowing you to take full advantage of the capabilities offered by the dbt Semantic Layer.