Skip to content

Commit 02db6ed

Browse files
pwsegpwseg
authored
Merge branch 'master' into event-streams
2 parents 480a45f + f1ae2cf commit 02db6ed

File tree

7 files changed

+455
-5
lines changed

7 files changed

+455
-5
lines changed

‎src/_data/sidenav/main.yml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,20 @@ sections:
322322
title: Sample Queries
323323
- path: /unify/profiles-sync/tables
324324
title: Tables & Materialized Views
325+
- section_title: Linked Profiles
326+
slug: unify/linked-profiles
327+
section:
328+
- section_title: Setup Guides
329+
slug: unify/linked-profiles/setup-guides
330+
section:
331+
- path: /unify/linked-profiles/setup-guides/bigquery-setup
332+
title: BigQuery Setup
333+
- path: /unify/linked-profiles/setup-guides/snowflake-setup
334+
title: Snowflake Setup
335+
- path: /unify/linked-profiles/setup-guides/redshift-setup
336+
title: Redshift Setup
337+
- path: /unify/linked-profiles/linked-events
338+
title: Linked Events
325339
- section_title: Traits
326340
slug: unify/traits
327341
section:

‎src/connections/destinations/actions.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -118,11 +118,13 @@ If necessary, click **New Mapping** to create a new, blank action.
118118
1. In the edit panel, define the [conditions](#conditions) under which the action should run.
119119
2. Test those conditions to make sure that they correctly match an expected event.
120120
This step looks for events that match the criteria in the [debugger queue](/docs/connections/sources/debugger/), so you might need to Trigger some events with the expected criteria to test your conditions. You can skip the test step if needed, and re-try it at any time.
121-
3. Next, set up the data mapping from the Segment format to the destination tool format.
122-
4. Test the mapping with data from a sample event.
121+
3. Select data models to [enrich your events](/docs/unify/linked-profiles/linked-events/) with.
122+
4. Set up the data mapping from the Segment format to the destination tool format.
123+
- You can click the Source field, then select the **Enrichments** tab to view and select Enrichments to use.
124+
5. Test the mapping with data from a sample event.
123125
The edit panel shows you the mapping output in the format for the destination tool. You can change your mapping as needed and re-test.
124-
5. When you're satisfied with the mapping, click **Save**. Segment returns you to the Mappings table.
125-
6. In the Mappings table **Status** column, verify that the **Enabled** toggle is on for the mapping you just customized.
126+
6. When you're satisfied with the mapping, click **Save**. Segment returns you to the Mappings table.
127+
7. In the Mappings table **Status** column, verify that the **Enabled** toggle is on for the mapping you just customized.
126128

127129

128130
> info ""
@@ -183,7 +185,7 @@ You can combine criteria in a single group using **ALL** or **ANY**. Use an ANY
183185
>
184186
> If your use case does not match these criteria, you might benefit from using Mapping-level Triggers to match only certain events.
185187
186-
## FAQ & Troubleshooting
188+
## FAQ and troubleshooting
187189

188190
### Validation error when using the Event Tester
189191

‎src/segment-app/iam/roles.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,11 @@ The following roles are only available to Segment Business Tier accounts.
6666
* Read-only access warehouse destination and warehouse destination settings. *(For example, Redshift, Postgres, BigQuery)*
6767
* **Scope:** Grants access to *all* warehouses.
6868

69+
#### Entities Admin
70+
Full CRUD (create, read, access, and delete) access to all Entities within a workspace. You can also grant or revoke user permissions.
71+
72+
#### Entities Read-only
73+
Read-only access to all Entities models and destinations in a workspace.
6974

7075
## PII Access
7176

‎src/unify/linked-profiles/linked-events.md

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
title: Linked Events
3+
beta: true
4+
plan: unify
5+
---
6+
7+
> info "Linked Events is in private beta"
8+
> Linked Events is in private beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions.
9+
10+
11+
Use Linked Events to enrich real-time event streams with entities from your data warehouse to your destinations. Insert additional event context for downstream applications for richer data about each event.
12+
13+
On this page, you'll learn how to get started with Linked Events.
14+
15+
## Use cases
16+
17+
With Linked Events, you can:
18+
19+
- **Add details to events for precise targeting**. Enable targeting by appending product events that only have `product_id` with full product SKU details from your warehouse.
20+
- **Sync enriched data**. Add a loyalty ID to event payloads before sending it downstream to destinations such as Amplitude, Mixpanel, and more.
21+
- **Reduce load times**. Enrich page view events with products and subscriptions connected to that view, and send that to Google Analytics 4 to lighten the front end and reduce page loading time.
22+
23+
## Requirements
24+
25+
Before getting started with Linked Events, you'll need:
26+
27+
1. [BigQuery](/docs/unify/linked-profiles/setup-guides/bigquery-setup/), [Snowflake](/docs/unify/linked-profiles/setup-guides/snowflake-setup/), or [Redshift](/docs/unify/linked-profiles/setup-guides/redshift-setup/) data warehouse credentials with **write** access.
28+
2. Access to Unify in your workspace.
29+
3. Access to the Destination you'll be using with Linked Events so that you can validate your data.
30+
31+
> info ""
32+
> Segment stores and processes all data in the United States.
33+
34+
### Linked Events roles
35+
36+
The following Segment access [roles](/docs/segment-app/iam/roles/) apply to Linked Events:
37+
38+
**Entities Admin Access**: Full CRUD (create, read, access, and delete) access to all Entities within a workspace. You can also grant or revoke user permissions.
39+
40+
**Entities Read-only Access**: Read-only access to all Entities models and destinations in a workspace.
41+
42+
For Linked Events, you need the following roles:
43+
- `Workspace Owner`
44+
- `Entities Admin`
45+
- `Source Admin`
46+
47+
To use Connections with Linked Events:
48+
- `Workspace Owner`
49+
- `Unify Read-only or Admin`
50+
- `Entities Admin`
51+
- `Source Admin`
52+
53+
## Step 1: Connect a data warehouse
54+
55+
> info ""
56+
> Linked Events uses Segment's [Reverse ETL](/docs/connections/reverse-etl/) infrastructure for pulling in data from your warehouse.
57+
58+
To get started, you'll need to connect a data warehouse. Linked Events supports [BigQuery](/docs/unify/linked-profiles/setup-guides/bigquery/), [Snowflake](/docs/unify/linked-profiles/setup-guides/snowflake/), and [Redshift](/docs/unify/linked-profiles/setup-guides/redshift-setup/).
59+
60+
1. Navigate to **Unify > Data graph** and click **Add warehouse**.
61+
2. Select a warehouse to connect from the [supported data warehouses](#supported-data-warehouses).
62+
3. [Connect your warehouse](#connect-your-warehouse).
63+
3. Click **Test Connection** to be sure your warehouse is connected.
64+
4. After a successful test, click **Save**.
65+
66+
### Schema
67+
68+
For Linked Events, the sync destination is an internal Segment data store. To track the data you send to Segment, you can view deltas/diffs in tables within a single schema Segment creates called `_segment_reverse_etl`.
69+
70+
You can choose which database within your warehouse this data lives in.
71+
72+
> info ""
73+
> Linked Events syncs data from your warehouse approximately once every hour.
74+
75+
### Supported data warehouses
76+
77+
The table below shows the data warehouses Linked Events supports. View the Segment docs for your warehouse, then carry out the corresponding steps.
78+
79+
| Data Warehouse | Steps |
80+
|------------------------|-------------------------|
81+
| [Snowflake](docs/unify/linked-profiles/setup-guides/snowflake-setup/) | 1. Configure your snowflake database. <br> 2. Enter your credentials. <br> 3. Test the Connection. <br> 4. Click **Save**. |
82+
| [BigQuery](/docs/unify/linked-profiles/setup-guides/bigquery-setup/) | 1. Add your credentials to the database that has tables with the entities you want to enrich your event with. <br> 2. Test your connection. |
83+
| [Redshift](/docs/unify/linked-profiles/setup-guides/redshift-setup/) | 1. Select the Redshift cluster you want to connect. <br> 2. [Configure](/docs/connections/storage/catalog/redshift/#networking) the correct network and security settings. |
84+
85+
## Step 2: Add entities
86+
87+
After you connect your warehouse, use the Data graph overview page (**Unify > Data graph**) to view entities Segment has synced from your data warehouse, add a new entity, and view data warehouse settings.
88+
89+
To add a new entity:
90+
1. Click **Add entity**.
91+
2. Select the table(s) from your warehouse that you'll use as an entity.
92+
3. For each table you select, choose a primary key from the drop-down menu.
93+
- The primary key uniquely identifies rows in your table.
94+
4. Click **Add entities**.
95+
96+
> success ""
97+
> If you don't see data you need, or have recently updated your warehouse, click **Refresh** to update the schema and tables list.
98+
99+
100+
## Step 3: Add a Destination
101+
102+
To use Linked Events, you'll need to add a destination to send enriched events to. Navigate to **Connections > Destinations**. Select an existing destination, or click **+ Add destination** to add a new destination.
103+
104+
> info ""
105+
> For Linked Events, Segment supports [Destination Actions](/docs/connections/destinations/actions/).
106+
107+
108+
## Step 4: Enrich events with entities
109+
With Linked Events, you can select entities and properties from your data warehouse, then add enrichments to map properties to your connected destination.
110+
111+
To enrich events with entities:
112+
113+
1. Navigate to **Connections > Destinations > Event streams**
114+
2. Select the destination you'd like to create an enrichment on.
115+
3. From the Destination overview page, click **Mappings**.
116+
4. Click **New Mapping**, and select the type of mapping you'd like to add.
117+
- Click the **...** icon to edit an existing mapping.
118+
5. In the "Select Events to Map and Send", define the [conditions](/docs/connections/destinations/actions/#conditions) under which the action should run.
119+
6. Click **Load Sample Event**, then add your entities.
120+
121+
### Add entities
122+
123+
After you load a sample event, you can add entities from the **Enrich events with entities** section. You’ll select an entity, then an entity match property.
124+
- The entity match property is the property in the event that you want to match to the primary key.
125+
126+
After you’ve added an entity and match property, add your event enrichments.
127+
128+
### Add enrichments
129+
130+
Use enrichments to select the entity you wish to send to your downstream destination.
131+
132+
In the Mappings tab, locate the **Select Mappings** section where you can enrich source properties from the entities you've selected in the previous step.
133+
134+
1. Select the propery field that you'd like to enrich, then select the **Enrichments** tab.
135+
2. Select the entity you want to send to your destination.
136+
- You’ll have access to all rows/columns in your data warehouse associated with the property you've selected in the previous step.
137+
3. Add the key name on the right side, which is what Segment sends to your destination.
138+
139+
> warning ""
140+
> At this time, Linked Events doesn't support a preview of enriched payloads.
141+
142+
### Test and save your Enrichments
143+
144+
After you’ve added Enrichments, test and save your enrichments.
145+
146+
1. Test the mapping with data from a sample event.
147+
- The edit panel shows you the mapping output in the format for the destination tool. You can change your mapping as needed and re-test.
148+
2. When you're satisfied with the mapping, click **Save**. Segment returns you to the Mappings table.
149+
150+
> warning ""
151+
> At this time, when you select mappings or test events, you won’t see enrichment data. Enrichment data is only available with real events.
152+
153+
## Frequently asked questions
154+
155+
#### What data warehouse permissions does Segment require?
156+
157+
To use Linked Events, be sure that you have proper permissions for the Data Warehouse you're using. Visit the [BigQuery](/docs/unify/linked-profiles/setup-guides/bigquery-setup/), [Snowflake](/docs/unify/linked-profiles/setup-guides/snowflake-setup/), and [Redshift](/docs/unify/linked-profiles/setup-guides/redshift-setup/) setup guides to learn more about updating permissions.
158+
159+
#### How often do syncs occur?
160+
161+
Segment currently syncs once every hour.
162+
163+
#### Which Action Destinations does Linked Events support?
164+
165+
For Linked Events, Segment supports all Actions Destinations.
166+
167+
#### Why aren't test events working?
168+
169+
Test events don't send Linked Events. You'll only see test events that come from the source debugger, which is ahead of the event enrichment.
170+
171+
#### Can I view my Linked Events Audit Trail?
172+
173+
Linked Events uses the existing Audit Trail in your Segment workspace. To view your Audit Trail, navigate to **Settings > Admin > Audit Trail**.
174+
175+
#### How can I refresh linked data from my warehouse?
176+
177+
You can define a schedule for refreshing the linked data from your data warehouse.
178+
179+
180+
181+

‎src/unify/linked-profiles/setup-guides/BigQuery-setup.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: BigQuery Setup
3+
beta: true
4+
plan: unify
5+
---
6+
7+
> info "Linked Events is in private beta"
8+
> Linked Events is in private beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions.
9+
10+
On this page, you'll learn how to connect your BigQuery data warehouse to Segment.
11+
12+
> warning ""
13+
> You need to be an account admin to set up the Segment BigQuery connector as well as write permissions for the `__segment_reverse_etl` dataset.
14+
15+
To set up the Segment BigQuery connector:
16+
17+
1. Navigate to **IAM & Admin > Service Accounts** in BigQuery.
18+
2. Click **+ Create Service Account** to create a new service account.
19+
3. Enter your **Service account name** and a description of what the account will do.
20+
4. Click **Create and Continue**.
21+
5. In the **Grant this service account access to project** section, select the [*BigQuery User*](https://cloud.google.com/bigquery/docs/access-control#bigquery.user){:target="_blank"} role to add.
22+
6. Click **+ Add another role** and add the *BigQuery Job User* role.
23+
7. Click **+ Add another role** and add the [*BigQuery Metadata Viewer*](https://cloud.google.com/bigquery/docs/access-control#bigquery.metadataViewer){:target="_blank"} role.
24+
8. Click **Continue**, then click **Done**.
25+
9. Search for the service account you've just created.
26+
11. From your service account, click the three dots under **Actions** and select **Manage keys**.
27+
12. Click **Add Key > Create new key**.
28+
13. In the pop-up window, select **JSON** for the key type, and click **Create**.
29+
14. Copy all the content within the file you've created and downloaded.
30+
15. Navigate to Segment and paste all the credentials you've just copied into the **Enter your credentials** section as you connect your warehouse destination.
31+
32+
## Grant access to datasets and tables for enrichment
33+
34+
Grant access to datasets and tables so that Segment can list datasets, tables, and columns, and create Linked Events.
35+
36+
Grant
37+
- [`BigQuery Data Viewer`](https://cloud.google.com/bigquery/docs/access-control#bigquery.dataViewer){:target="_blank"} role <br>
38+
OR
39+
- Permissions:
40+
- `bigquery.datasets.get`
41+
- `bigquery.tables.list`
42+
- `bigquery.tables.get`
43+
- `bigquery.tables.getData`
44+
45+
These can be scoped to projects or [datasets](https://cloud.google.com/bigquery/docs/control-access-to-resources-iam#grant_access_to_a_dataset){:target="_blank"}.
46+
47+
> info ""
48+
> To create Linked Events on your listed tables, Segment needs `bigquery.tables.get` and `bigquery.tables.getData` at dataset level. However, you can still scope `bigquery.tables.get` and `bigquery.tables.getData` to specific tables. See BigQuery's [docs](https://cloud.google.com/bigquery/docs/control-access-to-resources-iam#grant_access_to_a_table_or_view){:target="_blank"} for more info.
49+
50+
51+

‎src/unify/linked-profiles/setup-guides/redshift-setup.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Redshift Setup
3+
beta: true
4+
plan: unify
5+
---
6+
7+
> info "Linked Events is in private beta"
8+
> Linked Events is in private beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions.
9+
10+
On this page, you'll learn how to connect your Redshift data warehouse to Segment.
11+
12+
## Getting started
13+
14+
To get started with Redshift:
15+
1. Log in to Redshift and select the Redshift cluster you want to connect.
16+
2. Follow these [networking instructions](/docs/connections/storage/catalog/redshift/#networking) to configure network and security settings.
17+
18+
## Create a new role and user
19+
20+
Run the SQL commands below to create a role (`segment_entities`) and user (`segment_entities_user`).
21+
22+
```sql
23+
-- create role
24+
CREATE ROLE segment_entities;
25+
26+
-- allow the role to create new schemas on specified database. (This is the name you chose when provisioning your cluster)
27+
GRANT CREATE ON DATABASE "<enter database name here>" TO ROLE segment_entities;
28+
29+
-- create a user named "segment_entities_user" that Segment will use when connecting to your Redshift cluster.
30+
CREATE USER segment_entities_user PASSWORD '<enter password here>';
31+
32+
-- grant role permissions to the user
33+
GRANT ROLE segment_entities TO segment_entities_user;
34+
```
35+
36+
## Grant access to schemas and tables
37+
38+
You'll need to grant access to schemas and tables that you'd like to enrich with. This allows Segment to list schemas, tables, and columns, as well as create entities with data extracted and ingested to Segment.
39+
40+
### Schemas
41+
42+
Grant schema permissions based on customer need. Visit Amazon's docs to view [schema permissions](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT.html){:target="_blank"} and [example commands](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT-examples.html){:target="_blank"} that you can use to grant permissions.
43+
44+
```ts
45+
-- view specific schemas in database
46+
GRANT USAGE ON SCHEMA <schema-name> TO ROLE segment_entities;
47+
```
48+
49+
### Tables
50+
51+
Grant table permissions based on customer need. Learn more about Amazon's [table permissions](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT.html){:target="_blank"}.
52+
53+
```ts
54+
-- query data from a specific table in a schema
55+
GRANT SELECT ON TABLE <schema-name>.<table-name> TO ROLE segment_entities;
56+
```
57+
58+
### RETL table permissions
59+
60+
If you used RETL in your database, you'll need to add the following [table permissions](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT.html){:target="_blank"}:
61+
62+
```ts
63+
GRANT USAGE, CREATE ON SCHEMA __segment_reverse_etl TO ROLE segment_entities;
64+
65+
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA __segment_reverse_etl TO ROLE segment_entities;
66+
```

0 commit comments

Comments
 (0)