Skip to content

Commit 40ce1be

Browse files
kly-segmentkly-segment
authored
Update data-graph.md
WIP - Data Graph updates.
1 parent 546f299 commit 40ce1be

File tree

1 file changed

+115
-123
lines changed

1 file changed

+115
-123
lines changed

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

Lines changed: 115 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,15 @@ redirect_from:
77
- '/unify/linked-profiles/data-graph'
88
---
99

10-
The Data Graph is a semantic layer unifying all of your customer datasets. With the Data Graph, you can define relationships between any entity data set in the warehouse and the Segment Profiles you send with Profiles Sync. The Data Graph enables businesses to map and understand the relationships between different datasets about their customers (accounts, subscriptions, households, products, etc.), and tie rich entity context back to the profile. The Data Graph allows you to make this relational data accessible to marketers and business stakeholders to empower them with all the data they need to create targeted and personalized customer engagements.
10+
The Data Graph is a semantic layer unifying all your customer datasets. With the Data Graph, you can define relationships between any entity data set in the warehouse and the Segment Profiles you send with Profiles Sync. The Data Graph enables businesses to map and understand the relationships between different datasets about their customers (accounts, subscriptions, households, products, etc.), and tie rich entity context back to the profile. Once the defined, the Data Graph allows you to make this relational data accessible to marketers and business stakeholders to empower them with all the data they need to create targeted and personalized customer engagements.
1111

1212
> info ""
1313
> Data Graph currently only supports workspaces in the United States.
1414
1515
The Data Graph powers:
1616

17-
- [Linked Audiences](/docs/engage/audiences/linked-audiences/): enables marketers to build targeting logic based on data points available in the data graph in a self-service way. Start by building a [Data Graph](/docs/unify/data-graph/data-graph/) that defines relationships between any data set in the warehouse and the Segment Profiles you send with Profiles Sync. From there, use Linked Audiences to unlock a world of new hyper-personalized campaigns.
18-
- [Linked Events](/docs/unify/data-graph/linked-events/): enables data teams to enrich event streams, in real time, with any data set coming from a data warehouse or data lake, and send those enriched events to any Destination. Start by building a [Data Graph](/docs/unify/data-graph/data-graph/) with the data models you want to use, and then use set up the enrichment in Destinations or Functions.
17+
- [Linked Audiences](/docs/engage/audiences/linked-audiences/): Enables marketers to build targeting logic based on data points available in the data graph in a self-service way. Start by building a [Data Graph](/docs/unify/data-graph/data-graph/) that defines relationships between any data set in the warehouse and the Segment Profiles you send with Profiles Sync. From there, use Linked Audiences to unlock a world of new hyper-personalized campaigns.
18+
- [Linked Events](/docs/unify/data-graph/linked-events/): Enables data teams to enrich event streams, in real time, with any data set coming from a data warehouse or data lake, and send those enriched events to any Destination. Start by building a [Data Graph](/docs/unify/data-graph/data-graph/) with the data models you want to use, and then use set up the enrichment in Destinations or Functions.
1919

2020
> warning ""
2121
> Don't send any personal health information with the Data Graph.
@@ -25,7 +25,7 @@ The Data Graph powers:
2525
To use the Data Graph, you'll need the following:
2626

2727
- A supported data warehouse.
28-
- If using Linked Audiences, [Profiles Sync](/docs/unify/profiles-sync/) will need to be set up with ready-to-use [data models and tables](/docs/unify/profiles-sync/tables/) in your warehouse. Profiles Sync is not required for Linked Events.
28+
- If using Linked Audiences, [Profiles Sync](/docs/unify/profiles-sync/) will need to be set up with ready-to-use [data models and tables](/docs/unify/profiles-sync/tables/) in your warehouse. Note: Profiles Sync is not required for Linked Events.
2929
- Workspace Owner or Unify Read-only/Admin and Entities Admin permissions.
3030

