Skip to main content

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

​
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 TypePurposeUse Case
User ProfileStatic user attributesDemographics, subscription tiers, preference data
User ActivityTime-stamped eventsPurchase history, content interactions, conversion events
IdentityUser identity mappingsLinking user IDs across systems, cross-device identity resolution
GroupHousehold or group membershipsHousehold graphs, account-level groupings, shared identity relationships

​
Step 1: Start the Import Wizard

1

Navigate to Imports

In the Permutive Dashboard, go to Connectivity > Imports and click Create Import.
2

Enter an Import Name

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”).
3

Select the Source Type

Choose the source platform your data is stored in (e.g., Google BigQuery, Snowflake, Amazon S3, Google Cloud Storage).
4

Select the Connection

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

1

Choose the Schema

Select the schema (dataset or database schema) that contains the table you want to import. The available schemas are discovered from your active connection.
2

Choose the Table

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

FieldRequiredDescription
User IDYesThe 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 before they can be used.
AttributesNoAdditional 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

FieldRequiredDescription
User IDYesThe 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 before they can be used.
Time FieldYesA timestamp column used for incremental sync. A time range that determines the sync window must also be selected.
AttributesNoAdditional 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:

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

​
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

Sources Overview

Learn more about managing your source connections

Importing User Identity

Set up user identity imports to link identifiers

Importing User Group Memberships

Set up household and group identity imports