Install Tealium Audience Discovery for Snowflake

This guide explains how to install Tealium Audience Discovery for Snowflake from the Snowflake Marketplace and configure the roles and permissions required to use it.

Requirements

• A Snowflake account owner or administrator role.
• Access to the Snowflake databases and schemas you want to use for audience creation.

Install the app

Install Tealium Audience Discovery for Snowflake from the Snowflake Marketplace. After installation, run the SQL in the following section to set up and launch the app.

Set up the service

Run the following SQL after installation to configure and start the app. Replace <SOURCE_DATABASE> with the database containing your data. If you chose a different application name during installation, replace TEALIUM_AUDIENCE_DISCOVERY_APP accordingly.

1. Create an exclusive compute pool for the app.

   CPU_X64_XS (2 vCPU, 8 GB) is suitable for most workloads. Use CPU_X64_S (4 vCPU, 16 GB) for large audiences or heavy concurrent use.

   CREATE COMPUTE POOL IF NOT EXISTS TEALIUM_AUDIENCE_DISCOVERY_POOL
     FOR APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP
     MIN_NODES = 1
     MAX_NODES = 1
     INSTANCE_FAMILY = CPU_X64_XS;
   

2. Create a warehouse, or use an existing one.

   CREATE WAREHOUSE IF NOT EXISTS TEALIUM_AUDIENCE_DISCOVERY_WH
     WAREHOUSE_SIZE = 'X-SMALL';
   

3. Grant the app access to the compute pool and warehouse.

   GRANT USAGE ON COMPUTE POOL TEALIUM_AUDIENCE_DISCOVERY_POOL TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   GRANT USAGE ON WAREHOUSE TEALIUM_AUDIENCE_DISCOVERY_WH TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   

4. Grant the app read access to your source data.

   GRANT USAGE ON DATABASE <SOURCE_DATABASE> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   GRANT USAGE ON ALL SCHEMAS IN DATABASE <SOURCE_DATABASE> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   GRANT SELECT ON ALL TABLES IN DATABASE <SOURCE_DATABASE> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   GRANT SELECT ON ALL VIEWS IN DATABASE <SOURCE_DATABASE> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   

5. Start the service.

   CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.create_app_service(
       'TEALIUM_AUDIENCE_DISCOVERY_POOL',
       'TEALIUM_AUDIENCE_DISCOVERY_WH'
   );
   

6. Check the service status. Wait until the status returns READY before continuing.

   CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.check_service_status();
   

7. Get the application URL.

   CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.get_app_url();
   

Open the app

1. Open the URL returned in step 7, or go to Snowsight > Data Products > Apps > TEALIUM_AUDIENCE_DISCOVERY_APP > Endpoints.
2. Click audience-discovery-endpoint to open the web interface.
3. Use the Data Explorer to browse available tables.

Additional setup

Grant access to additional databases

The app needs read access to every database you want to build audiences from. Repeat the following for each additional database.

GRANT USAGE ON DATABASE <SOURCE_DATABASE> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
GRANT USAGE ON ALL SCHEMAS IN DATABASE <SOURCE_DATABASE> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
GRANT SELECT ON ALL TABLES IN DATABASE <SOURCE_DATABASE> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
GRANT SELECT ON ALL VIEWS IN DATABASE <SOURCE_DATABASE> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;

The app can only read source data. It never modifies your tables.

Enable Cortex AI (optional)

The app includes a Cortex mode that lets users describe audience segmentation rules in natural language. Cortex Analyst generates the SQL query automatically using your Snowflake semantic views.

This feature is disabled if you have not assigned a semantic view to the application.

1. Grant the Cortex AI database role.

   GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   

2. Grant access to your semantic views.

   GRANT USAGE ON DATABASE <SEMANTIC_VIEW_DB> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   GRANT USAGE ON SCHEMA <SEMANTIC_VIEW_DB>.<SEMANTIC_VIEW_SCHEMA> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   GRANT SELECT ON ALL VIEWS IN SCHEMA <SEMANTIC_VIEW_DB>.<SEMANTIC_VIEW_SCHEMA> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   GRANT SELECT ON SEMANTIC VIEW <SEMANTIC_VIEW_NAME> TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   

