Cloud Data Ingestion for Snowflake

This page covers everything you need to sync data from Snowflake to Braze using Cloud Data Ingestion (CDI): the resources to create in Snowflake, how to connect the source and create a sync in Braze, the source table for each data type, and Snowflake-specific troubleshooting.

Setup overview

1. In your Snowflake instance, set up the tables or views you want to sync to Braze.
2. Set up a role and warehouse for Braze.
3. Set up a Snowflake user for Braze with one of the supported authentication methods.
4. Create a new Snowflake source in the Braze dashboard, and finish authentication in Snowflake.
5. Create a sync in the Braze dashboard, validate the integration, and start the sync.

tip

The Snowflake quickstart guide provides sample code and walks through the required steps to create an automated pipeline using Snowflake Streams and CDI to sync data to Braze.

Step 1: Set up your source table

The steps in this section create a table with a PAYLOAD column. If you plan to map columns with Visual or write a query with SQL on the Data definition step, you can use an existing table or view instead. Skip the table creation step, and grant Braze read access to the tables or views you want to sync. For a comparison of options, see Choose a data definition option.

You can name the database, schema, and table as you’d like, but the column names should match the definitions in the following tabs. You may also use a view or a materialized view instead of a table.

note

If you use a PAYLOAD column, your source table or view can include columns that aren’t listed in the following tabs (for example, auditing or hashing). Braze reads only the columns described in these tabs; other columns are not used during Cloud Data Ingestion syncs.

Select the tab for the data type you want to sync.

• user attributes
• custom events
• purchase events
• catalog items
• canvas triggers
• user deletions

User attributes, custom events, and purchase events all use the same source table shape. Only the contents of PAYLOAD differ.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC (
     UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
     --at least one of external_id, alias_name and alias_label, email, phone, or braze_id is required
     EXTERNAL_ID VARCHAR(16777216),
     --if using user alias, both alias_name and alias_label are required
     ALIAS_LABEL VARCHAR(16777216),
     ALIAS_NAME VARCHAR(16777216),
     --braze_id can only be used to update existing users created through the Braze SDK
     BRAZE_ID VARCHAR(16777216),
     --If you include both email and phone, email is used as the primary identifier
     EMAIL VARCHAR(16777216),
     PHONE VARCHAR(16777216),
     PAYLOAD VARCHAR(16777216) NOT NULL
);

• UPDATED_AT - The time this row was updated in or added to the table. Braze syncs rows where UPDATED_AT is later than the last synced value. Rows at the exact boundary timestamp may be re-synced if new rows share that same timestamp.
• User identifier columns - Your table may contain one or more user identifier columns. Each row should only contain one identifier (either external_id, the combination of alias_name and alias_label, braze_id, email or phone). A source table may have columns for one, two, three, four, or all five identifier types.
  • EXTERNAL_ID - This identifies the user you want to update. This should match the external_id value used in Braze.
  • ALIAS_NAME and ALIAS_LABEL - These two columns create a user alias object. alias_name should be a unique identifier, and alias_label specifies the type of alias. Users may have multiple aliases with different labels but only one alias_name per alias_label.
  • BRAZE_ID - The Braze user identifier. This is generated by the Braze SDK, and new users cannot be created using a Braze ID through Cloud Data Ingestion. To create new users, specify an external user ID or user alias.
  • EMAIL - The user’s email address. If multiple profiles with the same email address exist, the most recently updated profile is prioritized for updates. If you include both email and phone, email is used as the primary identifier.
  • PHONE - The user’s phone number. If multiple profiles with the same phone number exist, the most recently updated profile is prioritized for updates.
• PAYLOAD - This is a JSON string of the fields you want to sync to the user in Braze.

For attribute syncs, PAYLOAD follows the user attributes object format. You can include nested custom attributes, arrays of objects, and subscription group statuses. For payload examples, see Table setup.

Custom events use the same source table as user attributes. Create the table shown in the User attributes tab, then populate PAYLOAD with an events object.

To sync events, an event name is required. Format the time field as an ISO 8601 string or in yyyy-MM-dd'T'HH:mm:ss:SSSZ format. If the time field is not present, Braze uses the UPDATED_AT column value as the event time. Other fields, including app_id and properties, are optional.

