> ## 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.
# Creating an Import
> How to create a data import from an active connection in Permutive
## Overview
This guide walks you through creating an import from an active connection. Imports pull data from your connected data warehouses or data lakes into Permutive, where it can be used for audience building, targeting, and activation. Each import is configured with a specific data type and column mapping that determines how Permutive processes the incoming data.
**Prerequisites:**
* An active connection (see guides for [BigQuery](/guides/connectivity/sources/connecting-to-bigquery), [Snowflake](/guides/connectivity/sources/connecting-to-snowflake), [Amazon S3](/guides/connectivity/sources/connecting-to-amazon-s3), or [Google Cloud Storage](/guides/connectivity/sources/connecting-to-gcs))
* A table in your source that contains the data you want to import
* Knowledge of which data type best matches your use case (see [Import Data Types](#import-data-types) below)
## Import Data Types
Before creating an import, determine which data type matches the data you want to bring into Permutive. Each data type serves a different purpose and requires different column mappings.
| Data Type | Purpose | Use Case |
| :---------------- | :----------------------------- | :----------------------------------------------------------------------- |
| **User Profile** | Static user attributes | Demographics, subscription tiers, preference data |
| **User Activity** | Time-stamped events | Purchase history, content interactions, conversion events |
| **Identity** | User identity mappings | Linking user IDs across systems, cross-device identity resolution |
| **Group** | Household or group memberships | Household graphs, account-level groupings, shared identity relationships |
## Step 1: Start the Import Wizard
In the Permutive Dashboard, go to **Connectivity > Imports** and click **Create Import**.
Provide a descriptive name for your import. Choose a name that identifies the data source and purpose (e.g., "BigQuery - Purchase History", "Snowflake - CRM Profiles").
Choose the source platform your data is stored in (e.g., Google BigQuery, Snowflake, Amazon S3, Google Cloud Storage).
Choose the active connection you want to import from. Only connections with an "Active" status are available.
If your connection isn't listed, check its status on the **Connections** page. It may still be processing or may have become inactive.
## Step 2: Select Schema and Table
Select the schema (dataset or database schema) that contains the table you want to import. The available schemas are discovered from your active connection.
Select the table you want to import data from. Permutive displays the tables discovered within the selected schema.
If you don't see an expected table, click **Resync with source** to refresh the list of available schemas and tables from your source platform. This is useful if tables have been added since the connection was created.
## Step 3: Select the Data Type
Choose the data type that matches the structure and purpose of your data. The data type you select determines which columns you'll need to map in the next step.
* **User Profile** — For importing static user attributes such as demographics, subscription tiers, or CRM segments. Use this when your data describes properties of individual users that don't change frequently.
* **User Activity** — For importing time-stamped event data such as purchase history, content interactions, or conversion events. Use this when your data contains records of actions users have taken, each associated with a timestamp.
* **Identity** — For importing identity mappings that link different user identifiers together. Use this to enrich Permutive's Identity Graph with cross-system or cross-device identity relationships.
* **Group** — For importing household or group membership data. Use this to associate users with groups such as households, accounts, or other shared identity structures.
## Step 4: Map Your Columns
After selecting your data type, map the columns from your source table to the fields Permutive expects. Each data type has a set of required fields and optional attribute fields.
### User Profile
| Field | Required | Description |
| :------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **User ID** | Yes | The column containing unique user identifiers. The identifier type (e.g., Permutive User ID, email hash) that the column represents must also be declared. Identifier types must be [configured in the Identity Graph](/guides/signals/identity/configuring-identifiers) before they can be used. |
| **Attributes** | No | Additional columns to import as user properties (e.g., age, subscription tier, region) |
User Profile imports are designed for data that describes who your users are. Each row should represent a single user, and the User ID column must contain a unique identifier for that user.
### User Activity
| Field | Required | Description |
| :------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **User ID** | Yes | The column containing unique user identifiers. The identifier type (e.g., Permutive User ID, email hash) that the column represents must also be declared. Identifier types must be [configured in the Identity Graph](/guides/signals/identity/configuring-identifiers) before they can be used. |
| **Time Field** | Yes | A timestamp column used for incremental sync. A time range that determines the sync window must also be selected. |
| **Attributes** | No | Additional columns to import as event properties (e.g., product category, purchase amount) |
The **Time Field** column is critical for User Activity imports. It must be a monotonically increasing timestamp that Permutive uses to track which records have already been imported. On each sync, Permutive reads only records with a time field value greater than the last imported value. The time field column should not be updated after a record is created.
### Identity and Group
For detailed column mapping and setup instructions:
* [Importing User Identity](/guides/signals/identity/importing-user-identity) for linking user-level identifiers
* [Importing User Group Memberships](/guides/signals/identity/importing-user-group-memberships) for household and group relationships
### Data Retention (Identity and Group Identity imports)
For Identity and Group Identity imports, you can configure a **data retention period** that determines how long imported data is kept in Permutive before it expires automatically. This is set per data type via the **Retain data for** dropdown on the import mapping card.
Available retention periods range from 2 days to 180 days (the default).
**For Group Identity imports**, data retention is an alternative to using the `is_deleted` column to manage stale data. Explicit deletions via `is_deleted` are the most efficient approach — only changed and deleted rows are processed, which minimizes data egress from your warehouse and keeps processing volumes low. However, if communicating deletions is cumbersome or not supported by your source system, a retention period is a convenient alternative.
**For Identity imports**, data retention lets you align how long identity mappings are kept with how long the underlying identifiers remain useful. This is particularly relevant for identifiers that naturally go stale, such as cookie-based IDs or mobile advertising IDs.
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. For example, if you refresh your data daily, a retention period of 3–7 days is a good starting point. Very short retention periods risk losing active data if an import run is delayed.
## Step 5: Save the Import
Once your column mappings are configured, click **Save** to create the import. The import will begin processing and will sync data from your source on its next scheduled run.
Imports sync on a daily schedule, pulling new and updated data from your source table into Permutive.
## Understanding Audience Size for Import Cohorts
When you create a cohort that includes imported data, you may notice that the **Predicted Audience Size (PAS)** is significantly larger than the **Live Audience Size (LAS)** immediately after deployment. This is expected behavior.
**Why this happens:**
* **PAS is a historical estimate.** It is calculated server-side using the past 30 days of data, including imported identifiers resolved against the identity graph. This means PAS can reflect users who have not visited your properties recently.
* **LAS counts only users evaluated since deployment.** LAS is updated periodically (approximately every 4 hours) as users interact with your properties. Imported users must return to your site or app before they can be counted in LAS.
* **No backfill.** LAS does not retroactively count users who qualified before the cohort was deployed. It only counts users going forward from the moment of deployment.
* **Identity resolution is progressive.** For imported users identified by external identifiers (such as hashed emails), the SDK must match the imported identity to a Permutive user ID when the user visits. This matching happens over time as users return.
**What to expect:**
* LAS will start at zero and grow over the first days and weeks as imported users visit your properties.
* The rate of growth depends on your traffic volume and how frequently imported users visit.
* After approximately 30 days, LAS should stabilize and more closely reflect PAS (assuming consistent user behavior).
* LAS may never fully reach PAS, because not all historically qualifying users may return within the cohort's recency window.
If LAS remains at zero for more than 48 hours after deployment, verify that the import is active and syncing data, and that the Permutive SDK is deployed on the properties where imported users are expected to visit. Also check that imported identifiers are correctly mapped and match the identity graph.
For a full explanation of Predicted and Live Audience Sizes, see [Custom Cohorts: Audience Size Definitions](/products/signals/cohorts/custom#whats-the-difference-between-predicted-audience-size-and-live-audience-size).
## Managing Imports
### Viewing Import Status
After creating an import, you can monitor it from the **Imports** page. Each import displays:
* **Name** — The name you provided during creation
* **Source** — The platform and connection used
* **Data Type** — The type of data being imported
* **Status** — Whether the import is active, processing, or has encountered errors
* **Last Sync** — When data was last successfully imported
### Resyncing Schema
If your source table has new columns added since the import was created, you can resync the schema to discover them:
1. Go to **Connectivity > Imports** and click **Create Import**
2. Enter a name, select the source, and select the connection
3. Click **Resync with source** to refresh the available schemas, tables, and columns
Schema resync discovers new columns but does not automatically update existing imports. If you need to include new columns, you'll need to create a new import with the updated column mapping.
### Deleting an Import
You can delete an import when it's no longer needed. Deleting an import has the following effects:
* **Data syncing stops immediately** — No further data will be pulled from the source table
* **Data retention** — For non-composable deployments, a 30-day time-to-live (TTL) is applied to the imported data. After 30 days, the data is removed from Permutive. For composable deployments, the data remains in your cloud environment
* **Cohort Builder impact** — The import is removed from the Cohort Builder as an available data source. Any existing cohorts that reference the deleted import will display a warning indicating the import is no longer active
* **Audience evaluation** — Cohort expressions that depend on the deleted import will stop evaluating against the imported data
Before deleting an import, review any cohorts that depend on it. Deleting an import can affect active campaigns and audience targeting. Cohorts that reference the import will continue to exist but will no longer include users based on the deleted import's data.
To delete an import:
1. Navigate to **Connectivity > Imports**
2. Select the import you want to delete
3. Click **Delete Import** and confirm the action
## Troubleshooting
If your import fails during initial processing:
* Verify the source connection is still active
* Check that the selected table exists and contains data
* Ensure your column mappings match the actual column names and data types in the source table
**Solution:** Review the import configuration and source table. If the connection has become inactive, create a new connection and reconfigure the import.
If expected columns don't appear during the column mapping step:
* The schema may not have been refreshed since the columns were added
* The column data type may not be supported
**Solution:** Use the **Resync with source** option to refresh the available columns from your source table.
If your User Activity import isn't picking up new records:
* The time field column may not be monotonically increasing
* Records may have been updated (changing the time field value) rather than inserted as new rows
* The time field column may contain null values
**Solution:** Ensure your time field column is a timestamp that is set once when a record is created and never updated. Remove or handle null values in the time field column.
If imported data isn't available in the Cohort Builder:
* The import may still be processing its first sync
* The column mapping may be incorrect
* The data type selected may not match the structure of your data
**Solution:** Check the import status on the Imports page. If the sync completed successfully but data isn't appearing, review your column mappings and data type selection. You may need to delete the import and recreate it with the correct configuration.
## Next Steps
Learn more about managing your source connections
Set up user identity imports to link identifiers
Set up household and group identity imports