Linked Events

Free x
Team x
Business ✓
Unify ✓

Unify requires a Business tier account and is included with Engage.
See the available plans, or contact Support.

Linked Events is in private beta

Linked Events is in private beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available.

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.

Linked Events warehouse support

Linked Events supports Snowflake, BigQuery, and Redshift.

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.


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.

Segment stores and processes all data in the United States.

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

Linked Events uses Segment’s Reverse ETL infrastructure for pulling in data from your warehouse.

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, Snowflake, and Redshift.

Step 2: Connect your warehouse to the Data Graph

Before getting started with the Data Graph, be sure to set up your warehouse permissions.

  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.


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.

Only sync what you need for enrichment. There may be cost implications to having Segment query your warehouse tables.

Linked Events syncs data from your warehouse approximately once every hour.

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.

Data Warehouse Steps
Snowflake 1. Configure your snowflake database.
2. Enter your credentials.
3. Test the Connection.
4. Click Save.
BigQuery 1. Add your credentials to the database that has tables with the entities you want to enrich your event with.
2. Test your connection.
Redshift 1. Select the Redshift cluster you want to connect.
2. Configure the correct network and security settings.

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.

Deleting entities and relationships are not yet supported.

Defining entities

Snowflake schemas are case sensitive, so you’ll need to reflect the schema, table, and column names based on how you case them in Snowflake.

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

Parameters Definition
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).
name A unique label which will display across Segment.
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].
primary_key The unique identifier for the given table. Should be a column with unique values per row.
(Optional) enrichment_enabled = true Indicates if you plan to also reference the entity table for Linked Events.
# 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.

For Linked Events, Segment supports Destination Actions in cloud-mode only.

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.

At this time, Linked Events doesn’t support a preview of enriched payloads.

Save your Enrichments

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

At this time, when you select mappings or test events, you won’t see enrichment data. Enrichment data is only available with real events.


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, 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.

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.

This page was last modified: 22 Feb 2024

Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
Create free account