Merge branch 'current' into jeremyyeo-patch-1

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
 
@@ -36,6 +36,40 @@ models
     └── stg_supplies.yml
 ```
 
+## Semantic Layer: Where and why?
+
+- 📂 **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.
+
+    <File name='models/marts/sem_orders.yml'>
+
+    ```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
+    ```
+    </File>
+
+## 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**: 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.
+
 ## 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?

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.
 
 <Lightbox src="/img/docs/dbt-cloud/semantic-layer/semantic_foundation.jpg" width="70%" title="A semantic model is made up of different components: Entities, Measures, and Dimensions."/>
@@ -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';
 
 <MeasuresParameters />
 
-
-
 import SetUpPages from '/snippets/_metrics-dependencies.md';
 
 <SetUpPages />
@@ -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)

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
 ```
 
 </File>