Update data-graph.md

cmastr · web-flow · commit b60c14930f3f · 2024-07-31T08:28:07.000-05:00
diff --git a/src/unify/data-graph/data-graph.md b/src/unify/data-graph/data-graph.md
@@ -62,76 +62,94 @@ This should be a Unify space with Profiles Sync already set up.
 
 ## Step 3: Build your Data Graph
 
-The Data Graph is a semantic layer that represents a subset of relevant business data that you'll use for audience targeting and personalization in downstream tools. Use the configuration language spec below to add models to build your Data Graph. The Data Graph currently supports 4 layers of depth, including the Profile entity. Warehouse schemas are case sensitive, so you'll need to reflect the schema, table, and column names based on how you case them in the warehouse.
+The Data Graph is a semantic layer that represents a subset of relevant business data that you'll use for audience targeting and personalization in downstream tools. Use the configuration language spec below to add models to build your Data Graph. The Data Graph currently supports 6 layers of depth, including the Profile entity. Warehouse schemas are case sensitive, so you'll need to reflect the schema, table, and column names based on how you case them in the warehouse.
 
 To leverage the Data Graph auto-complete feature, begin typing or use the following keyboard shortcuts to autocomplete the profile_folder and table_ref properties.
 
-- Mac: CtrlSpace
-- Windows: AltEsc
+- Mac: Ctrl + Space
+- Windows: Alt + Esc
 
 ### Define entities
 
 Use the parameters, definitions, and examples below to help you define entities.
 
-#### Profile 
-
-The profile is a special class of entity that is always defined at the top of the Data Graph, and there can only be one profile for a Data Graph. The profile entity corresponds to the Profiles Sync tables and models, such as profile traits. 
+#### Entity
 
-The parameters are:
+The first step in creating a Data Graph is to define your Entities. An entity is a stateful representation of a business object. The entity corresponds to a table in the warehouse. 
 
 | Parameters     | Definition                                                           |
 | ----------- | --------------------------------------------------------------------- |
-| `profile_folder`      | This is the fully qualified path of the folder or schema location for the profile tables.     |
-| `type`     | Identifies the materialization methods of the profile tables (`segment:unmaterialized`, `segment:materialized`, `segment:dbt`). **Note:** Leveraging materialized profile tables optimizes warehouse compute costs. |
+| `entity`      | A unique slug for the entity, which is immutable and treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (for example, `account-entity` or `account_entity`).    |
+| `name`        | A unique label that displays throughout your Segment space.                           |
+| `table_ref`   | Defines the table reference. In order to specify a connection to your table in Snowflake, a fully qualified table reference is required: `[database name].[schema name].[table name]`. |
+| `primary_key` | The unique identifier for the given table. Should be a column with unique values per row. |
+| (Optional) `enrichment_enabled = true`      | Indicates if you plan to also reference the entity table for [Linked Events](/docs/unify/data-graph/linked-events/).                         |
 
 Example:
 
 ```python
-# Define a profile entity
+# Define an entity and optionally indicate if the entity will be referenced for Linked Events (event enrichment)
 
-profile {
-     profile_folder = "PRODUCTION.segment"
-     type = segment:materialized
-    
+data_graph { 
+# Entities are nested under the data_graph
+entity "account-entity" {
+     name = "account"
+     table_ref = "PRODUCTION.CUST.ACCOUNT"
+     primary_key = "id"
+     enrichment_enabled = true
+}
+
+       entity "cart-entity" {
+            name = "cart"
+            table_ref = "PRODUCTION.CUST.CART"
+            primary_key = "id"
+       }
 }
 ```
 
-#### Entity
+#### Profile 
 
-An entity is a stateful representation of a business object. The entity corresponds to a table in the warehouse that represents the entity. 
+Next, we define a Profile block, a special class of Entity that represents Segment Profiles. There can only be one profile for a Data Graph. The profile entity corresponds to the Profiles Sync tables and models, such as profile traits. 
 
+The parameters are:
 
 | Parameters     | Definition                                                           |
 | ----------- | --------------------------------------------------------------------- |
-| `entity`      | A unique slug for the entity, which is immutable and treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (for example, `account-entity` or `account_entity`).    |
-| `name`        | A unique label that displays throughout your Segment space.                           |
-| `table_ref`   | Defines the table reference. In order to specify a connection to your table in Snowflake, a fully qualified table reference is required: `[database name].[schema name].[table name]`. |
-| `primary_key` | The unique identifier for the given table. Should be a column with unique values per row. |
-| (Optional) `enrichment_enabled = true`      | Indicates if you plan to also reference the entity table for [Linked Events](/docs/unify/data-graph/linked-events/).                         |
+| `profile_folder`      | This is the fully qualified path of the folder or schema location for the profile tables.     |
+| `type`     | Identifies the materialization methods of the profile tables (segment:unmaterialized, segment:materialized) as defined in your Profiles Sync configuration. E.g. utilize segment:materialized if you are synching Profiles Materialized Tables. Note: Leveraging materialized profile tables optimizes warehouse compute costs. |
 
 Example:
 
 ```python
-# Define an entity and optionally indicate if the entity will be referenced for Linked Events (event enrichment)
 
-data_graph { 
-# Entities are nested under the data_graph
+data_graph {
 entity "account-entity" {
      name = "account"
      table_ref = "PRODUCTION.CUST.ACCOUNT"
      primary_key = "id"
      enrichment_enabled = true
 }
 
+entity "cart-entity" {
+      name = "cart"
+      table_ref = "PRODUCTION.CUST.CART"
+      primary_key = "id"
+ }
+
+# Define a profile entity
 profile {
-# Relationships are nested under the profile
+     profile_folder = "PRODUCTION.segment"
+     type = segment:materialized
+    
 }
 }
+
+
 ```
 
 ### Relate entities
 
