Skip to content

SQL Segment Extensions

You can generate a Segment Extension using Snowflake SQL queries of Snowflake data. SQL can help you unlock new segment use cases because it offers the flexibility to describe the relationships between data in ways that aren’t achievable through other segmentation features.

Like standard Segment Extensions, you can query events from up to the past two years (730 days) in your SQL Segment Extension.

Types of SQL Segment Extensions

There are two types of SQL editors to choose from when creating your SQL Segment Extension: the SQL Editor, and the Incremental SQL Editor.

  • Creating extensions with SQL Editor (full refresh): Each time your segment refreshes, Braze will query all available data to update your segment, which will use more credits than incremental refreshes. Full refresh extensions can automatically regenerate membership hourly, daily, weekly, or monthly, but can’t be refreshed using incremental refresh.
  • Creating extensions with Incremental SQL Editor (incremental refresh): Incremental refresh calculates only the last two days’ worth of data, which is more cost-efficient and uses up fewer credits each time. When you create an incremental refresh SQL segment, you can set it to automatically regenerate membership hourly, daily, weekly, or monthly.

Creating SQL Segment Extensions

To create a full refresh SQL Segment Extension:

  1. Go to Audience > Segment Extensions.
  2. Select Create New Extension and then select Full refresh.



  3. Add a name for your Segment Extension and input your SQL. Refer to the section Writing SQL for requirements and resources.

    SQL editor showing an example SQL Segment Extension.

  4. If desired, select Enable refresh.

    Cycle icon with "Enable refresh" text.

  5. Save your Segment Extension.

The Incremental refresh SQL editor allows user query aggregations to happen on a per date basis for an event within a given time frame. To create an incremental refresh SQL Segment Extension:

  1. Go to Audience > Segment Extensions.
  1. Select Create New Extension and then select Incremental refresh.



  2. Add a name for your Segment Extension and input your SQL. Refer to the section Writing SQL for requirements and resources.

    SQL editor showing an example incremental SQL Segment Extension.

  3. If desired, select Enable refresh.

    Cycle icon with "Enable refresh" text.

  4. Save your Segment Extension.

The AI SQL generator leverages GPT, powered by OpenAI, to recommend SQL for your SQL segment.

AI SQL generator with the prompt "Users that received a notification last month"

To use the AI SQL generator, do the following:

  1. Select AI SQL Generator after creating a SQL segment using either full or incremental refresh.
  2. Type in your prompt and select Generate to translate your prompt into SQL.
  3. Review the generated SQL to make sure it looks correct, and then save your segment.

Example prompts

  • Users who received an email in the last month
  • Users who made less than five purchases in the last year

Tips

  • Familiarize yourself with the available Snowflake data tables. Asking for data that doesn’t exist in these tables may result in ChatGPT making up a fake table.
  • Familiarize yourself with the SQL writing rules for this feature. Not following these rules will cause an error. For example, your SQL code must select the user_id column. Starting your prompt with “users who” can help.
  • You can send up to 20 prompts per minute with the AI SQL Generator.

How is my data used and sent to OpenAI?

In order to generate your SQL, Braze will send your prompts to OpenAI’s API Platform. All queries sent to OpenAI from Braze are anonymized, meaning that OpenAI will not be able to identify from whom the query was sent unless you include uniquely identifiable information in the content you provide. As detailed in OpenAI’s API Platform Commitments, data sent to OpenAI’s API via Braze is not used to train or improve their models and will be deleted after 30 days. Please ensure that you adhere to OpenAI’s policies relevant to you, including the Usage Policy. Braze makes no warranty of any kind with respect to any AI-generated content.

When the extension finishes processing, you can create a segment using your Segment Extension and target this new segment with your campaigns and Canvases.

Designating refresh settings

If you don’t need your extension to refresh on a regular schedule, you can save it without using refresh settings, and Braze will default to generating your Segment Extension based on your user membership at that moment. Use the default behavior if you only want to generate the audience once and then target it with a one-off campaign.

Your segment will always begin processing after the initial save. Whenever your segment refreshes, Braze will re-run the segment and update segment membership to reflect the users in your segment at the time of refresh. This can help your recurring campaigns reach the most relevant users.

Setting up a recurring refresh

To set up a recurring schedule by designating refresh settings, select Enable refresh. The option to designate refresh settings is available for all types of Segment Extensions, including SQL segments, CDI segments, and simple form-based Segment Extensions.

Selecting your refresh settings

Refresh Interval Settings with a weekly refresh frequency, start time of 10 am, and Monday selected as a day.

Within the Refresh Interval Settings panel, you can select the frequency at which this segment extension will refresh: hourly, daily, weekly, or monthly. You’ll also be required to select the specific time (which is in your company’s time zone) the refresh would occur, such as:

  • If you have an email campaign that is sent every Monday at 11 am company time, and you want to ensure your segment is refreshed right before it’s sent, you should choose a refresh schedule of weekly at 10 am on Mondays.
  • If you’d like your segment to refresh every day, select the daily refresh frequency and then choose the time of day to refresh.

Credit consumption and additional costs

Because refreshes re-run your segment’s query, each refresh for SQL segments will consume SQL segment credits, and each refresh for CDI segments will incur a cost within your third-party data warehouse.