3131
## Step 1: Set up Data Graph permissions in your data warehouse
@@ -49,170 +49,163 @@ To connect your warehouse to the Data Graph:
4949

5050
## Step 3: Build your Data Graph
5151

52-
The Data Graph is a semantic layer that represents a subset of relevant business data that marketers and business stakeholders can use for audience targeting and personalization in downstream tools. Use the configuration language spec below to build your Data Graph. The Data Graph currently supports 6 layers of depth, including the Profile entity.
52+
The Data Graph is a semantic layer that represents a subset of relevant business data that marketers and business stakeholders can use for audience targeting and personalization in downstream tools. Use the configuration language spec below to build your Data Graph.
5353

54-
### Define entities
54+
### Data Graph structure
55+
- Define your entities. This corresponds to tables in your warehouse.
56+
- Define your profile. This maps to the Segment Profiles tables synced via Profiles Sync.
57+
- Define the relationship type.
58+
- The Data Graph currently supports 6 layers of depth, including the profile. There are no limits on the breadth of your Data Graph.
59+
- Relationships are nested under the profile.
5560

56-
Use the parameters, definitions, and examples below to help you define entities.
61+
Example:
62+
63+
```python
64+
65+
data_graph {
66+
...
67+
profile {
68+
relationship "A"{
69+
...
70+
relationship "B" {
71+
...
72+
relationship "C"{
73+
...
74+
}
75+
}
76+
}
77+
}
78+
}
79+
80+
```
5781

58-
#### Entity
82+
### a) Define entities
83+
> info ""
84+
> Leverage the "Warehouse access" tab to view the warehouse tables you've granted Segment access to for the Data Graph.
5985
60-
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.
86+
The first step in creating a Data Graph is to define your entities. An entity corresponds to a table in the warehouse.
6187

6288
| Parameters | Definition |
6389
| ----------- | --------------------------------------------------------------------- |
64-
| `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`). |
65-
| `name` | A unique label that displays throughout your Segment space. |
66-
| `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]`. |
67-
| `primary_key` | The unique identifier for the given table. Should be a column with unique values per row. |
68-
| (Optional) `enrichment_enabled = true` | Indicates if you plan to also reference the entity table for [Linked Events](/docs/unify/data-graph/linked-events/). |
90+
| `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`) |
91+
| `name` | A label that displays throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time |
92+
| `table_ref` | Defines the fully qualified table reference: `[database name].[schema name].[table name]`. Segment flexibly supports tables, views or materialized views |
93+
| `primary_key` | The unique identifier for the given table. Must be a column with unique values per row |
94+
| (Optional) `enrichment_enabled = true` | Add this if you plan to reference the entity table for [Linked Events](/docs/unify/data-graph/linked-events/) use cases |
6995

70-
Example:
96+
**Example:**
7197

7298
```python
73-
# Define an entity and optionally indicate if the entity will be referenced for Linked Events (event enrichment)
74-
75-
data_graph {
76-
# Entities are nested under the data_graph
99+
data_graph {
77100
entity "account-entity" {
78-
name = "account"
79-
table_ref = "PRODUCTION.CUST.ACCOUNT"
80-
primary_key = "id"
81-
enrichment_enabled = true
101+
name = "account"
102+
table_ref = "PRODUCTION.CUST.ACCOUNT"
103+
primary_key = "id"
82104
}
83105

84106
entity "cart-entity" {
85-
name = "cart"
86-
table_ref = "PRODUCTION.CUST.CART"
87-
primary_key = "id"
107+
name = "cart"
108+
table_ref = "PRODUCTION.CUST.CART"
109+
primary_key = "id"
110+
enrichment_enabled = true
88111
}
89112
}
90113
```
91114

92-
#### Profile
93-
94-
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.
115+
### b) Define the profile
116+
> info ""
117+
> Segments recommends that you select materialized views under the Profiles Sync Selective Sync settings to optimize warehouse compute costs.
95118
96-
The parameters are:
119+
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.
97120

