From 19e1ba5aabd005a5da903a0c2ddcd92ed27030f2 Mon Sep 17 00:00:00 2001 From: Logan Luque <98849774+LLuque-twilio@users.noreply.github.com> Date: Fri, 2 May 2025 12:09:45 -0700 Subject: [PATCH 1/7] Add description field to entities/relationships --- src/unify/data-graph/index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/unify/data-graph/index.md b/src/unify/data-graph/index.md index 4860be27e1..297fce56e3 100644 --- a/src/unify/data-graph/index.md +++ b/src/unify/data-graph/index.md @@ -174,6 +174,7 @@ The first step in creating a Data Graph is to define your entities. An entity co | Parameters | Definition | | ----------- | --------------------------------------------------------------------- | | `entity` | An immutable slug for the entity, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (e.g `account-entity` or `account_entity`). | +| (Optional) `description` | An optional descriptor used to add additional context to the entity | | `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time. | | `table_ref` | Defines the fully qualified table reference: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views. | | `primary_key` | The unique identifier for the given table. Must be a column with unique values per row. | @@ -185,6 +186,7 @@ The first step in creating a Data Graph is to define your entities. An entity co data_graph { entity "account-entity" { name = "account" + description = "An entity representing user accounts" table_ref = "PRODUCTION.CUST.ACCOUNT" primary_key = "ID" } @@ -241,6 +243,7 @@ This is the first level of relationships and a unique type of relationship betwe | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | | `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time | +| (Optional) `description` | An optional descriptor used to add additional context to the relationship | | `related_entity` | References your already defined entity | To define a profile-to-entity relationship, reference your entity table and depending on your table columns, choose to join on one of the following: @@ -277,6 +280,7 @@ data_graph { # Relate accounts table to the profile relationship "user-accounts" { name = "Premium Accounts" + description = "A relationship linking segment profiles to user accounts" related_entity = "account-entity" # Option 1: Join the profile entity with an identifier (like email) on the related entity table @@ -302,6 +306,7 @@ For 1:many relationships, define the join on between the two entity tables using | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | | `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | +| (Optional) `description` | An optional descriptor used to add additional context to the relationship | | `related_entity` | References your already defined entity | | `join_on` | Defines relationship between the two entity tables `[lefty entity slug].[column name] = [right entity slug].[column name]`. Note that since you’re referencing the entity slug for the join on, you do not need to define the full table reference | @@ -328,6 +333,7 @@ data_graph { # Define 1:many relationship between accounts and carts relationship "user-carts" { name = "Shopping Carts" + description = "A relationship linking user accounts to carts" related_entity = "carts-entity" join_on = "account-entity.ID = cart-entity.ACCOUNT_ID" } @@ -347,6 +353,7 @@ For many:many relationships, define the join on between the two entity tables wi | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | | `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | +| (Optional) `description` | An optional descriptor used to add additional context to the relationship | | `related_entity` | References your already defined entity | **Junction table spec** @@ -390,6 +397,7 @@ data_graph { # Define many:many relationship between carts and products relationship "products" { name = "Purchased Products" + description = "A relationship linking user carts to products via the CART_PRODUCT junction table" related_entity = "product-entity" junction_table { table_ref = "PRODUCTION.CUSTOMER.CART_PRODUCT" From e43dd9407755bfc5be48329f14d407731acf091a Mon Sep 17 00:00:00 2001 From: Logan Luque <98849774+LLuque-twilio@users.noreply.github.com> Date: Fri, 2 May 2025 12:12:16 -0700 Subject: [PATCH 2/7] [netlify-build] From b4edef95fe6ec2b3495449c1d86ea71701d6d826 Mon Sep 17 00:00:00 2001 From: Logan Luque <98849774+LLuque-twilio@users.noreply.github.com> Date: Fri, 2 May 2025 12:45:09 -0700 Subject: [PATCH 3/7] uppercase Segment --- src/unify/data-graph/index.md | 200 ++++++++++++++++++---------------- 1 file changed, 108 insertions(+), 92 deletions(-) diff --git a/src/unify/data-graph/index.md b/src/unify/data-graph/index.md index 297fce56e3..173d85f71b 100644 --- a/src/unify/data-graph/index.md +++ b/src/unify/data-graph/index.md @@ -2,8 +2,8 @@ title: Data Graph plan: unify redirect_from: - - '/unify/linked-profiles/data-graph' - - '/unify/data-graph/data-graph' + - "/unify/linked-profiles/data-graph" + - "/unify/data-graph/data-graph" --- The Data Graph acts as a semantic layer that allows businesses to define relationships between various entity datasets in the warehouse — such as accounts, subscriptions, households, and products — with the Segment Profile. It makes these relational datasets easily accessible to business teams for targeted and personalized customer engagements. @@ -17,23 +17,25 @@ To use the Data Graph, you'll need the following: - A supported data warehouse with the appropriate Data Graph permissions - Workspace Owner or Unify Read-only/Admin and Entities Admin permissions -- For Linked Audiences, set up [Profiles Sync](/docs/unify/profiles-sync/) in a Unify space with ready-to-use [data models and tables](/docs/unify/profiles-sync/tables/) in your warehouse. When setting up selective sync, Segment recommends the following settings: +- For Linked Audiences, set up [Profiles Sync](/docs/unify/profiles-sync/) in a Unify space with ready-to-use [data models and tables](/docs/unify/profiles-sync/tables/) in your warehouse. When setting up selective sync, Segment recommends the following settings: - Under **Profile materialized tables**, select all the tables (`user_identifier`, `user_traits`, `profile_merges`) for faster and more cost-efficient Linked Audiences computations in your data warehouse. - **Make sure to include the unmaterialized tables as well**. Segment needs them during setup to understand your schema. - Under **Track event tables**, select **Sync all Track Call Tables** to enable filtering on event history for Linked Audiences conditions. > info "" -> To define entity relationships, you need to enable Linked Audiences. Contact your Customer Success Manager to get access to Linked Audiences. +> To define entity relationships, you need to enable Linked Audiences. Contact your Customer Success Manager to get access to Linked Audiences. ## Step 1: Set up Data Graph permissions in your data warehouse + > warning "" > Data Graph, Reverse ETL, and Profiles Sync require different warehouse permissions. -To get started with the Data Graph, set up the required permissions in your warehouse. Segment supports the following: +To get started with the Data Graph, set up the required permissions in your warehouse. Segment supports the following: + - Linked Audiences: [BigQuery](/docs/unify/data-graph/setup-guides/BigQuery-setup/), [Databricks](/docs/unify/data-graph/setup-guides/databricks-setup/), [Redshift](/docs/unify/data-graph/setup-guides/redshift-setup/), and [Snowflake](/docs/unify/data-graph/setup-guides/snowflake-setup/) -- Linked Events: [BigQuery](/docs/unify/data-graph/setup-guides/BigQuery-setup/), [Databricks](/docs/unify/data-graph/setup-guides/databricks-setup/), [Redshift](/docs/unify/data-graph/setup-guides/redshift-setup/), and [Snowflake](/docs/unify/data-graph/setup-guides/snowflake-setup/) +- Linked Events: [BigQuery](/docs/unify/data-graph/setup-guides/BigQuery-setup/), [Databricks](/docs/unify/data-graph/setup-guides/databricks-setup/), [Redshift](/docs/unify/data-graph/setup-guides/redshift-setup/), and [Snowflake](/docs/unify/data-graph/setup-guides/snowflake-setup/) -To track the data sent to Segment on previous syncs, Segment uses [Reverse ETL](/docs/connections/reverse-etl/) infrastructure to store diffs in tables within a dedicated schema called `_segment_reverse_etl` in your data warehouse. You can choose which database or project in your warehouse this data lives in. +To track the data sent to Segment on previous syncs, Segment uses [Reverse ETL](/docs/connections/reverse-etl/) infrastructure to store diffs in tables within a dedicated schema called `_segment_reverse_etl` in your data warehouse. You can choose which database or project in your warehouse this data lives in. ## Step 2: Connect your warehouse to the Data Graph @@ -42,7 +44,7 @@ To connect your warehouse to the Data Graph: 1. Navigate to **Unify > Data Graph**. This should be a Unify space with Profiles Sync already set up. 2. Click **Add warehouse**. 3. Select your warehouse type. -4. Enter your warehouse credentials. +4. Enter your warehouse credentials. 5. Test your connection, then click **Save**. ## Step 3: Build your Data Graph @@ -61,34 +63,35 @@ The Data Graph is a semantic layer that represents a subset of relevant business **Defining Relationships** -Similar to the concept of [cardinality in data modeling](https://w.wiki/Ay$u){:target="_blank"}, the Data Graph supports 3 types of relationships: +Similar to the concept of [cardinality in data modeling](https://w.wiki/Ay$u){:target="\_blank"}, the Data Graph supports 3 types of relationships: + - **Profile-to-entity relationship:** This is a relationship between your entity table and the Segment Profiles tables, and is the first level of relationship. - **1:many relationship:** For example, an `account` can have many `carts`, but each `cart` can only be associated with one `account`. - **many:many relationship:** For example, a user can have many `carts`, and each `cart` can have many `products`. However, these `products` can also belong to many `carts`. - The Data Graph currently supports 6 levels of depth (or nodes) starting from the profile. For example, relating the `profile` to the `accounts` table to the `carts` table is 3 levels of depth. There are no limits on the width of your Data Graph or the number of entities. - Relationships are nested under the profile. Refer to the example below. -**Data Graph Example** +**Data Graph Example** An example of a Data Graph ```python data_graph { version = "v1.0.0" - + # Define entities entity "account-entity" { name = "account" table_ref = "PRODUCTION.CUST.ACCOUNT" primary_key = "ID" } - + entity "product-entity" { name = "product" table_ref = "PRODUCTION.PROD.PRODUCT_SKUS" primary_key = "SKU" } - + entity "cart-entity" { name = "cart" table_ref = "PRODUCTION.CUST.CART" @@ -107,13 +110,13 @@ data_graph { table_ref = "PRODUCTION.CUST.SUBSCRIPTION" primary_key = "SUB_ID" } - + # Define the profile entity, which corresponds to Segment Profiles tables synced with Profiles Sync # Use materialized views in Profiles Sync to reduce query costs and speed things up profile { profile_folder = "PRODUCTION.SEGMENT" type = "segment:materialized" - + # First branch - relate accounts table to the profile # This is a unique type of relationship between an entity and the profile block relationship "user-accounts" { @@ -125,17 +128,17 @@ data_graph { type = "email" join_key = "EMAIL_ID" } - + # Define 1:many relationship between accounts and carts # for example, an account can be associated with many carts relationship "user-carts" { name = "Shopping Carts" related_entity = "cart-entity" join_on = "account-entity.ID = cart-entity.ACCOUNT_ID" - + # Define many:many relationship between carts and products # for example, there can be multiple carts, and each cart can be associated with multiple products - relationship "products" { + relationship "products" { name = "Purchased Products" related_entity = "product-entity" junction_table { @@ -143,7 +146,7 @@ data_graph { table_ref = "PRODUCTION.CUSTOMER.CART_PRODUCT" left_join_on = "cart-entity.ID = CART_ID" right_join_on = "PRODUCT_ID = product-entity.SKU" - } + } } } } @@ -156,7 +159,7 @@ data_graph { type = "email" join_key = "EMAIL_ID" } - + # Define 1:many relationship between households and subscriptions # for example, a household can be associated with multiple subscriptions relationship "user-subscriptions" { @@ -169,16 +172,17 @@ data_graph { ``` ### 3a: Define entities + The first step in creating a Data Graph is to define your entities. An entity corresponds to a table in the warehouse. -| Parameters | Definition | -| ----------- | --------------------------------------------------------------------- | -| `entity` | An immutable slug for the entity, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (e.g `account-entity` or `account_entity`). | -| (Optional) `description` | An optional descriptor used to add additional context to the entity | -| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time. | -| `table_ref` | Defines the fully qualified table reference: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views. | -| `primary_key` | The unique identifier for the given table. Must be a column with unique values per row. | -| (If applicable) `enrichment_enabled = true` | Add this if you plan to reference the entity table for [Linked Events](/docs/unify/data-graph/linked-events/) use cases. | +| Parameters | Definition | +| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `entity` | An immutable slug for the entity, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (e.g `account-entity` or `account_entity`). | +| (Optional) `description` | An optional descriptor used to add additional context to the entity | +| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time. | +| `table_ref` | Defines the fully qualified table reference: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views. | +| `primary_key` | The unique identifier for the given table. Must be a column with unique values per row. | +| (If applicable) `enrichment_enabled = true` | Add this if you plan to reference the entity table for [Linked Events](/docs/unify/data-graph/linked-events/) use cases. | **Example:** @@ -190,7 +194,7 @@ data_graph { table_ref = "PRODUCTION.CUST.ACCOUNT" primary_key = "ID" } - + entity "cart-entity" { name = "cart" table_ref = "PRODUCTION.CUST.CART" @@ -201,15 +205,16 @@ data_graph { ``` ### 3b: Define the profile + > info "" > Segments recommends that you select materialized views under the Profiles [Selective Sync settings](/docs/unify/profiles-sync/profiles-sync-setup/#step-3-set-up-selective-sync) to optimize warehouse compute costs. -Next, define the profile. This is a special class of entity that represents Segment Profiles, which corresponds to the Profiles Sync tables and models. For Linked Audiences, this allows marketers to filter on profile traits, event history, etc. There can only be one profile for a Data Graph. +Next, define the profile. This is a special class of entity that represents Segment Profiles, which corresponds to the Profiles Sync tables and models. For Linked Audiences, this allows marketers to filter on profile traits, event history, etc. There can only be one profile for a Data Graph. -| Parameters | Definition | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `profile_folder` | Define the fully qualified path of the folder or schema location for the profile tables. | -| `type` | Use `segment:materialized` to sync materialized views with Profiles Sync. Segment recommends this configuration for all Linked Audiences and Data Graph setups. If you can't sync materialized views, [reach out to Segment support](https://segment.com/help/contact/){:target="_blank"} for help. | +| Parameters | Definition | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `profile_folder` | Define the fully qualified path of the folder or schema location for the profile tables. | +| `type` | Use `segment:materialized` to sync materialized views with Profiles Sync. Segment recommends this configuration for all Linked Audiences and Data Graph setups. If you can't sync materialized views, [reach out to Segment support](https://segment.com/help/contact/){:target="\_blank"} for help. | **Example:** @@ -218,7 +223,7 @@ Next, define the profile. This is a special class of entity that represents Segm data_graph { # Define entities ... - + # Define the profile entity, which corresponds to Segment Profiles tables synced via Profiles Sync # Recommend setting up Profiles Sync materialized views to optimize warehouse compute costs profile { @@ -231,24 +236,27 @@ data_graph { ### 3c: Define relationships -Now define your relationships between your entities. Similar to the concept of [cardinality in data modeling](en.wikipedia.org/wiki/Cardinality_(data_modeling)), the Data Graph supports 3 types of relationships below. All relationship types require you to define the relationship slug, name, and related entity. Each type of relationship has unique join on conditions. +Now define your relationships between your entities. Similar to the concept of [cardinality in data modeling](), the Data Graph supports 3 types of relationships below. All relationship types require you to define the relationship slug, name, and related entity. Each type of relationship has unique join on conditions. + - **[Profile-to-entity relationship](#define-profile-to-entity-relationship):** This is a relationship between your entity table and the Segment Profiles tables, and is the first level of relationship. - **[1:many relationship](#define-a-1many-relationship):** For example, an `account` can have many `carts`, but each `cart` can only be associated with one `account`. - **[many:many relationship](#define-manymany-relationship):** For example, a user can have many `carts`, and each `cart` can have many `products`. However, these `products` can also belong to many `carts`. #### Define profile-to-entity relationship -This is the first level of relationships and a unique type of relationship between the Segment profile entity and a related entity. -| Parameters | Definition | -| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | -| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time | -| (Optional) `description` | An optional descriptor used to add additional context to the relationship | -| `related_entity` | References your already defined entity | +This is the first level of relationships and a unique type of relationship between the Segment profile entity and a related entity. -To define a profile-to-entity relationship, reference your entity table and depending on your table columns, choose to join on one of the following: +| Parameters | Definition | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | +| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time | +| (Optional) `description` | An optional descriptor used to add additional context to the relationship | +| `related_entity` | References your already defined entity | + +To define a profile-to-entity relationship, reference your entity table and depending on your table columns, choose to join on one of the following: + +**Option 1 (Most common) - Join on an external ID:** Use the `external_id` block to join the profile entity with an entity table using external IDs from your [Unify ID resolution](/docs/unify/identity-resolution/externalids/) settings. Typically these identifiers are `user_id`, `email`, or `phone` depending on the structure of your entity table. -**Option 1 (Most common) - Join on an external ID:** Use the `external_id` block to join the profile entity with an entity table using external IDs from your [Unify ID resolution](/docs/unify/identity-resolution/externalids/) settings. Typically these identifiers are `user_id`, `email`, or `phone` depending on the structure of your entity table. - `type`: Represents the [external ID type](/docs/unify/identity-resolution/externalids/#default-externalids) (`email`, `phone`, `user_id`) in your ID resolution settings. - This maps to the `type` column in the `user_identifiers` table when using materialized views. - `join_key`: The column on the entity table that matches the external ID. @@ -256,39 +264,41 @@ To define a profile-to-entity relationship, reference your entity table and depe > note "" > Segment recommends using materialized views with Profiles Sync. However, Segment may still reference unmaterialized tables during setup for schema detection. -**Option 2 - Join on a profile trait:** Use the `trait` block to join the profile entity with an entity table using [Profile Traits](/docs/unify/#enrich-profiles-with-traits). -- `name`: Represents a trait name in your Unify profiles. - - This maps to the `name` column in the `user_traits` table when using materialized views. +**Option 2 - Join on a profile trait:** Use the `trait` block to join the profile entity with an entity table using [Profile Traits](/docs/unify/#enrich-profiles-with-traits). + +- `name`: Represents a trait name in your Unify profiles. + - This maps to the `name` column in the `user_traits` table when using materialized views. - `join_key`: The column on the entity table that you're matching to the trait. **Example:** + ```python -data_graph { +data_graph { entity "account-entity" { name = "account" table_ref = "PRODUCTION.CUST.ACCOUNT" primary_key = "ID" } - + # Define additional entities... # Note: Relationships are nested profile { profile_folder = "PRODUCTION.SEGMENT" type = "segment:materialized" - - # Relate accounts table to the profile + + # Relate accounts table to the profile relationship "user-accounts" { name = "Premium Accounts" - description = "A relationship linking segment profiles to user accounts" + description = "A relationship linking Segment profiles to user accounts" related_entity = "account-entity" - + # Option 1: Join the profile entity with an identifier (like email) on the related entity table external_id { type = "email" join_key = "EMAIL_ID" } - + # Option 2: Join the profile entity with a profile trait on the related entity table trait { name = "cust_id" @@ -300,36 +310,37 @@ data_graph { ``` #### Define a 1:many relationship + For 1:many relationships, define the join on between the two entity tables using the spec below. -| Parameters | Definition | -| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | -| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | -| (Optional) `description` | An optional descriptor used to add additional context to the relationship | -| `related_entity` | References your already defined entity | -| `join_on` | Defines relationship between the two entity tables `[lefty entity slug].[column name] = [right entity slug].[column name]`. Note that since you’re referencing the entity slug for the join on, you do not need to define the full table reference | +| Parameters | Definition | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | +| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | +| (Optional) `description` | An optional descriptor used to add additional context to the relationship | +| `related_entity` | References your already defined entity | +| `join_on` | Defines relationship between the two entity tables `[lefty entity slug].[column name] = [right entity slug].[column name]`. Note that since you’re referencing the entity slug for the join on, you do not need to define the full table reference | **Example:** ```python -data_graph { +data_graph { entity "cart-entity" { name = "cart" table_ref = "PRODUCTION.CUST.CART" primary_key = "ID" } - + # Define additional entities... # Note: Relationships are nested profile { profile_folder = "PRODUCTION.SEGMENT" type = "segment:materialized" - + relationship "user-accounts" { ... - + # Define 1:many relationship between accounts and carts relationship "user-carts" { name = "Shopping Carts" @@ -343,57 +354,55 @@ data_graph { ``` #### Define many:many relationship + For many:many relationships, define the join on between the two entity tables with the `junction_table`. > warning "" > Attributes from a junction table are not referenceable via the Linked Audience builder. If a marketer would like to filter upon a column on the junction table, you must define the junction as an entity and define a relationship. - -| Parameters | Definition | -| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | -| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | -| (Optional) `description` | An optional descriptor used to add additional context to the relationship | -| `related_entity` | References your already defined entity | +| Parameters | Definition | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | +| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | +| (Optional) `description` | An optional descriptor used to add additional context to the relationship | +| `related_entity` | References your already defined entity | **Junction table spec** -| Parameters |Definition | -| --------------- | --------------------------------- | -| `table_ref` | Defines the fully qualified table reference to the join table: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views | +| Parameters | Definition | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `table_ref` | Defines the fully qualified table reference to the join table: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views | | `primary_key` | The unique identifier for the given table. Must be a column with unique values per row | | `left_join_on` | Define the relationship between the left entity table and the junction table: `[left entity slug].[column name] = [junction table column name]`. Note that schema and table are implied within the junction table column name, so you do not need to define it again | | `right_join_on` | Define the relationship between the junction table and the right entity table: `[junction table column name] = [right entity slug].[column name]`. Note that schema and table are implied within the junction table column name, so you do not need to define it again | - When you define a many-to-many relationship using a junction table, `left_join_on` and `right_join_on` tell Data Graph how to connect each entity to the junction table: -* Use `left_join_on` to specify which column in the junction table links to the parent (left) entity. +- Use `left_join_on` to specify which column in the junction table links to the parent (left) entity. -* Use `right_join_on` to specify which column links to the child (right) entity. +- Use `right_join_on` to specify which column links to the child (right) entity. These fields define the join conditions, but they don’t control how the join is executed. Data Graph always performs inner joins, even if you specify a `left_join_on`. If you need behavior similar to a left join (like including unmatched rows), create a view in your warehouse with the logic you’re targeting and reference that view as an entity in your graph. - **Example:** ```python -data_graph { +data_graph { # Define entities # Note: Relationships are nested profile { # Define profile - + relationship "user-accounts" { ... - + relationship "user-carts" { ... - + # Define many:many relationship between carts and products relationship "products" { name = "Purchased Products" @@ -410,9 +419,11 @@ data_graph { } } } - + ``` + ## Step 4: Validate your Data Graph + You can validate your Data Graph using the preview, then click Save. After you've set up your Data Graph, your partner teams can start leveraging these datasets with with [Linked Events](/docs/unify/data-graph/linked-events/) and [Linked Audiences](/docs/engage/audiences/linked-audiences/). ## Edit and manage your Data Graph @@ -425,28 +436,33 @@ To edit your Data Graph: ### View Data Graph data consumers A data consumer refers to a Segment feature like Linked Events and Linked Audiences that are referencing datasets, such as entities and/or relationships, from the Data Graph. You can view a list of data consumers in two places: + - Under **Unify > Data Graph**, click the **Data consumers** tab - Under **Unify > Data Graph > Overview** or the **Data Graph editor > Preview**, click into a node on the Data Graph preview and a side sheet will pop up with the list of data consumers for the respective relationship ### Understand changes that may cause breaking and potential breaking changes Upon editing and saving changes to your Data Graph, a modal will pop up to warn of breaking and/or potential breaking changes to your data consumers. You must acknowledge and click **Confirm and save** in order to proceed. + - **Definite breaking change**: Occurs when deleting an entity or relationship that is being referenced by a data consumer. Data consumers affected by breaking changes will fail on the next run. Note: The entity and relationship slug are immutable and treated as a delete if you make changes. You can modify the label. - **Potential breaking change**: Some changes such as updating the entity `table_ref` or `primary_key`, may lead to errors with data consumers. If there’s a breaking change, the data consumer will fail on the next run. Unaffected data consumers will continue to work. ### Detect warehouse breaking changes -Segment has a service that regularly scans and monitors the Data Graph for changes that occur in your warehouse that may break components of the Data Graph, like when the table being referenced by the Data Graph gets deleted from your warehouse or when the primary key column no longer exists. An alert banner will be displayed on the Data Graph landing page. The banner will be removed once the issues are resolved in your warehouse and/or the Data Graph. You will also have the option to trigger a manual sync of your warehouse schema. +Segment has a service that regularly scans and monitors the Data Graph for changes that occur in your warehouse that may break components of the Data Graph, like when the table being referenced by the Data Graph gets deleted from your warehouse or when the primary key column no longer exists. An alert banner will be displayed on the Data Graph landing page. The banner will be removed once the issues are resolved in your warehouse and/or the Data Graph. You will also have the option to trigger a manual sync of your warehouse schema. ### Receive alerts for warehouse breaking changes Configure alerts for breaking changes to receive notifications over Slack, email, or in-app notification whenever Segment detects a breaking change in your warehouse. -To configure alerts for breaking changes: -1. Open your workspace and navigate to **Settings > User Preferences > Activity Notifications**. +To configure alerts for breaking changes: + +1. Open your workspace and navigate to **Settings > User Preferences > Activity Notifications**. 2. Select **Data Graph**. -3. Select one of the following notification methods: - - **Email**: Select this to receive notifications at either the email address associated with your account or another email address that you enter into this field. - - **Slack**: Select this and enter a Slack webhook URL and channel name to send alerts to a channel in your Slack workspace. - - **In-app**: Select this to receive notifications in the Segment app. To view your notifications, select the bell next to your user icon in the Segment app. +3. Select one of the following notification methods: + +- **Email**: Select this to receive notifications at either the email address associated with your account or another email address that you enter into this field. +- **Slack**: Select this and enter a Slack webhook URL and channel name to send alerts to a channel in your Slack workspace. +- **In-app**: Select this to receive notifications in the Segment app. To view your notifications, select the bell next to your user icon in the Segment app. + 4. Click **Save**. From 2cbe76a6a390f54c4b9723632ff25e27bb551dbc Mon Sep 17 00:00:00 2001 From: Logan Luque <98849774+LLuque-twilio@users.noreply.github.com> Date: Mon, 5 May 2025 10:29:25 -0700 Subject: [PATCH 4/7] PR suggestions --- src/unify/data-graph/index.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/unify/data-graph/index.md b/src/unify/data-graph/index.md index 173d85f71b..dba6d71ae9 100644 --- a/src/unify/data-graph/index.md +++ b/src/unify/data-graph/index.md @@ -2,8 +2,8 @@ title: Data Graph plan: unify redirect_from: - - "/unify/linked-profiles/data-graph" - - "/unify/data-graph/data-graph" + - '/unify/linked-profiles/data-graph' + - '/unify/data-graph/data-graph' --- The Data Graph acts as a semantic layer that allows businesses to define relationships between various entity datasets in the warehouse — such as accounts, subscriptions, households, and products — with the Segment Profile. It makes these relational datasets easily accessible to business teams for targeted and personalized customer engagements. @@ -178,7 +178,7 @@ The first step in creating a Data Graph is to define your entities. An entity co | Parameters | Definition | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entity` | An immutable slug for the entity, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (e.g `account-entity` or `account_entity`). | -| (Optional) `description` | An optional descriptor used to add additional context to the entity | +| `description` (*Optional*) | An optional descriptor used to add additional context to the entity. | | `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time. | | `table_ref` | Defines the fully qualified table reference: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views. | | `primary_key` | The unique identifier for the given table. Must be a column with unique values per row. | @@ -246,12 +246,12 @@ Now define your relationships between your entities. Similar to the concept of [ This is the first level of relationships and a unique type of relationship between the Segment profile entity and a related entity. -| Parameters | Definition | -| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | -| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time | -| (Optional) `description` | An optional descriptor used to add additional context to the relationship | -| `related_entity` | References your already defined entity | +| Parameters | Definition | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | +| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time | +| `description` (*Optional*) | An optional descriptor used to add additional context to the relationship. | +| `related_entity` | References your already defined entity | To define a profile-to-entity relationship, reference your entity table and depending on your table columns, choose to join on one of the following: @@ -313,13 +313,13 @@ data_graph { For 1:many relationships, define the join on between the two entity tables using the spec below. -| Parameters | Definition | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | -| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | -| (Optional) `description` | An optional descriptor used to add additional context to the relationship | -| `related_entity` | References your already defined entity | -| `join_on` | Defines relationship between the two entity tables `[lefty entity slug].[column name] = [right entity slug].[column name]`. Note that since you’re referencing the entity slug for the join on, you do not need to define the full table reference | +| Parameters | Definition | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | +| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | +| `description` (*Optional*) | An optional descriptor used to add additional context to the relationship. | +| `related_entity` | References your already defined entity | +| `join_on` | Defines relationship between the two entity tables `[lefty entity slug].[column name] = [right entity slug].[column name]`. Note that since you’re referencing the entity slug for the join on, you do not need to define the full table reference | **Example:** From 77a86c56de7ba80cca1f8a74860e68511da3987e Mon Sep 17 00:00:00 2001 From: Logan Luque <98849774+LLuque-twilio@users.noreply.github.com> Date: Mon, 5 May 2025 10:52:17 -0700 Subject: [PATCH 5/7] Update entity description --- src/unify/data-graph/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/unify/data-graph/index.md b/src/unify/data-graph/index.md index dba6d71ae9..c5e77f018a 100644 --- a/src/unify/data-graph/index.md +++ b/src/unify/data-graph/index.md @@ -178,7 +178,7 @@ The first step in creating a Data Graph is to define your entities. An entity co | Parameters | Definition | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entity` | An immutable slug for the entity, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (e.g `account-entity` or `account_entity`). | -| `description` (*Optional*) | An optional descriptor used to add additional context to the entity. | +| `description` (*Optional*) | An optional descriptor used to add additional context to the entity (E.g. table grain, cadence at which the table/view is refreshed, etc). | | `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time. | | `table_ref` | Defines the fully qualified table reference: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views. | | `primary_key` | The unique identifier for the given table. Must be a column with unique values per row. | From f9517c7c8cd020298873d53beb12e67580797a09 Mon Sep 17 00:00:00 2001 From: stayseesong <83784848+stayseesong@users.noreply.github.com> Date: Wed, 7 May 2025 13:02:39 -0700 Subject: [PATCH 6/7] Apply suggestions from code review --- src/unify/data-graph/index.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/unify/data-graph/index.md b/src/unify/data-graph/index.md index c5e77f018a..21e83c2a7c 100644 --- a/src/unify/data-graph/index.md +++ b/src/unify/data-graph/index.md @@ -177,9 +177,9 @@ The first step in creating a Data Graph is to define your entities. An entity co | Parameters | Definition | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `entity` | An immutable slug for the entity, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (e.g `account-entity` or `account_entity`). | -| `description` (*Optional*) | An optional descriptor used to add additional context to the entity (E.g. table grain, cadence at which the table/view is refreshed, etc). | -| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time. | +| `entity` | An immutable slug for the entity, and will be 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`). | +| `description` (*Optional*) | An optional descriptor used to add additional context to the entity (for example, table grain, cadence at which the table/view is refreshed). | +| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences. This name can be modified at any time. | | `table_ref` | Defines the fully qualified table reference: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views. | | `primary_key` | The unique identifier for the given table. Must be a column with unique values per row. | | (If applicable) `enrichment_enabled = true` | Add this if you plan to reference the entity table for [Linked Events](/docs/unify/data-graph/linked-events/) use cases. | @@ -248,10 +248,10 @@ This is the first level of relationships and a unique type of relationship betwe | Parameters | Definition | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | -| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time | +| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`). | +| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences. This name can be modified at any time. | | `description` (*Optional*) | An optional descriptor used to add additional context to the relationship. | -| `related_entity` | References your already defined entity | +| `related_entity` | This references the already defined entity. | To define a profile-to-entity relationship, reference your entity table and depending on your table columns, choose to join on one of the following: @@ -315,11 +315,11 @@ For 1:many relationships, define the join on between the two entity tables using | Parameters | Definition | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | +| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`). | | `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | | `description` (*Optional*) | An optional descriptor used to add additional context to the relationship. | | `related_entity` | References your already defined entity | -| `join_on` | Defines relationship between the two entity tables `[lefty entity slug].[column name] = [right entity slug].[column name]`. Note that since you’re referencing the entity slug for the join on, you do not need to define the full table reference | +| `join_on` | Defines relationship between the two entity tables `[lefty entity slug].[column name] = [right entity slug].[column name]`. Note that since you’re referencing the entity slug for the join on, you do not need to define the full table reference. | **Example:** @@ -362,10 +362,10 @@ For many:many relationships, define the join on between the two entity tables wi | Parameters | Definition | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`) | -| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time | -| (Optional) `description` | An optional descriptor used to add additional context to the relationship | -| `related_entity` | References your already defined entity | +| `relationship` | An immutable slug for the relationship, and will be treated as a delete if you make changes. The slug must be in all lowercase, and supports dashes or underscores (like `user-account` or `user_account`). | +| `name` | A label displayed throughout your Segment space for Linked Events, Linked Audiences, and so on. This name can be modified at any time. | +| (Optional) `description` | An optional descriptor used to add additional context to the relationship. | +| `related_entity` | This references your defined entity. | **Junction table spec** From b944e80256325cbe53b18fa8707d1706edb61e6c Mon Sep 17 00:00:00 2001 From: stayseesong <83784848+stayseesong@users.noreply.github.com> Date: Wed, 7 May 2025 13:07:03 -0700 Subject: [PATCH 7/7] Update src/unify/data-graph/index.md --- src/unify/data-graph/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/unify/data-graph/index.md b/src/unify/data-graph/index.md index 21e83c2a7c..2b2b25d906 100644 --- a/src/unify/data-graph/index.md +++ b/src/unify/data-graph/index.md @@ -371,10 +371,10 @@ For many:many relationships, define the join on between the two entity tables wi | Parameters | Definition | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `table_ref` | Defines the fully qualified table reference to the join table: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views | -| `primary_key` | The unique identifier for the given table. Must be a column with unique values per row | -| `left_join_on` | Define the relationship between the left entity table and the junction table: `[left entity slug].[column name] = [junction table column name]`. Note that schema and table are implied within the junction table column name, so you do not need to define it again | -| `right_join_on` | Define the relationship between the junction table and the right entity table: `[junction table column name] = [right entity slug].[column name]`. Note that schema and table are implied within the junction table column name, so you do not need to define it again | +| `table_ref` | Defines the fully qualified table reference to the join table: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views and materialized views. | +| `primary_key` | The unique identifier for the given table. Must be a column with unique values per row. | +| `left_join_on` | Defines the relationship between the left entity table and the junction table: `[left entity slug].[column name] = [junction table column name]`. Note that schema and table are implied within the junction table column name, so you do not need to define it again. | +| `right_join_on` | Define the relationship between the junction table and the right entity table: `[junction table column name] = [right entity slug].[column name]`. Note that schema and table are implied within the junction table column name, so you do not need to define it again. | When you define a many-to-many relationship using a junction table, `left_join_on` and `right_join_on` tell Data Graph how to connect each entity to the junction table: