Skip to main content

​
Overview

Import segment memberships from your data warehouse using Connectivity. User Segment imports let you bring pre-built segments or audiences — for example, segments modeled in your warehouse or supplied by a partner — into Permutive, where they can be used for targeting and activation. Each row in your source table associates a user with the segments they belong to. Optionally, you can also indicate which segments a user has left. Segment data is ingested and stored as soon as your import starts syncing, whether or not a taxonomy is in place — but you’ll need a taxonomy that maps raw segment IDs to human-readable names before those segments can be used, for example in the Cohort Builder. You can add a taxonomy when you create the import, or at any point afterwards.
This guide speaks to the new flow that was previously “Audience Imports.” User Segment imports are now created and managed from the same Imports page as every other import type, under Connectivity.
Prerequisites:A taxonomy CSV mapping your segment IDs to human-readable names is not required to create the import — segment data is ingested either way — but you’ll need one before the segments can be used. See Taxonomies.

​
Choosing an Update Strategy

There are two ways to deliver segment data to Permutive, and how you configure the optional fields — the Time Field, the Segments Deleted column, and the retention period — depends on which one you choose. Incremental updates — Your table accumulates rows describing changes: each row carries the affected user, the segments they’ve been added to (Segment ID), any segments they’ve left (Segments Deleted), and a timestamp. Map the Time Field so that on each sync Permutive only processes rows newer than the last import. This is the most efficient approach — only changed rows are processed, which minimizes data egress from your warehouse and keeps processing volumes low. Set a longer retention period as a backstop that expires memberships for users your data stops mentioning. Full refresh — Your table always holds the complete, current set of memberships (for example, a table your warehouse re-materializes daily), and Permutive re-imports it in full on each daily sync. A Time Field isn’t needed, since the whole table is processed on every sync. A Segments Deleted column isn’t needed either — by default, when a user leaves a segment, the membership simply stops appearing in the table and expires once the retention period passes. However, you can still map a Segments Deleted column if you want: any exit rows it contains are processed and applied immediately rather than being ignored, so those removals don’t have to wait for retention to lapse. Set a short retention period — 3–7 days for a daily refresh — so removals still take effect quickly for users who drop out of the table without an explicit exit row, while leaving a safety margin in case an import run is delayed.

​
Steps

1

Prepare your source table

Create or identify a table in your warehouse. Its shape depends on your update strategy:
  • A user ID column (required): Contains user identifiers of a single identifier type configured in Permutive
  • A segment ID column (required): Contains the segments the user belongs to, as either an array or a delimited string
  • A segments deleted column (optional): Contains segments the user has been removed from, in the same format. Recommended for incremental updates; can also be mapped for a full refresh to apply exits immediately instead of waiting for retention (see Choosing an Update Strategy)
  • A time column (incremental updates): The timestamp used as the sync cursor
2

Start the import wizard

In the Permutive Dashboard, go to Connectivity > Imports and click Create Import. Enter a name, select the source type and connection, then choose the schema and table containing your segment data. See Creating an Import for details on these steps.
3

Select the data type

Select User Segment as the data type.
4

Map your columns

  • Map the User ID field to your user ID column and declare its identifier type
  • Map the Segment ID field to your segment column. If the column is a string, select the separator used to delimit segment IDs
  • For incremental updates, map the Segments Deleted field (selecting a separator if the column is a string) and the Time Field. For a full refresh, leave the Time Field unmapped — it isn’t used. You can optionally map Segments Deleted as well, so exits are applied immediately rather than waiting for retention to expire the membership
5

Set the retention period

Use the Retain data for dropdown to choose how long imported segment memberships are kept before expiring automatically. Choose a short period (3–7 days) for a full refresh, or a longer one (the 60-day default or higher) for incremental updates.
6

Add a taxonomy