You can sync one event per row.

1
2
3
4
5
6
7
8
9

{
    "app_id" : "your-app-id",
    "name" : "rented_movie",
    "time" : "2013-07-16T19:20:45+01:00",
    "properties": {
        "movie": "The Sad Egg",
        "director": "Alex Smith"
    }
}

Purchase events use the same source table as user attributes. Create the table shown in the User attributes tab, then populate PAYLOAD with a purchases object.

To sync purchase events, product_id, currency, and price are required. Format the optional time field as an ISO 8601 string or in yyyy-MM-dd'T'HH:mm:ss:SSSZ format. If the time field is not present, Braze uses the UPDATED_AT column value as the event time. Other fields, including app_id, quantity, and properties, are optional.

You can sync one purchase event per row.

1
2
3
4
5
6
7
8
9
10
11
12

{
    "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
    "product_id" : "Completed Order",
    "currency" : "USD",
    "price" : 219.98,
    "time" : "2013-07-16T19:20:30+01:00",
    "properties" : {
        "products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99 },
        { "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99 }
        ]
    }
}

Before you create a catalog sync, create the target catalog in Braze. For the full catalog workflow, see Sync and delete catalog data.

1
2
3
4
5
6
7
8
9
10
11

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC (
     UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
     --ID of the catalog item to be created or updated
     ID VARCHAR(16777216) NOT NULL,
     --Catalog fields and values that should be added or updated
     PAYLOAD VARCHAR(16777216) NOT NULL,
     --The catalog item associated with this ID should be deleted
     DELETED BOOLEAN
);

Grant the Braze role access to this table alongside your other source tables:

1

GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC TO ROLE BRAZE_INGESTION_ROLE;

The name of the integration must exactly match the name of the catalog you created in Braze.

Braze recommends creating a view from your catalog data so the source table fully refreshes each time a sync runs. For example, if you have a table of product data (product_catalog_1) with product_id and three additional attributes, you could sync the following view:

1
2
3
4
5
6
7
8
9
10
11
12
13

CREATE VIEW BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS
SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    product_id as id,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'attribute_3',
            attribute_3)
    )as PAYLOAD FROM "product_catalog_1";

Canvas triggers power zero-copy personalization. For the destination Canvas setup and considerations, see Zero-copy personalization.

1
2
3
4
5
6
7
8
9
10
11

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC (
     UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
     --at least one of external_id or alias_name and alias_label is required
     EXTERNAL_ID VARCHAR(16777216),
     --if using user alias, both alias_name and alias_label are required
     ALIAS_LABEL VARCHAR(16777216),
     ALIAS_NAME VARCHAR(16777216),
     PROPERTIES VARCHAR(16777216)
);

Canvas trigger syncs differ from other user data syncs in three ways:

• Only external ID or user alias identifiers are supported. Email and phone numbers are not supported identifiers.
• Only existing Braze users can be synced. New users cannot be created.
• PROPERTIES replaces the PAYLOAD column. This is a JSON string of the fields you want to use as Canvas entry properties for personalization.

Your Canvas triggers table needs the following columns:

• UPDATED_AT - The time this row was updated or added to the table. Braze syncs rows where UPDATED_AT is later than the last synced value. Rows at the exact boundary timestamp may be re-synced if new rows share that same timestamp.
• Either EXTERNAL_ID or ALIAS_NAME and ALIAS_LABEL as the user identifier column. These identify the users for whom you want to trigger Canvas messaging.
  • EXTERNAL_ID - Identifies the user to enter into the Canvas. This should match the external_id value used in Braze.
  • ALIAS_NAME and ALIAS_LABEL - These columns create a user alias object. alias_name should be a unique identifier, and alias_label specifies the alias type. Users may have multiple aliases with different labels, but only one alias_name per alias_label.
• PROPERTIES - A JSON string of fields to make available as personalization properties in your Canvas. This should contain user-specific information.

note

Properties are not required for every row or user. However, properties values must be a valid JSON string. Input an empty {} string if there are no properties for the row.

