Skip to content

Commit 3e8aa91

Browse files
rchinn1rchinn1
committed
data-graph updates
1 parent eb253a1 commit 3e8aa91

File tree

1 file changed

+263
-0
lines changed

1 file changed

+263
-0
lines changed

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

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
---
2+
title: Data Graph
3+
hidden: true
4+
5+
---
6+
7+
With Linked Profiles, you can build a Data Graph that defines relationships between any data set in the warehouse and the Segment Profiles you send with Profiles Sync.
8+
9+
Use the Data Graph to define relationships between data sets and give marketers access to data to target, personalize, and analyze customer experiences.
10+
11+
> success ""
12+
> Segment's Data Graph powers [Linked Events](#) and [Linked Audiences](#).
13+
14+
## Prerequisites
15+
16+
To use the Data Graph, you'll need the following:
17+
- A Unify and Engage Foundations or Premier plan.
18+
- Workspace owner or Unify Read-only/Admin and Entities Admin permissions.
19+
- A Snowflake Data Warehouse.
20+
- [Profiles Sync](/docs/unify/profiles-sync/) set up with ready to use [data models and tables](/docs/unify/profiles-sync/tables/) in your warehouse.
21+
- A Braze, Customer.io, or Iterable Destination. <!-- are we supporting all destination actions here? -->
22+
23+
24+
> info ""
25+
> Linked Profiles follows Zero Copy principles. This means that Segment doesn't copy entities to store in Segment. Segment stores and processes all data in the U.S.
26+
27+
> warning ""
28+
> Don't send any personal health information (PHI) with the Data Graph.
29+
30+
31+
## Connect your warehouse to the Data Graph
32+
33+
> success ""
34+
> Before getting started with the Data Graph, be sure to [set up your Snowflake permissions](/unify/linked-profiles/setup-guides/snowflake-setup/).
35+
36+
To connect your warehouse to the data graph:
37+
38+
1. In your Segment workspace, navigate to **Unify**, and select **Data Graph**.
39+
- This should be the Unify space with Profiles Sync already set up.
40+
2. Click **Connect warehouse**.
41+
3. Select your warehouse type.
42+
4. Enter your warehouse credentials. Then, test your connection and click **Save**.
43+
44+
Depending on the size of your warehouse, it may take anywhere from a few minutes to an hour for Segment to sync your warehouse metadata to cache before you're able to set up your Data Graph.
45+
46+
## Build your Data Graph
47+
48+
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.
49+
50+
Use the configuration language spec below to add models to build your Data Graph.
51+
52+
### Delete and edit entities and/or relationships from your Data Graph
53+
54+
> info ""
55+
> Each Unify space has one Data Graph. The current version is v0.0.6.
56+
57+
Segment recommends creating a new Linked Audience or Linked Event. Deleting and/or editing entities in the Data Graph may lead to errors if you reference these entities or relationships in existing Linked Audiences and Linked Events.
58+
59+
While you can delete relationships or entities from the Data Graph, these relationships and entities will still display in the Linked Audience builder and Linked Events.
60+
61+
### Define entities
62+
63+
Use the parameters, defintions, and examples below to help you define entities.
64+
65+
#### Profile
66+
67+
The profile is a special class of entity. The profile 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. The parameters are:
68+
69+
- `profile_folder`: This is the folder or schema location for the profile tables.
70+
- `materialization`: Identify the type of materialization (`dbt`,`segment`,`none`).
71+
72+
```python
73+
#define a profile entity
74+
75+
profile {
76+
profile_folder = "segment"
77+
materialization = "none"
78+
# for the pilot, use "none" for materialization
79+
}
80+
```
81+
82+
#### Entity
83+
84+
An entity is a stateful representation of a business object. The entity corresponds to a table in the warehouse that represents that entity. The parameters are:
85+
86+
- `entity`: This should be a unique name for the entity.
87+
- `table_ref`: Define the table reference.
88+
- `primary_key`: This is the unique identifier for the given table and should be a column with unique values per row.
89+
- (Optional) `enrichment_enabled` = true: Indicate if you plan to also reference the entity table for Linked Events.
90+
91+
92+
```python
93+
# Define an entity and optionally indicate if the entity will be referenced for Linked Events (event enrichment)
94+
95+
entity "account" {
96+
table_ref = "cust.account"
97+
primary_key = "id"
98+
enrichment_enabled = true
99+
}
100+
```
101+
102+
### Relate entities
103+
104+
Use the following relationship, parameters, and examples to help you relate entities.
105+
106+
> warning ""
107+
> Snowflake schemas are case sensitive, so you'll need to reflect the uppercase schema, table, and column names based on how you have it in Snowflake.
108+
109+
#### Relate Entity to Profile
110+
111+
- `relationship`: A unique name to be referenced by the Audience builder.
112+
- `related_entity`: Reference your already defined entity.
113+
- `external_id`: Define the external ID that will be used to join the profile with your entity.
114+
- `type`: Identify the external ID type (`email`, `phone`, `user id`).
115+
- This corresponds to the `external_id_type` column in your `external_id_mapping` table.
116+
- `join_key`: This is the column on the entity table that you are matching to the external identifier.
117+
118+
```python
119+
data_graph {
120+
#define entities
121+
122+
profile {
123+
#define profile
124+
125+
#relate profile to account
126+
relationship "Accounts" {
127+
related_entity = "account"
128+
external_id {
129+
type = "email"
130+
join_key = "email_id"
131+
}
132+
}
133+
}
134+
}
135+
```
136+
137+
#### Relate between entities
138+
139+
- `relationship`: A unique name that will be referenced in the Audience builder.
140+
- `related_entity`: Your already defined entity.
141+
- `join_on`: Define relationships between two entity tables `[lefty entity name].[column name] = [right entity name].[column name]`.
142+
- 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.
143+
144+
```py
145+
data_graph {
146+
#define entities
147+
profile {
148+
#define profile
149+
...
150+
#relate account to carts
151+
relationship "Carts" {
152+
related_entity = "cart"
153+
join_on = "account.id = cart.account_id"
154+
}
155+
}
156+
}
157+
}
158+
159+
```
160+
161+
If you're relating entities with a junction table:
162+
- `Junction_table`: Define relationships between two entities tables joined by a junction table.
163+
- `table_ref`: Define the table reference to the join table.
164+
- `primary_key`: The unique identifier on the join table and should be a column with unique values per row.
165+
- `left_join_on`: Define relationship between the two entity tables `[left entity name].[column name] = [junction table column name]`.
166+
- `right_join_on`: Define relationship between the two entity tables `[junction table column name] = [right entity name].[column name]`.
167+
- Note that schema.table is implied within the junction table column name and doesn't need to be provided.
168+
- Attributes from a junction table are not referenceable with the Audience Builder. If you'd like to reference an additional column on the junction table for filtering, you must first define it as an entity and explicitly define a relationship name.
169+
170+
```py
171+
#relating entities with junction table
172+
173+
data_graph {
174+
#define entities
175+
profile {
176+
#define profile
177+
...
178+
#relate products to carts
179+
relationship "Products" {
180+
related_entity = "product"
181+
junction_table {
182+
primary_key = "id"
183+
table_ref = "customer.cart_product"
184+
left_join_on = "cart.id = cart_id"
185+
#schema.table is implied within the cart_id key
186+
right_join_on = "product_id = product.sku"
187+
}
188+
189+
}
190+
}
191+
}
192+
}
193+
194+
```
195+
196+
![An example of a data graph](images/data-graph-example.png)
197+
198+
```py
199+
data_graph {
200+
version = "v0.0.6"
201+
202+
#define a profile entity
203+
profile {
204+
profile_folder = "segment"
205+
materialization = "none"
206+
207+
#relate profile to accounts
208+
relationship "Accounts" {
209+
related_entity = "account"
210+
external_id {
211+
type = "email"
212+
join_key = "email_id"
213+
}
214+
215+
#relate account to carts
216+
relationship "Carts" {
217+
related_entity = "cart"
218+
join_on = "account.id = cart.account_id"
219+
220+
#relate products to carts
221+
relationship "Products" {
222+
related_entity = "product"
223+
junction_table {
224+
primary_key = "id"
225+
table_ref = "customer.cart_product"
226+
left_join_on = "cart.id = cart_id"
227+
#schema.table is implied within the cart_id key
228+
right_join_on = "product_id = product.sku"
229+
}
230+
}
231+
}
232+
}
233+
}
234+
235+
#define account, product, and cart entities
236+
entity "account" {
237+
table_ref = "cust.account"
238+
primary_key = "id"
239+
enrichment_enabled = true
240+
}
241+
242+
entity "product" {
243+
table_ref = "prod.product_skus"
244+
primary_key = "sku"
245+
enrichment_enabled = true
246+
}
247+
248+
entity "cart" {
249+
table_ref = "cust.cart"
250+
primary_key = "id"
251+
}
252+
}
253+
254+
```
255+
256+
## Validate your Data Graph
257+
258+
Validate your Data Graph using the config builder and preview, then click **Save**.
259+
260+
## Next steps
261+
262+
After you've set up your Data Graph, get started with [Linked Audiences](/docs/unify/linked-profiles/linked-audiences/) and [Linked Events](/docs/unify/linked-profiles/linked-events/).
263+

0 commit comments

Comments
 (0)