Linked Events Overview

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.

On this page, you’ll learn how to get started with Linked Events.

Use cases

With Linked Events, you can:

• 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.
• Sync enriched data. Add a loyalty ID to event payloads before sending it downstream to destinations such as Amplitude, Mixpanel, and more.
• 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.

Prerequisites

To use Linked Events, you’ll need the following:

1. A supported data warehouse.
2. Access to Unify in your workspace.
3. Access to the actions-based destination you’ll be using with Linked Events so that you can validate your data.

Linked Events roles

The following Segment access roles apply to Linked Events:

Entities Admin Access: Entities Admins have the ability to view and edit entity models and connection details.

Entities Read-only Access: Entities Read-only users have the ability to view entity models.

To create models and enrich events in destinations, you need to be a Workspace Owner or have the following roles:

• Unify Admin
• Entities Admin
• Source Admin

Step 1: Set up your data warehouse and permissions

To get started, you’ll need to set up your data warehouse and provide the correct access detailed in the set up steps below. Linked Events supports BigQuery, Databricks, Snowflake, and Redshift.

Step 2: Connect your warehouse to the Data Graph

1. Navigate to Unify > Data graph and click Add warehouse.
2. Select a warehouse to connect from the supported data warehouses.
3. Connect your warehouse.
4. Click Test Connection to be sure your warehouse is connected.
5. After a successful test, click Save.

Schema

Linked Events uses Reverse ETL to compute the incremental changes to your data directly within your data warehouse. The Unique Identifier column detects data changes, such as new, updated, and deleted records.

For Segment to compute data changes in your warehouse, Segment requires both read and write permissions to the warehouse schema table. At a high level, the extract process requires read permissions for the query being executed. Segment tracks changes to the query results through tables that Segment manages in a dedicated schema (for example, _segment_reverse_etl), which requires some write permissions.

Supported data warehouses

The table below shows the data warehouses Linked Events supports. View the Segment docs for your warehouse, then carry out the corresponding steps.

Step 3: Build your Data Graph

The Data Graph is a semantic layer that represents a subset of relevant business data that you’ll use to enrich events in downstream tools. Use the configuration language spec below to add models to build out your Data Graph.

Each Unify space has one Data Graph. The current version is v0.0.6 but this may change in the future as Segment accepts feedback about the process.

Defining entities

An entity is a stateful representation of a business object. The entity corresponds to a table in the warehouse that represents that entity.

# Define an entity and indicate if the entity will be referenced for Linked Events (enrichment_enabled=true)

entity "account-entity" {
     name = "account"
     table_ref = "CUST.ACCOUNT"
     primary_key = "id"
     enrichment_enabled = true
}

Step 4: Add an actions-based destination

To use Linked Events, you’ll need to add an action destination to send enriched events to. Navigate to Connections > Destinations. Select an existing action destination, or click + Add destination to add a new action destination.

Step 5: Enrich events with entities

With Linked Events, you can select entities and properties from your data warehouse, then add enrichments to map properties to your connected destination.

To enrich events with entities:

1. Navigate to Connections > Destinations > Event streams
2. Select the destination you’d like to create an enrichment on.
3. From the Destination overview page, click Mappings.
4. Click New Mapping, and select the type of mapping you’d like to add.
   • Click the … icon to edit an existing mapping.
5. In the “Select Events to Map and Send”, define the conditions under which the action should run.
6. Click Load Sample Event, then add your entities.

Add entities

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.

• The entity match property is the property in the event that you want to match to the primary key.

After you’ve added an entity and match property, add your event enrichments.

Add enrichments

Use enrichments to select the entity you wish to send to your downstream destination.

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.

1. Select the property field that you’d like to enrich, then select the Enrichments tab.
2. Select the entity you want to send to your destination.
   • You’ll have access to all rows/columns in your data warehouse associated with the property you’ve selected in the previous step.
3. Add the key name on the right side, which is what Segment sends to your destination.

Save your enrichments

When you’re satisfied with the mappings, click Save. Segment returns you to the Mappings table.

Enrichment observability

To verify which of your events matched one or more enrichments:

1. Navigate to Delivery Overview for your connected destination.
2. Select the Successfully received step in the pipeline view.
3. Select the Events enriched tab. This table breaks down events into the following categories:
   • Successfully enriched: Events that were enriched by all entities
   • Partially enriched: Events that were only enriched by only some of your entities
   • Unenriched events: Events that did not match any entities

FAQs

What data warehouse permissions does Segment require?

To use Linked Events, be sure that you have proper permissions for the Data Warehouse you’re using. Visit the BigQuery, Databricks, Snowflake, and Redshift setup guides to learn more about updating permissions.

How often do syncs occur?

Segment currently syncs once every hour.

Which Destinations does Linked Events support?

For Linked Events, Segment supports all actions-based destinations in cloud-mode. Device-mode destinations are not supported.

Why aren’t test events working?

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.

Can I view my Linked Events Audit Trail?

Linked Events uses the existing Audit Trail in your Segment workspace. To view your Audit Trail, navigate to Settings > Admin > Audit Trail.

How can I refresh linked data from my warehouse?

You can define a schedule for refreshing the linked data from your data warehouse.

How do I use entities in my data graph with Linked Events?

To use entities with Linked Events, you’ll need to set the enrichment_enabled flag to true. Here’s the sample code:

# Define an entity and indicate if the entity will be referenced for Linked Events (enrichment_enabled=true)

entity "account-entity" {
     name = "account"
     table_ref = "CUST.ACCOUNT"
     primary_key = "id"
     enrichment_enabled = true
}