Grant the Braze role access to this table:

1

GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC TO ROLE BRAZE_INGESTION_ROLE;

To get started, select the Canvas Triggers data type when creating a new sync.

Source tables for user deletes should include one or more user identifier types and an UPDATED_AT timestamp. Payload columns aren’t supported for user delete data.

• UPDATED_AT - The time this row was updated or added to the table. Braze syncs rows where UPDATED_AT is later than the last synced value. Rows at the exact boundary timestamp may be re-synced if new rows share that same timestamp.
• User identifier columns - Each row should only contain one identifier: either external_id, the combination of alias_name and alias_label, or braze_id. A source table may contain columns for one, two, or all three identifier types.
  • EXTERNAL_ID - This identifies the user you want to update. This should match the external_id value used in Braze.
  • ALIAS_NAME and ALIAS_LABEL - These two columns create a user alias object. alias_name should be a unique identifier, and alias_label specifies the type of alias. Users may have multiple aliases with different labels but only one alias_name per alias_label.
  • BRAZE_ID - The Braze user identifier. This is generated by the Braze SDK and new users cannot be created using a Braze ID through Cloud Data Ingestion. To create new users, specify an external user ID or user alias.

important

Do not include a PAYLOAD column in your table for user removal. To prevent accidental, permanent removal of users, a sync fails if a payload column is provided in the source table. Any other columns are allowed but are ignored by Braze.

1
2
3
4
5
6
7
8
9
10

CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.USERS_DELETES (
     UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
     --at least one of external_id, alias_name and alias_label, or braze_id is required
     EXTERNAL_ID VARCHAR(16777216),
     --if using user alias, both alias_name and alias_label are required
     ALIAS_LABEL VARCHAR(16777216),
     ALIAS_NAME VARCHAR(16777216),
     --braze_id can only be used to update existing users created through the Braze SDK
     BRAZE_ID VARCHAR(16777216)
);

On the Create import sync page, set the Data Type to Delete Users so that the proper actions are taken during the integration run. For more information, see Delete users with Cloud Data Ingestion.

warning

Deleting user profiles cannot be undone. The delete action permanently removes users, which may cause discrepancies in your data. For details, see Effects of deleting user profiles.

Step 2: Set up the role and warehouse

Step 2.1: Set up the role and database permissions

1
2
3
4
5

CREATE ROLE BRAZE_INGESTION_ROLE;

GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC TO ROLE BRAZE_INGESTION_ROLE;

Update the names as needed, but the permissions should match the preceding example.

Step 2.2: Set up the warehouse and give access to Braze role

1
2
3

CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;

GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

note

The warehouse needs to have the auto-resume flag on. If not, grant Braze additional OPERATE privileges on the warehouse so Braze can turn it on when the query runs.

Step 2.3: Allow Braze IPs in Snowflake network policy (optional)

Depending on the configuration of your Snowflake account, you may need to allow the following IP addresses in your Snowflake network policy. For more information on enabling this, see the relevant Snowflake documentation on modifying a network policy.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

Step 3: Set up authentication

Braze connects to Snowflake as a Snowflake user that has the role from Step 2. Set up the user with one of the following authentication methods:

Key pair authentication

With key pair authentication, Braze generates an RSA key pair when you save your credentials in the Braze dashboard. You assign the public key to a Snowflake user that Braze connects as.

Set up the user

Create a user for Braze and grant it the role you created:

1
2
3

CREATE USER BRAZE_INGESTION_USER;

GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

note

When connecting different workspaces to the same Snowflake account, you must create a unique user for each Braze workspace where you are creating an integration. Within a workspace, you can reuse the same user across integrations, but integration creation fails if a user on the same Snowflake account is duplicated across workspaces.

Add the public key to the user

Complete this step after you enter your credentials in the Braze dashboard and select Save credentials. Braze generates the key pair and displays the public key. Add the public key to the user you created for Braze:

1

ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';

Assigning the key requires SECURITYADMIN access or higher in Snowflake. For more information, see the Snowflake documentation.

To rotate the keys, go to Data Access Management in Cloud Data Ingestion and select Generate New Key for the account. Then, assign the new public key to the user. If you reuse the same user and role across integrations, you don’t need to add the public key again.

