Skip to main content
Use array expansion when your source stores multiple values in a single array column but your destination expects one record per value. For example, if a user has several device IDs in an array column, array expansion creates a separate sync row for each ID so you can sync each one individually.
Array expansion is supported with the Lightning sync engine on Postgres, Snowflake, BigQuery, and Databricks sources.

​
Before you begin

​
How it works

When you map an array-type column as the identifier in your sync configuration, Hightouch automatically enables array expansion. Each element of the array becomes a separate row, and a generated column is used as the identifier value sent to the destination.

​
Example

Consider this source table with an array column device_ids: When you map device_ids as the identifier for your sync, Hightouch expands each row so that every array element becomes its own record: The generated column _ht_device_ids_element contains the individual element value and is used as the identifier sent to the destination.

​
Empty arrays

Rows where the array column is empty ([]) or NULL produce zero output rows. In the example above, Charlie’s row is omitted entirely because device_ids is an empty array.

​
Duplicate elements

If an array contains duplicate values (like Dana’s two "web_d4" entries), the duplicates produce a primary key collision. The sync completes with a “Report” status and the duplicate rows are flagged as rejected. Only one row per unique element value is synced.

​
Configuration

Array expansion is configured automatically when you map an array-type column as the identifier in the “How should rows be matched?” section of your sync configuration. When an array column is selected:
  1. Hightouch sets the arrayExpansionSourceColumn in your sync config
  2. The identifier mapping is automatically translated to use the generated element column (_ht_{column}_element)
  3. An info banner confirms that array expansion is active
To disable array expansion, change the identifier mapping to a non-array column.

​
Supported column types

Array expansion works with columns of the following types:
  • Native arrays: Postgres text[], Snowflake ARRAY, BigQuery ARRAY<STRING>, Databricks ARRAY<STRING>
  • JSON arrays: Postgres jsonb, Snowflake VARIANT, BigQuery JSON
  • JSON string arrays: VARCHAR columns containing JSON-encoded arrays like '["a","b"]'
Hightouch automatically detects the column type and applies the appropriate expansion strategy.

​
Limitations

  • Only one array column can be expanded per sync
  • Array expansion requires the Lightning sync engine
  • Only supported on Postgres, Snowflake, BigQuery, and Databricks sources
  • Duplicate values within an array cause row-level rejections
  • Array expansion is not available on syncs that use Match Booster, as Match Booster applies its own identity resolution logic that is incompatible with row expansion
Last modified on August 20, 2026