In the Taxonomy section, upload a new taxonomy CSV or select an existing one to map raw segment IDs to human-readable names. This step is optional here — segment data is ingested and stored regardless — but a taxonomy is required before the segments can be used, for example in the Cohort Builder. You can skip this step for now and add or update a taxonomy at any later point. See Taxonomies below for the file format.
7

Save and verify

Click Save to create the import. After the first sync runs, verify on the Imports page that data was successfully imported.

​
Data Format Requirements

Your source table needs a user ID column and a segment ID column. The column names can be anything — what matters is the data each column contains. The segment columns can be either array columns: or string columns holding delimited segment IDs: Important notes:
  • User ID: All values must be of a single identifier type (e.g., Permutive User ID, email hash) that is configured in Permutive. Declare this type when mapping the column.
  • Segment ID: Contains the segments the user currently belongs to. For string columns, choose the separator when mapping the column: comma, semicolon, colon, vertical bar, caret, or tab.
  • Segments Deleted (optional): Contains segments the user has left or been removed from. The same array-or-delimited-string rules apply. Recommended for incremental updates; not required for a full refresh, but if mapped, exit rows are still processed rather than ignored.
  • Time Field (optional): A timestamp or text column that acts as the sync cursor for incremental updates — on each sync, only rows newer than the last import are processed. Not needed for a full refresh.
Snowflake sources do not support array columns for the Segment ID and Segments Deleted fields. When importing from Snowflake, use string columns with a separator.

​
Multiple Rows Per User

A user can appear in more than one row within the same sync — each row’s Segment ID and Segments Deleted values are processed independently, and segment membership accumulates across rows for that user. If two rows for the same user conflict (for example, one row adds a segment that another removes), Permutive resolves this by processing the later record, based on the Time Field. Without a Time Field mapped — as in a full refresh with no time column — conflict resolution between rows for the same user is non-deterministic. This doesn’t come up if your table already reflects the complete, current membership for each user, as recommended for a full refresh; but where you can, keep to one row per user per sync to avoid relying on it.

​
Data Retention

You can configure a data retention period (TTL) when creating the import. This determines how long imported segment memberships are kept before they expire automatically. Available retention periods range from 2 days to 180 days; the default is 60 days. The role the retention period plays depends on your update strategy:
  • Full refresh — Retention is the primary cleanup mechanism for users who simply stop appearing in the table. Because the full table is re-imported on each sync, a short retention period (3–7 days for a daily refresh) means memberships expire soon after that happens. If you also map a Segments Deleted column, explicit exits are processed immediately, and retention becomes a backstop for the remaining case.
  • Incremental updates — Retention is a backstop. Removals are communicated explicitly via the Segments Deleted column, so a longer retention period (the 60-day default or higher) simply expires memberships for users your data stops mentioning.
We recommend setting the retention period at least 2–3 days longer than your import frequency to provide a safety margin in case of delayed processing. Very short retention periods risk losing active data if an import run is delayed.

​
Taxonomies

Taxonomies map raw segment IDs to human-readable names used across data imports. Segment data is ingested and stored as soon as your import syncs, regardless of whether a taxonomy is attached — rows with unrecognized segment IDs aren’t dropped. A taxonomy is required only to make those segments usable, for example in the Cohort Builder, and you can create or attach one at any time, whether during import creation or afterwards. When creating a User Segment import, the Taxonomy section offers two options:
  • Upload New Taxonomy — Upload a CSV file with segment ID definitions
  • Use Existing Taxonomy — Select from previously uploaded taxonomies
Taxonomy files must meet the following requirements:
  • The file must be a comma-separated file (.csv), with a maximum size of 50MB
  • The file must contain a header row as the first line
  • The file must contain these columns, in this exact order. The CPM (USD) column is optional and can be omitted entirely if you don’t need it:
If you set a CPM value, you will be billed through our third-party billing. If you don’t intend to be billed, omit the CPM column entirely or set the value to 0.

​
Next Steps

Creating an Import

Full walkthrough of the import wizard and all data types

Connections Overview

Learn more about managing your connections