-Use the following relationship, parameters, and examples to help you relate entities.
+Next, relate Profiles to Entities to model relationships between your Profiles and business datasets. Use the following relationship, parameters, and examples to help you relate entities.
 
 #### Relate Entity to Profile
 
@@ -152,10 +170,24 @@ Example:
 
 ```python
 data_graph { 
-     #define entities
+ #define entities
+entity "account-entity" {
+     name = "account"
+     table_ref = "PRODUCTION.CUST.ACCOUNT"
+     primary_key = "id"
+     enrichment_enabled = true
+}
+
+  entity "cart-entity" {
+        name = "cart"
+        table_ref = "PRODUCTION.CUST.CART"
+        primary_key = "id"
+   }
 
+  #define profile
      profile {
-          #define profile
+         profile_folder = "PRODUCTION.segment"
+         type = segment:materialized
 
           #Option 1: Relate account to profile with an external ID
           relationship "user-accounts" {
@@ -166,6 +198,8 @@ data_graph {
                     join_key = "email_id"
                }
           }
+    }
+}
 ```
 **2. With a `trait`**: Define a profile trait that will be used to join the profile with your entity.
 - `name`: The trait name that corresponds to a column name in your `profile_traits_updates` table.
@@ -177,8 +211,11 @@ Example:
 data_graph { 
      #define entities
 
+   #define profile
      profile {
-          #define profile
+         
+         profile_folder = "PRODUCTION.segment"
+         type = segment:materialized
 
           #Option 2: relate account to profile with a trait`
           relationship: "user-accounts" {
@@ -194,29 +231,57 @@ data_graph {
 ```
 
 #### Relate between entities
+Finally, define relationships between Entities nested within the Profiles block.
 
 | Parameters     | Definition                                                           |
 | ----------- | --------------------------------------------------------------------- |
 | `relationship`      | A unique slug for the relationship, which is immutable and treated as a delete if you make changes. The slug must be in all lowercase and will support dashes or underscores (for example, `user-account` or `user_account`).   |
 | `name`        | A unique label that displays throughout your Segment space.                          |
 | `related_entity`   | References your already defined entity. |
-| `join_on`         |    Defines relationships between two entity tables `[lefty entity name].[column name] = [right entity name].[column name]`. Note that the entity name is a reference to the alias provided in the config and doesn't need to be the fully qualified table name. |
+| `join_on`         |    Defines relationships between two entity tables `[lefty entity slug].[column name] = [right entity slug].[column name]`. Note that the entity slug is a reference to the alias provided in the config and doesn't need to be the fully qualified table name. |
 
 Example:
 
 ```py
 data_graph { 
      #define entities
+
+ #define entities
+entity "account-entity" {
+     name = "account"
+     table_ref = "PRODUCTION.CUST.ACCOUNT"
+     primary_key = "id"
+     enrichment_enabled = true
+}
+
+     entity "cart-entity" {
+          name = "cart"
+          table_ref = "PRODUCTION.CUST.CART"
+          primary_key = "id"
+     }
+     
+ #define profile
      profile {
-          #define profile
-               ...
-               #relate account to carts
+         profile_folder = "PRODUCTION.segment"
+         type = segment:materialized
+               
+          relationship "user-accounts" {
+               name = "Premium Accounts"
+               related_entity = "account-entity"
+               external_id {
+                    type = "email"
+                    join_key = "email_id"
+               }
+
+               #relate account to Carts
                relationship "Carts" { 
                     name = "Shopping Carts"
-                    related_entity = "cart-entity"
-                    join_on = "account.id = cart.account_id"
+                    related_entity = "carts-entity"
+                    join_on = "account-entity.id = carts-entity.account_id"
                }
           }
+
+          }
      }         
 }
 
@@ -231,8 +296,8 @@ If you're relating entities with a junction table:
 | `junction_table`      | Defines the table reference to the join table. In order to specify a connection to your table in Snowflake, a fully qualified table reference is required: `[database name].[schema name].[table name]`.  |
 | `table_ref`      | Defines the table reference to the join table. In order to specify a connection to your table in Snowflake, a fully qualified table reference is required: `[database name].[schema name].[table name]`.  |
 | `primary_key`    | The unique identifier on the join table, and should be a column with unique values per row. |
-| `left_join_on`   | Defines the relationship between the two entity tables: `[left entity name].[column name] = [junction table column name]`. |
-| `right_join_on`  | Defines the relationship between the two entity tables: `[junction table column name] = [right entity name].[column name]`. |
+| `left_join_on`   | Defines the relationship between the two entity tables: `[left entity slug].[column name] = [junction table column name]`. |
+| `right_join_on`  | Defines the relationship between the two entity tables: `[junction table column name] = [right entity slug].[column name]`. |
 
 **Note:** `schema.table` is implied within the junction table column name and doesn't need to be provided.
 
@@ -356,3 +421,4 @@ Editing the Data Graph may lead to errors with data consumers. If there’s a br
 ## Next steps 
 
 After you've set up your Data Graph, get started with [Linked Events](/docs/unify/data-graph/linked-events/) and [Linked Audiences](/docs/engage/audiences/linked-audiences/).
+