98121
| Parameters | Definition |
99122
| ----------- | --------------------------------------------------------------------- |
100-
| `profile_folder` | This is the fully qualified path of the folder or schema location for the profile tables. |
101-
| `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. |
123+
| `profile_folder` | Define the fully qualified path of the folder or schema location for the profile tables |
124+
| `type` | Identify the materialization method of the profile tables defined in your Profiles Sync configuration (`segment:unmaterialized`, `segment:materialized`)|
102125

103-
Example:
126+
**Example:**
104127

105128
```python
106129

107130
data_graph {
131+
# Define your entities
108132
entity "account-entity" {
109-
name = "account"
110-
table_ref = "PRODUCTION.CUST.ACCOUNT"
111-
primary_key = "id"
112-
enrichment_enabled = true
133+
name = "account"
134+
table_ref = "PRODUCTION.CUST.ACCOUNT"
135+
primary_key = "id"
113136
}
114137

115-
entity "cart-entity" {
116-
name = "cart"
117-
table_ref = "PRODUCTION.CUST.CART"
118-
primary_key = "id"
119-
}
138+
...
120139

121-
# Define a profile entity
140+
# Define the profile entity
122141
profile {
123-
profile_folder = "PRODUCTION.segment"
124-
type = segment:materialized
125-
142+
profile_folder = "PRODUCTION.SEGMENT"
143+
type = "segment:materialized"
126144
}
127145
}
128146

