Overview
dentsu.Composable Push allows you to send audience data directly from Snowflake to Merkury Explorer. Push supports three audience types:
- Single-attribute audiences
- Multi-attribute audiences
- Opt-out audiences
Push also provides a way to check the status of audience ingestion in DataBridge.
Load an audience
To load an audience, run the PUSH_AUDIENCE procedure and specify one of the following audience-type parameters:
single-attributemulti-attributeopt-out
Enter the applicable audience-type parameter exactly as shown. Do not modify these values.
A multi-attribute audience results in multiple audiences in Merkury Explorer: one parent audience with the audience name provided in the SQL statement and child audiences named after the custom-attribute columns in the source table.
Minimum matched audience size
An audience does not load if fewer than 100 submitted identifiers match in Merkury Explorer.
Access to new audience tables
Grant Push SELECT access to each new audience table added after the initial configuration. If the new table uses a database and schema that Push can already access, you do not need to repeat the database and schema grants. For more information, see Configure the Push app.
Before running a PUSH_AUDIENCE procedure, confirm that:
- A warehouse is selected in the Snowflake UI.
- The applicable Merkury Explorer advertiser is registered with Push.
A successful response from PUSH_AUDIENCE indicates that audience ingestion has started. Use the status query returned in the response to monitor the audience’s progress through the ingestion pipeline.
Single-attribute, multi-attribute, and opt-out submissions appear on the Files tab. Single-attribute and multi-attribute audiences are also available in Explorer after processing. Opt-out audiences are applied to your Merkury Explorer audiences but do not appear in the Explorer interface.
The following examples show where single-attribute and multi-attribute audiences appear in Merkury Explorer.
The following example shows a single-attribute audience on the Files tab:
The following example shows a multi-attribute audience on the Files tab:
The following example shows a single-attribute audience in Explorer:
The following example shows a multi-attribute audience with custom attributes in Explorer:
Loading single-attribute audiences
A single-attribute audience must be stored in a table with 2 columns – one titled HMID and the other as AUDIENCE_NAME where both columns must be defined as NOT NULL. The Push app must be granted access to the table (and the database and schema where it resides).
The AUDIENCE_NAME parameter and custom-attribute column names must contain between 5 and 100 characters. The names can contain:
- Uppercase letters from A through Z
- Lowercase letters from a through z
- Numbers from 0 through 9
- Underscores (_)
- Hyphens (-)
- Spaces
The following example shows the expected structure of the single-attribute audience table that contains one or more audience name in the table. This table example has two single-attribute audiences.
| HMID | AUDIENCE_NAME |
|---|---|
| example_hmid_1 | Summer_Audience_2026 |
| example_hmid_2 | Summer_Audience_2026 |
| example_hmid_1 | Winter_Audience_2026 |
| example_hmid_2 | Winter_Audience_2026 |
The following is an example query for creating the single-attribute table:
CREATE TABLE AUDIENCE_DB.DATA.AUDIENCE_2026 ( HMID VARCHAR(16777216) NOT NULL, AUDIENCE_NAME VARCHAR(16777216) NOT NULL );
To load a single-attribute audience, replace the placeholders in the following template:
-
<APPLICATION_NAME>: Name of the installed Push application -
<DB.SCHEMA.TABLE>: Fully qualified name of the source table -
<ADVERTISER_ID>: Merkury Explorer advertiser ID -
<AUDIENCE_NAME>: Name assigned to the audience in Merkury Explorer
A fully qualified table name includes the database, schema, and table names separated by periods. For example, AUDIENCE_DB.SINGLE_ATTR_AUDS.AUDIENCE_SUMMER_2026.
Use the exact value single-attribute for the audience-type parameter.
Audience and custom attribute naming requirements
Please also see the Hashed Merkury Identifier (HMID) section of Prepare your data file for restrictions on audience and custom attribute names.
Template
CALL <APPLICATION_NAME>.APP_CODE.PUSH_AUDIENCE(
'<DB.SCHEMA.TABLE>',
'<ADVERTISER_ID>',
'single-attribute',
'<AUDIENCE_NAME>'
);Example
CALL DENTSU_COMPOSABLE_PUSH_APP.APP_CODE.PUSH_AUDIENCE(
'AUDIENCE_DB.SINGLE_ATTR_AUDS.AUDIENCE_2026',
'DENTSU_ADV',
'single-attribute',
'Summer_Audience_2026' -- For example, use 'Winter_Audience_2026' to load another audience from the same table.
);By default, an audience expires one year after it is loaded. To specify a different expiration date, include the optional date parameter in YYYY-MM-DD format.
Template with an expiration date
CALL <APPLICATION_NAME>.APP_CODE.PUSH_AUDIENCE(
'<DB.SCHEMA.TABLE>',
'<ADVERTISER_ID>',
'single-attribute',
'<AUDIENCE_NAME>',
'<EXPIRATION_DATE>'
);Example with an expiration date
CALL DENTSU_COMPOSABLE_PUSH_APP.APP_CODE.PUSH_AUDIENCE(
'AUDIENCE_DB.SINGLE_ATTR_AUDS.AUDIENCE_2026',
'DENTSU_ADV',
'single-attribute',
'Summer_Audience_2026', -- For example, use 'Winter_Audience_2026' to load another audience from the same table.
'2026-12-01'
);Loading a multi-attribute audience
A multi-attribute audience must be stored in a table containing:
- One
HMIDcolumn - One
AUDIENCE_NAMEcolumn - At least one custom-attribute column
- No more than 1,000 custom-attribute columns
Custom-attribute columns can use the NUMBER or VARCHAR data type and contain 0, 1, or NULL. Push must have access to the table and the database and schema containing it.
A multi-attribute audience creates one parent audience with the audience name provided in the procedure and child audiences named after the custom-attribute columns in the source table.
The AUDIENCE_NAME parameter and custom-attribute column names must contain between 5 and 100 characters. The names can contain:
- Uppercase letters from
AthroughZ - Lowercase letters from
athroughz - Numbers from
0through9 - Underscores (
_) - Hyphens (
-) - Spaces
The following example shows the expected structure of a multi-attribute audience table:
| HMID | HIGH_VALUE | RECENT_BUYER | EMAIL_ENGAGED | AUDIENCE_NAME |
|---|---|---|---|---|
example_hmid_1 |
1 | 0 | 1 | Summer_Audience_2026 |
example_hmid_2 |
0 | 1 | NULL |
Summer_Audience_2026 |
This example is illustrative and uses the column structure, data types, and allowed values specified in the source requirements.
The following is an example query for creating the multi-attribute table:
CREATE TABLE AUDIENCE_DB.MULTI_ATTR_AUDS.AUDIENCE_SUMMER_2026 ( HMID VARCHAR(16777216) NOT NULL, HIGH_VALUE NUMBER, RECENT_BUYER NUMBER, EMAIL_ENGAGED NUMBER, AUDIENCE_NAME VARCHAR(16777216) NOT NULL );
To load a multi-attribute audience, replace the placeholders in the following template. Use the exact value multi-attribute for the audience-type parameter.
Template
CALL <APPLICATION_NAME>.APP_CODE.PUSH_AUDIENCE(
'<DB.SCHEMA.TABLE>',
'<ADVERTISER_ID>',
'multi-attribute',
'<AUDIENCE_NAME>'
);Example
CALL DENTSU_COMPOSABLE_PUSH_APP.APP_CODE.PUSH_AUDIENCE(
'AUDIENCE_DB.MULTI_ATTR_AUDS.AUDIENCE_SUMMER_2026',
'DENTSU_ADV',
'multi-attribute',
'Summer_Audience_2026'
);By default, an audience expires one year after it is loaded. To specify a different expiration date, include the optional date parameter in YYYY-MM-DD format.
Template with an expiration date
CALL <APPLICATION_NAME>.APP_CODE.PUSH_AUDIENCE(
'<DB.SCHEMA.TABLE>',
'<ADVERTISER_ID>',
'multi-attribute',
'<AUDIENCE_NAME>',
'<EXPIRATION_DATE>'
);Example with an expiration date
CALL DENTSU_COMPOSABLE_PUSH_APP.APP_CODE.PUSH_AUDIENCE(
'AUDIENCE_DB.MULTI_ATTR_AUDS.AUDIENCE_SUMMER_2026',
'DENTSU_ADV',
'multi-attribute',
'Summer_Audience_2026',
'2026-12-01'
);Loading an opt-out audience
An opt-out audience must be stored in a table containing one column named HMID. Push must have access to the table and the database and schema containing it.
To load an opt-out audience, replace the placeholders in the following template. Use the exact value opt-out for the audience-type parameter.
Template
CALL <APPLICATION_NAME>.APP_CODE.PUSH_AUDIENCE(
'<DB.SCHEMA.TABLE>',
'<ADVERTISER_ID>',
'opt-out'
);Example
CALL DENTSU_COMPOSABLE_PUSH_APP.APP_CODE.PUSH_AUDIENCE(
'AUDIENCE_DB.OPT_OUT_AUDS.AUDIENCE_EXCLUDE_SUMMER_2026',
'DENTSU_ADV',
'opt-out'
);Restoring opted-out identifiers
You cannot restore opted-out identifiers through Push. If identifiers must be restored, submit a dentsu.Composable support request.
Check audience ingestion status
When PUSH_AUDIENCE completes successfully, the procedure returns a JSON response containing information about the audience-ingestion request, including the audience ID and a query for checking its status.
Example response
{
"status": "success",
"message": "Audience ingestion has been triggered successfully",
"data": {
"audience_id": "aud_260501_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"audience_code": 12345,
"audience_version": 3,
"adv_id": "ADV123",
"audience_name": "Summer_Audience_2026",
"requestor": "user@company.com",
"status_code": 200,
"audience_type": "single-attribute"
},
"next_steps": {
"check_status_query": "CALL DENTSU_COMPOSABLE_PUSH_APP.APP_CODE.CHECK_AUDIENCE_STATUS('aud_260501_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6', 'ADV123');"
}
}The response includes the following key fields:
-
audience_id: Unique identifier for the audience-ingestion request. Use this value to check the ingestion status. -
adv_id: Field containing the Merkury Explorer advertiser ID. -
check_status_query: Preformatted SQL query containing the audience ID and advertiser ID returned for the request.
To check the audience status, copy the SQL statement from check_status_query, paste it into your Snowflake SQL editor, and run it.
Using the preceding response, run:
CALL DENTSU_COMPOSABLE_PUSH_APP.APP_CODE.CHECK_AUDIENCE_STATUS(
'aud_260501_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
'ADV123'
);The status query is preformatted with the applicable audience ID and advertiser ID, so you can run it without modification.
Alternatively, build the query using the audience_id and adv_id returned in the response:
CALL DENTSU_COMPOSABLE_PUSH_APP.APP_CODE.CHECK_AUDIENCE_STATUS(
'<AUDIENCE_ID>',
'<ADV_ID>'
);Replace <AUDIENCE_ID> with the returned audience-ingestion ID and <ADV_ID> with the returned advertiser ID. The adv_id property in the JSON response represents the advertiser ID referenced elsewhere in this documentation.