Step 4: Create a new source in the Braze dashboard

In the Braze dashboard, go to Data Settings > Cloud Data Ingestion > Sources, select Add data source, and then select Snowflake.

Step 4.1: Add Snowflake connection information

Choose a name for your source and input your Snowflake credentials and configuration, then proceed to the next step. Select the authentication method you set up in Step 3, and enter its credentials:

• Key pair authentication: Username and Role

Before you continue, confirm the value you enter in Snowflake Account Locator.

For the Snowflake Account Locator field, enter your Snowflake account identifier. Enter only the account identifier value, such as myorganization-myaccount. Do not include https://, .snowflakecomputing.com, or any path.

To find your Snowflake account identifier:

1. In Snowsight, select your account menu.
2. Select View account details.
3. Copy the Account identifier value.
4. If you copy from a Snowflake URL, use only the value before .snowflakecomputing.com.

Step 4.2: Finish authentication in Snowflake

After inputting your credentials and configuration, select Save credentials. For key pair authentication, Braze generates an RSA key pair and displays the public key. Go back to Snowflake and add the public key to the user you created for Braze.

Step 5: Create a new sync in the Braze dashboard

Go to Data Settings > Cloud Data Ingestion > Syncs, and select Create data sync.

Configure sync details and define your data

Enter a name for your sync. Then, select an active source and a sync data type. Next, select Visual or Table and enter your source table, or select SQL to write a custom SQL query. Finally, select Preview and validate.

After validation succeeds, a preview of the data appears. Select Next: Notifications to continue. If validation fails, an error message appears to help troubleshoot the issue.

note

You must successfully validate a sync before progressing to next steps. If you need to close out of the sync creation page, select Save as draft to keep your work in progress.

Add notification preferences

Input contact email(s) for sync error notifications. Braze uses this contact information to send notifications about integration errors, such as unexpected loss of table access.

Contact emails only receive notifications of global or sync-level errors such as missing tables, permissions, and others. They do not receive row-level issues. Global errors indicate critical problems with the connection that prevent syncs from running.

Such problems can include the following:

• Connectivity issues
• Lack of resources
• Permissions issues
• Catalog tier is out of space (catalog syncs only)

Set the schedule

Lastly, configure your sync as non-recurring or recurring.

Non-recurring syncs run only when you select Sync Now in the dashboard or call the Trigger a sync endpoint.

Recurring syncs can run as often as every 5 minutes or as rarely as once per month. By default, the shortest interval you can set in the dashboard is 15 minutes, which helps manage your warehouse compute costs and request volume. To sync as often as every 5 minutes, contact Braze Support or your customer success manager. Braze schedules recurring syncs in UTC.

note

You must successfully validate an integration before it can move from Draft to Active state. If you close the creation page, your integration is saved, and you can revisit the details page to make changes and validate.

Run the sync

When activated, your sync runs on the schedule configured during setup. If you want to run the sync outside its schedule or to fetch the most recent data, select Sync Now. This run does not impact regularly scheduled future syncs. To start a sync automatically when your data updates, call the Trigger a sync endpoint from your pipeline.

Set up additional integrations or users (optional)

You can set up multiple integrations with Braze. When creating additional syncs, you can reuse existing credentials if connecting to the Snowflake account.

If you reuse the same user and role across integrations, you do not need to add the public key again.

Use Snowflake as a connected source

A connected source is a zero-copy alternative to syncing data into Braze. Braze queries your Snowflake instance directly to build CDI segments, without copying the underlying data. For concepts, limitations, and cost implications, see Connected sources.

Step 1: Create a role and grant permissions

Create a role for your connected source to use. This role is used to generate the list of tables available in your CDI Segment Extensions, and to query source tables to create new segments. After the connected source is created, Braze discovers the names and description of all tables available to the user in the source schema.

You may choose to grant access to all tables in a schema, or grant privileges only to specific tables. Whichever tables the Braze role has access to are available to query in the CDI Segment Extension.

