> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing User Segments (previously Audience Imports)

> How to set up Connectivity imports for user segment data, including data format requirements and taxonomies

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

<Note>
  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**.
</Note>

<Info>
  **Prerequisites:**

  * An active connection (see guides for [BigQuery](/guides/connectivity/connections/connecting-to-bigquery), [Snowflake](/guides/connectivity/connections/connecting-to-snowflake), [Amazon S3](/guides/connectivity/connections/connecting-to-amazon-s3), or [Google Cloud Storage](/guides/connectivity/connections/connecting-to-gcs))
  * A table in your source containing user IDs and their segment memberships
  * The user identifier type used in your table [configured in the Identity Graph](/guides/signals/identity/configuring-identifiers)

  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](#taxonomies).
</Info>

## 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                                                                             | Full refresh                                                                                                                                      |
| :------------------------- | :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Table contents**         | New and changed rows, each with a timestamp                                                     | The complete, current set of segment memberships                                                                                                  |
| **Time Field**             | Required — acts as the sync cursor, so only rows newer than the last import are processed       | Not needed — the full table is processed on each sync                                                                                             |
| **Segments Deleted**       | Recommended — explicitly removes users from segments                                            | Optional — if mapped, exit rows are processed immediately rather than ignored; otherwise stale memberships simply expire via the retention period |
| **Retention period (TTL)** | Longer (the 60-day default or higher), as a backstop for users that stop appearing in your data | Short (3–7 days), so memberships lapse soon after a user disappears from the table                                                                |

**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

<Steps>
  <Step title="Prepare your source table">
    Create or identify a table in your warehouse. Its shape depends on your [update strategy](#choosing-an-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](#choosing-an-update-strategy))
    * A **time column** (incremental updates): The timestamp used as the sync cursor
  </Step>

  <Step title="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](/guides/connectivity/imports/creating-an-import) for details on these steps.
  </Step>

  <Step title="Select the data type">
    Select **User Segment** as the data type.
  </Step>

  <Step title="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
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](#taxonomies) below for the file format.
  </Step>

  <Step title="Save and verify">
    Click **Save** to create the import. After the first sync runs, verify on the **Imports** page that data was successfully imported.
  </Step>
</Steps>

### 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:

| user\_id | segments            | segments\_deleted | updated\_at         |
| -------- | ------------------- | ----------------- | ------------------- |
| user123  | \["sports", "news"] | \["travel"]       | 2025-01-01 10:00:00 |
| user124  | \["finance"]        | \[]               | 2025-01-01 10:00:00 |

or **string** columns holding delimited segment IDs:

| user\_id | segments    | segments\_deleted | updated\_at         |
| -------- | ----------- | ----------------- | ------------------- |
| user123  | sports,news | travel            | 2025-01-01 10:00:00 |
| user124  | finance     |                   | 2025-01-01 10:00:00 |

**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](#choosing-an-update-strategy); 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](#choosing-an-update-strategy) — on each sync, only rows newer than the last import are processed. Not needed for a full refresh.

<Note>
  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.
</Note>

### 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](#choosing-an-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.

<Note>
  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.
</Note>

### 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:

| Column          | Required | Description                                           |
| :-------------- | :------- | :---------------------------------------------------- |
| **ID**          | Yes      | The raw segment ID as it appears in your source table |
| **Name**        | Yes      | The human-readable segment name                       |
| **Description** | Yes      | A description of the segment                          |
| **CPM (USD)**   | No       | The CPM price for the segment, in USD                 |

<Warning>
  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`.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Creating an Import" icon="download" href="/guides/connectivity/imports/creating-an-import">
    Full walkthrough of the import wizard and all data types
  </Card>

  <Card title="Connections Overview" icon="database" href="/products/connectivity/connections">
    Learn more about managing your connections
  </Card>
</CardGroup>