Skip to content

Commit 9567baf

Browse files
kly-segmentkly-segment
authored
Update data-graph.md
1 parent 762d60e commit 9567baf

File tree

1 file changed

+100
-113
lines changed

1 file changed

+100
-113
lines changed

‎src/unify/data-graph/data-graph.md

Lines changed: 100 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -53,33 +53,112 @@ The Data Graph is a semantic layer that represents a subset of relevant business
5353
- Begin typing to autopopulate the configuration spec within the editor, as well as to autocomplete your warehouse schema
5454
- Validate your Data Graph using the **Preview** tab
5555

56-
### Data Graph structure
57-
- Define your entities. Each entity corresponds to a table in your warehouse.
58-
- Define the profile. This maps to the Segment Profiles tables synced via Profiles Sync.
59-
- Define the relationship.
60-
- The Data Graph supports three relationship types: 1) profile:entity 2) 1:many, and 3) many:many.
61-
- It currently supports 6 layers of depth, including the profile. There are no limits on the breadth of your Data Graph.
62-
- Relationships are nested under the profile.
56+
### Key steps to build your Data Graph
57+
1. First, define your entities. An entity corresponds to a table in your warehouse. Segment flexibly supports tables, views and materialized views.
58+
2. Then, define the profile block. 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.
59+
3. Finally, define how your datasets are related to each other. The Data Graph preserves these relationships and carries this rich context to the destinations to unlock personalization.
6360