3. (Optional) Configure available large language models (LLMs). Grant app_admin to your role to manage the model list.

   GRANT APPLICATION ROLE TEALIUM_AUDIENCE_DISCOVERY_APP.app_admin TO ROLE <ADMIN_ROLE>;
   

   View the default models seeded during installation.

   SELECT * FROM TEALIUM_AUDIENCE_DISCOVERY_APP.AUDIENCE_DISCOVERY_SCHEMA.AVAILABLE_LLMS;
   

   Replace the list with your own models.

   DELETE FROM TEALIUM_AUDIENCE_DISCOVERY_APP.AUDIENCE_DISCOVERY_SCHEMA.AVAILABLE_LLMS;
   INSERT INTO TEALIUM_AUDIENCE_DISCOVERY_APP.AUDIENCE_DISCOVERY_SCHEMA.AVAILABLE_LLMS (MODEL_NAME)
   VALUES
       ('mistral-large2'),
       ('llama3.1-70b'),
       ('llama3.1-405b'),
       ('snowflake-arctic'),
       ('claude-3-5-sonnet');
   

   Only list models enabled in your Snowflake region. Test a model with SELECT AI_COMPLETE(model => '<model_name>', prompt => 'Hello');

Enable webhook delivery (optional)

The app can send audience data to external HTTP endpoints. This feature is disabled by default and requires administrator setup.

This feature is disabled if you have not configured a network rule and external access integration.

1. Create a network rule for your webhook host.

   CREATE OR REPLACE NETWORK RULE webhook_egress_rule
     TYPE = HOST_PORT
     MODE = EGRESS
     VALUE_LIST = ('your-webhook-host.example.com:443');
   

2. Create an external access integration.

   CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION webhook_external_access
     ALLOWED_NETWORK_RULES = (webhook_egress_rule)
     ENABLED = TRUE;
   

3. Grant the integration to the application.

   GRANT USAGE ON INTEGRATION webhook_external_access TO APPLICATION TEALIUM_AUDIENCE_DISCOVERY_APP;
   

4. Enable the feature. This automatically attaches the external access integration to the running service.

   -- Uses the default integration name WEBHOOK_EXTERNAL_ACCESS
   CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.set_webhook_enabled(TRUE);
   
   -- Or specify a custom integration name
   CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.set_webhook_enabled(TRUE, 'MY_CUSTOM_INTEGRATION');
   

   To disable webhook delivery later:

   CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.set_webhook_enabled(FALSE);
   

To send audience data, open an audience, click the three-dot menu, and select Send to Webhook. Enter the HTTPS webhook URL, optionally provide Basic Auth credentials, and click Send. Data is delivered as JSON in batches of 1,000 rows by default, up to 1,000,000 rows.

All deliveries are logged in AUDIENCE_DISCOVERY_SCHEMA.WEBHOOK_LOG.

SELECT * FROM TEALIUM_AUDIENCE_DISCOVERY_APP.AUDIENCE_DISCOVERY_SCHEMA.WEBHOOK_LOG
ORDER BY STARTED_AT DESC;

Set up external access for the Tealium connector

Each audience includes a USERS_EXTERNAL secure view for external consumers such as the Tealium Snowflake connector. The view automatically returns zero rows when an audience is deactivated and resumes when re-activated.

1. Create a dedicated role for the external service account.

   CREATE ROLE IF NOT EXISTS TEALIUM_AUDIENCE_DISCOVERY_EXTERNAL_ROLE;
   

2. Grant the app_external application role. This role provides access to secure views only, not tables.

   GRANT APPLICATION ROLE TEALIUM_AUDIENCE_DISCOVERY_APP.app_external TO ROLE TEALIUM_AUDIENCE_DISCOVERY_EXTERNAL_ROLE;
   

3. Grant warehouse usage for query execution.

   GRANT USAGE ON WAREHOUSE TEALIUM_AUDIENCE_DISCOVERY_WH TO ROLE TEALIUM_AUDIENCE_DISCOVERY_EXTERNAL_ROLE;
   