Criteria to automatically disable stale extensions

Scheduled refreshes are automatically disabled once a Segment Extension is stale. A Segment Extension is stale if it meets the following criteria:

  • Not used in any active campaigns or Canvases
  • Not used in any segment that is in an active campaign or Canvas
  • Not used in any segment that has analytics tracking turned on
  • Hasn’t been modified in over seven days
  • Hasn’t been added to a campaign or Canvas (including drafts), or segment in over seven days

If the scheduled refresh is disabled for a Segment Extension, that extension will have a notification that says so.

A notification stating that "Scheduled refreshes have been turned off for this extension because it's not used in any active campaigns, Canvases, or segments. The segment extension was disabled February 23, 2025 at 12:00 AM."

When you’re ready to use a stale Segment Extension, review the refresh settings, select the refresh schedule that matches your use case, and then save any modifications.

Writing SQL

Your SQL query should be written using Snowflake syntax. Consult the table reference for a full list of tables and columns available to be queried.

Your SQL must additionally adhere to the following rules:

  • Write a single SQL statement. Do not include any semicolons.
  • Your SQL must select only one column: the user_id column. This means your SQL must contain:
1

SELECT DISTINCT user_id FROM "INSERT TABLE NAME"
  • It isn’t possible to query for users with zero events, which means any query for users that have done an event less than X times would need to follow this workaround:
    1. Write a query to select users who have the event MORE than X times.
    2. When referencing your Segment Extension in your segment, select doesn't include to invert the result.

All incremental refresh queries consist of two parts: a query, and schema details.

  1. In the editor, write a query that selects user_ids from your desired table.
  2. Add schema details by selecting an Operator, Number of times, and Time period from the fields above the editor. The query will check if the sum of the aggregate column meets a certain condition specified by the {{operator}} and {{number of times}} placeholders. This functions similarly to the workflow for creating classic Segment Extensions.

    • Operator: Indicate if the event has happened more than, less than, or equal to a number of occurrences.
    • Number of times: How many times you would like to evaluate the event in relation to the operator.
    • Time period: Number of days from 1 to 730 in which you want to check instances of the event. This time period refers to past days relative to the current day. The following example shows querying for users that performed the event more than 5 times in the past 365 days.
      Fields to select schema details.

In the following example, the resulting segment would contain users that performed a custom event more than 3 times during the last 30 days, after a specified date.

SQL editor showing an example incremental SQL Segment Extension.

Additional rules

Your incremental refresh query must additionally adhere to the following rules:

  • Write a single SQL statement. Do not include any semicolons.
  • Your incremental SQL segment would be able to refer to just one single event. Your dropdowns for date and count are in reference to your chosen event.
  • Your SQL must have the following columns: user_id, $start_date, and an aggregation function (such as COUNT). Any SQL saved without these three fields will result in an error.

Previewing results

Before saving, you can run a preview of your query. Query previews are automatically limited to 100 rows and will timeout after 60 seconds. The user_id column requirement does not apply when running a preview.

For incremental SQL Segment Extensions, the preview will not include the additional criteria from your operator, number of times, and time period fields.

Managing SQL Segment Extensions

On the Segment Extensions page, segments generated using SQL are denoted with next to their name.

Select a SQL Segment Extension to archive the extension, manually refresh the segment membership, or select Messaging Use to view where the extension is being used.

Messaging Use modal showing where the SQL segment is being used.

Refreshing segment membership

To refresh the segment membership of any Segment Extension created using SQL, open the Segment Extension and select Refresh. You can schedule automatic refreshes for any Segment Extension by selecting Enable refresh and configuring the refresh frequency (hourly, daily, weekly, or monthly).

Monitoring your SQL Segments usage

Each Braze workspace has 5 Snowflake credits available per month. If you need more credits, contact your account manager. Credits are used whenever you refresh, or save and refresh, a SQL Segment’s membership. Credits are not used when you run previews within a SQL Segment or save or refresh a classic Segment Extension.

Credit usage is correlated to the run time of your SQL query. The longer the run time is, the more credits a query will cost. Run time can vary depending on the complexity and size of your queries over time. The more complex and frequent queries you run, the larger your resource allocation and the faster your run time becomes.

To save on credits, preview your query to ensure it is correct before saving the SQL Segment Extension.

Your credits will reset to 5 on the first of each month at 12 am UTC. You can monitor your credit usage throughout the month within the credits usage panel. From the Segment Extensions page, select View SQL Credit Usage.

SQL Credit Usage panel in the SQL Segment Extensions page

The following will happen when your credits reach zero:

  • Any SQL Segment Extensions set up to automatically refresh stop refreshing, impacting the membership of these segments and any campaigns or Canvases that target these segments.
  • You can only save new SQL Segment Extensions as drafts for the remainder of the month.

All company users who created a SQL Segment and your company admins will receive a notification email when you have used up 50%, 80%, and 100% of your credits. After your credits reset at the start of the next month, you can create more SQL Segments, and automatic refreshes will resume.

If you want to purchase more SQL Segment credits or additional Segment Extensions, please contact your account manager.

Troubleshooting

Your query may fail for any of the following reasons:

  • Syntax errors in your SQL query
  • SQL does not adhere to the SQL rules
  • Processing timeout (after 20 minutes)
Github   Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!