The create table permission is required so Braze can create a table with your CDI Segment Extension query results before updating the segment in Braze. Braze creates a temporary table per segment, and the table only persists while Braze is updating the segment.

1
2
3
4
5
6
7
8
9
10
11
12

CREATE ROLE BRAZE_INGESTION_ROLE;

GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT CREATE TABLE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;

-- grant access to all current and future tables or views in the schema
GRANT SELECT ON ALL TABLES IN SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON FUTURE TABLES IN SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;

-- grant access to specific tables or views in the schema
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC TO ROLE BRAZE_INGESTION_ROLE;

The warehouse setup matches Step 2.2, and network policy setup matches Step 2.3. Set up the user that Braze connects as with one of the methods in Step 3: Set up authentication.

Step 2: Create the connected source in Braze

Go to Data Settings > Cloud Data Ingestion > Connected Sources, select Add data source, and then select Snowflake.

In Setup source, enter the following:

• Credentials: Account Locator and the fields for your authentication method. Enter Username and Role.

• Configuration: Warehouse, Database, and Schema

For key pair authentication, if you’re creating new Snowflake credentials, select Save credentials and generate RSA key before testing the connection.

Choose a name for the connected source. This name is used in the list of available sources when you create a new CDI Segment Extension.

Configure a maximum runtime for this source. Braze automatically aborts any queries that exceed the maximum runtime. The maximum runtime allowed is 60 minutes; a lower runtime reduces costs incurred on your Snowflake account. This setting applies to queries run through this source, including syncs and CDI Segment Extensions that use it.

For key pair authentication, take note of the RSA public key in the Test connection step. You need it to complete the integration in Snowflake.

Step 3: Finalize the Snowflake configuration

For key pair authentication, add the public key you noted during the last step to your user in Snowflake, as described in Add the public key to the user. This allows Braze to connect to Snowflake.

After you finish authentication in Snowflake, select Test Connection in Braze, and then select Done. Your connected source is now created and ready to use in CDI Segment Extensions.

You may set up multiple connected sources with Braze, but each source should be configured to connect a different schema. When creating additional connections, you may reuse existing credentials if connecting to the same Snowflake account. If you reuse the same user and role across integrations, you don’t need to add the public key again.

Format a payload from existing columns

If you prefer to store each attribute in its own column internally, you need to convert those columns to a JSON string to populate the sync with Braze. Use this query in Snowflake to format source columns into CDI fields.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

CREATE TABLE "EXAMPLE_USER_DATA"
    (attribute_1 string,
     attribute_2 string,
     attribute_3 number,
     my_user_id string);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    )as PAYLOAD FROM "EXAMPLE_USER_DATA";

To completely remove an attribute rather than setting it to null, use TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

For more optimization guidance, see Cloud Data Ingestion best practices.

Troubleshooting

Test Connection runs slow

Test Connection is running on your data warehouse, so increasing warehouse capacity may improve its speed. Using a serverless SQL instance minimizes warmup time and improves query throughput, but may result in slightly higher integration costs.

Error connecting to Snowflake instance: Incoming request with IP is not allowed to access Snowflake

Try adding the official Braze IPs to your IP allowlist. For more information, see Allow Braze IPs in Snowflake network policy.

Error executing SQL due to customer config: 002003 (42S02): SQL compilation error: does not exist or not authorized

If the table doesn’t exist, create the table. If the table does exist, verify that the user and role have permissions to read from the table.

Could not use schema

If you receive this error, grant access to that schema for the specified user or role.

Could not use role

If you receive this error, allow that user to use the specified role.

User access disabled

If you receive this error, allow that user access to your Snowflake account.

Error connecting to Snowflake instance with current and old key

If you receive this error, make sure the user is using the current public key as displayed in your Braze dashboard. To rotate keys, see Add the public key to the user.

Where to run SQL checks

Run validation checks directly in the Snowflake SQL editor, against the same table or view used by your CDI integration. Go to Projects > Worksheets. For more information, see Snowflake Worksheets.

Related pages

• Table setup for required columns and payload formatting
• Best practices for sync scheduling and data point efficiency
• Sync logs and observability for monitoring sync runs
• FAQ for common questions across all sources