4. Grant the role to the Tealium service account user.

   GRANT ROLE TEALIUM_AUDIENCE_DISCOVERY_EXTERNAL_ROLE TO USER <TEALIUM_SERVICE_USER>;
   

The Tealium connector queries audiences using:

SELECT * FROM TEALIUM_AUDIENCE_DISCOVERY_APP.<AUDIENCE_SCHEMA>.USERS_EXTERNAL;

To verify role restrictions, disable secondary roles before testing.

USE SECONDARY ROLES NONE;
USE ROLE TEALIUM_AUDIENCE_DISCOVERY_EXTERNAL_ROLE;

-- Should return data for an active audience
SELECT * FROM TEALIUM_AUDIENCE_DISCOVERY_APP.AUD_XXXXXXXXXXXXXXXX.USERS_EXTERNAL;

-- Should fail with insufficient privileges
SELECT * FROM TEALIUM_AUDIENCE_DISCOVERY_APP.AUD_XXXXXXXXXXXXXXXX.USERS;

-- Re-enable secondary roles when done
USE SECONDARY ROLES ALL;
USE ROLE SYSADMIN;

Manage the service

Use the following stored procedures to manage the app service lifecycle. To create the service for the first time, see Set up the service. To recreate it after dropping, run the same SQL.

Stop the service

Suspends the service without dropping it. Containers stop but the service definition is preserved.

CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.stop_app_service();

Resume the service

Resumes a previously suspended service.

CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.resume_app_service();

Refresh the service

Re-applies the service specification to pick up a new container image after an application upgrade.

CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.refresh_app_service('TEALIUM_AUDIENCE_DISCOVERY_WH');

Drop the service

Permanently removes the service. Use create_app_service() to recreate it.

CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.drop_app_service();

Check service status

CALL TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.check_service_status();

View service logs

CALL SYSTEM$GET_SERVICE_LOGS('TEALIUM_AUDIENCE_DISCOVERY_APP.main_schema.audience_discovery_service', 0, 'audience-discovery-app', 100);

Troubleshoot

Security and data handling

Data residency

All data remains within your Snowflake account. The app:

• Does not make external network requests by default. The only built-in HTTP call is to the Snowflake Cortex Analyst REST API on the same Snowflake infrastructure.
• Does not include telemetry, analytics, or automatic data egress.
• Does not use cookies.
• Does not store secrets in plain text. Authentication is handled through Snowflake’s OAuth token mechanism in Snowpark Container Services (SPCS).
• Uses self-hosted fonts bundled into the container image at build time. No runtime requests are made to external servers.

The optional webhook delivery feature, when explicitly enabled by an administrator with a network rule and external access integration, allows users to send audience data to a specified HTTPS endpoint. No outbound requests occur unless the administrator enables this feature and a user initiates a send.

Authentication

All access requires Snowflake authentication. The web UI is served through a Snowflake ingress endpoint. There are no public unauthenticated endpoints.

Objects created

The app creates the following objects in your Snowflake account.

Schemas:

• MAIN_SCHEMA — infrastructure
• AUDIENCE_DISCOVERY_SCHEMA — metadata
• TEALIUM_EXTERNAL_ACCESS — secure views for external access
• One AUD_* schema per audience

Tables:

• AUDIENCES — audience metadata
• AVAILABLE_LLMS — LLM configuration
• WEBHOOK_CONFIG — feature flag
• WEBHOOK_LOG — webhook delivery audit log
• One USERS table per audience

Views:

• One USERS_EXTERNAL secure view per audience. Returns zero rows when the audience is deactivated and resumes when re-activated.

Procedures: Service management and owner-privilege DDL executors for audience lifecycle.

Tasks: One REFRESH_TASK per active audience for scheduled refreshes.

Service: audience_discovery_service running the containerized application.

Data retention

Audience metadata including name, description, configuration, user counts, and timestamps is stored in the AUDIENCES table indefinitely. Each audience version is preserved as a separate row for historical tracking. Deleting an audience removes all associated data, including metadata rows and the audience schema.