64-
**Example:**
65-
```python
61+
**Relationships**
62+
63+
Similar to the concept of [cardinality in data modeling](/en.wikipedia.org/wiki/Cardinality_(data_modeling)), the Data Graph supports 3 types of relationships:
64+
- **Profile-to-entity relationship:** This is a relationship between your entity table and the Segment Profiles tables.
65+
- **1:many relationship:** For example, an `account` can have many `carts`, and each `cart` can only be associated with one `account`.
66+
- **many:many relationship:** For example, a user can have many 'carts', and each cart can have many 'products'. These `products` can also belong to many `carts`.
67+
- The Data Graph currently supports 5 levels of relationships starting from the profile. For example, relating the accounts table to the profile block is one level of relationship, relating a 1:many relationship between the accounts and carts table is the second level of relationship, and so on. There are no limits on the breadth of your Data Graph.
68+
- Relationships are nested under the profile. Refer to the example below.
69+
70+
**Data Graph Example**
71+
72+
<img src="/docs/unify/images/data-graph-example.png" alt="An example of a Data Graph" width="5888"/>
6673

74+
```python
6775
data_graph {
68-
...
69-
profile {
70-
relationship "a"{
71-
...
72-
relationship "b" {
73-
...
74-
relationship "c"{
75-
...
76+
version = "v1.0.0"
77+
78+
# Define entities
79+
entity "account-entity" {
80+
name = "account"
81+
table_ref = "PRODUCTION.CUST.ACCOUNT"
82+
primary_key = "ID"
83+
}
84+
85+
entity "product-entity" {
86+
name = "product"
87+
table_ref = "PRODUCTION.PROD.PRODUCT_SKUS"
88+
primary_key = "SKU"
89+
}
90+
91+
entity "cart-entity" {
92+
name = "cart"
93+
table_ref = "PRODUCTION.CUST.CART"
94+
primary_key = "ID"
95+
enrichment_enabled = true
96+
}
97+
98+
entity "household-entity" {
99+
name = "household"
100+
table_ref = "PRODUCTION.CUST.HOUSEHOLD"
101+
primary_key = "HOUSEHOLD_ID"
102+
}
103+
104+
entity "subscription-entity" {
105+
name = "subscription"
106+
table_ref = "PRODUCTION.CUST.SUBSCRIPTION"
107+
primary_key = "SUB_ID"
108+
}
109+
110+
# Define the profile entity, which corresponds to Segment Profiles tables synced via Profiles Sync
111+
# Recommend setting up Profiles Sync materialized views to optimize warehouse compute costs
112+
profile {
113+
profile_folder = "PRODUCTION.SEGMENT"
114+
type = "segment: materialized"
115+
116+
# First branch - relate accounts table to the profile. Unique type of relationship between an entity and the profile block
117+
relationship "user-accounts" {
118+
name = "Premium Accounts"
119+
related_entity = "account-entity"
120+
# Join the profile entity with user_id, email, or phone as the identifier on the entity table
121+
# Option to replace with the traits block below to join with a profile trait on the entity table instead
122+
external_id {
123+
type = "email"
124+
join_key = "EMAIL_ID"
125+
}
126+
127+
# Define 1:many relationship between accounts and carts (e.g. an account can be associated with many carts)
128+
relationship "user-carts" {
129+
name = "Shopping Carts"
130+
related_entity = "cart-entity"
131+
join_on = "account-entity.ID = cart-entity.ACCOUNT_ID"
132+
133+
# Define many:many relationship between carts and products (e.g. there can be multiple carts, and each cart can be associated with multiple products)
134+
relationship "products" {
135+
name = "Purchased Products"
136+
related_entity = "product-entity"
137+
junction_table {
138+
primary_key = "ID"
139+
table_ref = "PRODUCTION.CUSTOMER.CART_PRODUCT"
140+
left_join_on = "cart-entity.ID = CART_ID"
141+
right_join_on = "PRODUCT_ID = product-entity.SKU"
142+
}
76143
}
77144
}
78145
}
79-
relationship "d" {
80-
...
81-
}
82-
}
146+
147+
# Second branch - relate households table to the profile by joining with an external ID block
148+
relationship "user-households" {
149+
name = "Households"
150+
related_entity = "household-entity"
151+
external_id {
152+
type = "email"
153+
join_key = "EMAIL_ID"
154+
}
155+
156+
# Define 1:many relationship between households and subscriptions (e.g. a household can be associated with multiple subscriptions)
157+
relationship "user-subscriptions" {
158+
name = "Subscriptions"
159+
related_entity = "subscription-entity"
160+
join_on = "household-entity.SUB_ID = subscription-entity.HOUSEHOLD_ID"
161+
}
83162
}
84163

85164
```
@@ -309,98 +388,6 @@ data_graph {
309388
## Step 4: Validate your Data Graph
310389
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/).
311390

312-
## Data Graph Example
313-
314-
<img src="/docs/unify/images/data-graph-example.png" alt="An example of a Data Graph" width="5888"/>
315-
316-
```python
317-
data_graph {
318-
version = "v1.0.0"
319-
320-
# Define entities
321-
entity "account-entity" {
322-
name = "account"
323-
table_ref = "PRODUCTION.CUST.ACCOUNT"
324-
primary_key = "ID"
325-
}
326-
327-
entity "product-entity" {
328-
name = "product"
329-
table_ref = "PRODUCTION.PROD.PRODUCT_SKUS"
330-
primary_key = "SKU"
331-
}
332-
333-
entity "cart-entity" {
334-
name = "cart"
335-
table_ref = "PRODUCTION.CUST.CART"
336-
primary_key = "ID"
337-
enrichment_enabled = true
338-
}
339-
340-
entity "household-entity" {
341-
name = "household"
342-
table_ref = "PRODUCTION.CUST.HOUSEHOLD"
343-
primary_key = "HOUSEHOLD_ID"
344-
}
345-
346-
entity "subscription-entity" {
347-
name = "subscription"
348-
table_ref = "PRODUCTION.CUST.SUBSCRIPTION"
349-
primary_key = "SUB_ID"
350-
}
351-
352-
# Define the profile entity
353-
profile {
354-
profile_folder = "PRODUCTION.SEGMENT"
355-
type = "segment: materialized"
356-
357-
# First branch - relate accounts table to the profile by joining with an external ID block
358-
relationship "user-accounts" {
359-
name = "Premium Accounts"
360-
related_entity = "account-entity"
361-
external_id {
362-
type = "email"
363-
join_key = "EMAIL_ID"
364-
}
365-
366-
# Define 1:many relationship between accounts and carts
367-
relationship "user-carts" {
368-
name = "Shopping Carts"
369-
related_entity = "cart-entity"
370-
join_on = "account-entity.ID = cart-entity.ACCOUNT_ID"
371-
372-
# Define many:many relationship between carts and products
373-
relationship "products" {
374-
name = "Purchased Products"
375-
related_entity = "product-entity"
376-
junction_table {
377-
primary_key = "ID"
378-
table_ref = "PRODUCTION.CUSTOMER.CART_PRODUCT"
379-
left_join_on = "cart-entity.ID = CART_ID"
380-
right_join_on = "PRODUCT_ID = product-entity.SKU"
381-
}
382-
}
383-
}
384-
}
385-
386-
# Second branch - relate households table to the profile by joining with an external ID block
387-
relationship "user-households" {
388-
name = "Households"
389-
related_entity = "household-entity"
390-
external_id {
391-
type = "email"
392-
join_key = "EMAIL_ID"
393-
}
394-
395-
# Define 1:many relationship between households and subscriptions
396-
relationship "user-subscriptions" {
397-
name = "Subscriptions"
398-
related_entity = "subscription-entity"
399-
join_on = "household-entity.SUB_ID = subscription-entity.HOUSEHOLD_ID"
400-
}
401-
}
402-
403-
```
404391
## Edit & manage your Data Graph
405392

406393
To edit your Data Graph:

0 commit comments

Comments
 (0)