129-
130147
```
131148

132-
### Relate entities
149+
### c) Define relationships
133150

134-
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.
151+
Now define your relationships across your entities. The Data Graph supports three types of relationships:
152+
- Define relationship between an entity and the profile. This is the first level of relationships
153+
- Define 1:many relationships
154+
- Define many:many relationships
135155

136-
#### Relate Entity to Profile
156+
All relationship types require you to define the `relationship`,`name`, and `related_entity`. Each type of relationship has specific `join_on` conditions.
157+
158+
#### Define relationship between an entity and the profile
159+
This is the first level of relationships and a unique type of relationship between an entity and the Segment profile entity.
137160

138161
| Parameters | Definition |
139162
| ----------- | --------------------------------------------------------------------- |
140-
| `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`). |
141-
| `name` | A unique label that displays throughout your Segment space. |
142-
| `related_entity` | References your already defined entity. |
143-
144-
145-
A profile can be related to an entity in two ways:
146-
147-
**1. With an `external_id`**: Define the external ID that will be used to join the profile with your entity.
148-
- `type`: Identify the external ID type (`email`, `phone`, `user id`). This corresponds to the `external_id_type` column in your `external_id_mapping` table.
149-
- `join_key`: This is the column on the entity table that you are matching to the external identifier.
150-
151-
Example:
152-
163+
| `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 (e.g. `user-account` or `user_account`) |
164+
| `name` | A label that displays throughout your Segment space for Linked Events, Linked Audiences, etc. This name can be modified at any time |
165+
| `related_entity` | References your already defined entity |
166+
167+
Reference your entity table and depending on your table columns, choose to join on one of the following:
168+
**Option 1:** Use the `external_id` block to join the profile entity with `user_id`, `email`, or `phone` as the identifier on the entity table
169+
- `type`: Identify the external ID type (`email`, `phone`, `user id`). This corresponds to the `external_id_type` column in your Profiles Sync `external_id_mapping` table
170+
- `join_key`: This is the column on the entity table that you are matching to the external identifier
171+
**Option 2:** Use the `traits` block to join with a profile trait on the entity table
172+
- `name`: The trait name that corresponds to a column name in your Profiles Sync `profile_traits_updates` table
173+
- `join_key`: This is the column on the entity table that you are matching to the trait
174+
175+
**Example:**
153176
```python
154177
data_graph {
155-
#define entities
156-
entity "account-entity" {
157-
name = "account"
158-
table_ref = "PRODUCTION.CUST.ACCOUNT"
159-
primary_key = "id"
160-
enrichment_enabled = true
161-
}
162-
163-
entity "cart-entity" {
164-
name = "cart"
165-
table_ref = "PRODUCTION.CUST.CART"
166-
primary_key = "id"
167-
}
168-
169-
#define profile
170-
profile {
171-
profile_folder = "PRODUCTION.segment"
172-
type = segment:materialized
178+
entity "account-entity" {
179+
name = "account"
180+
table_ref = "PRODUCTION.CUST.ACCOUNT"
181+
primary_key = "id"
182+
}
173183

174-
#Option 1: Relate account to profile with an external ID
175-
relationship "user-accounts" {
176-
name = "Premium Accounts"
177-
related_entity = "account-entity"
178-
external_id {
179-
type = "email"
180-
join_key = "email_id"
181-
}
182-
}
184+
profile {
185+
profile_folder = "PRODUCTION.SEGMENT"
186+
type = segment:materialized
187+
188+
relationship "user-accounts" {
189+
name = "Premium Accounts"
190+
related_entity = "account-entity"
191+
192+
# Option 1: Relate account to profile with an external ID
193+
external_id {
194+
type = "email"
195+
join_key = "email_id"
196+
}
197+
198+
# Option 2: Relate account to profile with a trait
199+
trait {
200+
name = "cust_id"
201+
join_key = "id"
202+
}
183203
}
184-
}
185-
```
186-
**2. With a `trait`**: Define a profile trait that will be used to join the profile with your entity.
187-
- `name`: The trait name that corresponds to a column name in your `profile_traits_updates` table.
188-
- `join_key`: This is the column on the entity table that you are matching to the trait.
189-
190-
Example:
191-
```python
192-
193-
data_graph {
194-
#define entities
195-
....
196-
197-
#define profile
198-
profile {
199-
profile_folder = "PRODUCTION.segment"
200-
type = segment:materialized
201-
202-
#Option 2: relate account to profile with a trait`
203-
relationship: "user-accounts" {
204-
name = "Premium Accounts"
205-
related_entity = "account-entity"
206-
trait {
207-
name = "cust_id"
208-
join_key = "id"
209-
}
210-
}
211-
}
204+
}
212205
}
213206
```
214207

215-
#### Relate between entities
208+
#### Define 1:many relationship
216209
Finally, define relationships between Entities nested within the Profiles block.
217210

218211
| Parameters | Definition |
@@ -231,13 +224,13 @@ data_graph {
231224
name = "account"
232225
table_ref = "PRODUCTION.CUST.ACCOUNT"
233226
primary_key = "id"
234-
enrichment_enabled = true
235227
}
236228

237229
entity "cart-entity" {
238230
name = "cart"
239231
table_ref = "PRODUCTION.CUST.CART"
240232
primary_key = "id"
233+
enrichment_enabled = true
241234
}
242235

243236
#define profile
@@ -267,7 +260,7 @@ data_graph {
267260

268261
```
269262

270-
#### Relating entities with a junction table
263+
#### Define many:many relationship
271264

272265
If you're relating entities with a junction table:
273266

@@ -364,20 +357,19 @@ data_graph {
364357
name = "account"
365358
table_ref = "PRODUCTION.CUST.ACCOUNT"
366359
primary_key = "id"
367-
enrichment_enabled = true
368360
}
369361

370362
entity "product-entity" {
371363
name = "product"
372364
table_ref = "PRODUCTION.PROD.PRODUCT_SKUS"
373365
primary_key = "sku"
374-
enrichment_enabled = true
375366
}
376367

377368
entity "cart-entity" {
378369
name = "cart"
379370
table_ref = "PRODUCTION.CUST.CART"
380371
primary_key = "id"
372+
enrichment_enabled = true
381373
}
382374
}
383375

0 commit comments

Comments
 (0)