How to Use Query Builder — Thread the Needle with Braze

In Braze's annual Customer Engagement Review, a key theme is 'the full potential of data is more promising than ever.' They shared that top-performing brands are leveraging real-time data to arm the company (and marketers) with meaningful insights about their customers to continuously optimize their experiences. Data is the foundation of modern marketing, so it’s critical for marketing teams to have access to robust insights for segmentation and analysis. With Query Builder, marketers can expand Braze's reporting capabilities using SQL and Snowflake data tables.

In this video, Solution Architect, Rachel Moning, breaks down how to use the Query Builder in Braze, including 

  • An Overview of Query Builder
  • How to write a basic query
  • How to edit a query 
  • Query Builder’s Variables (with examples)


Hello, my name is Rachel Moning, and I'm a Solution Architect at Stitch, a marketing consultancy that focuses on helping our clients get the most out of their Braze platform. This video is a part of a series presented by Stitch with helpful tips and tricks on specific aspects of Braze. We're going to be digging into Query Builder, which is a tool that can be used to expand Braze's reporting capabilities using SQL and Snowflake data tables. That being said, a basic understanding of SQL will be helpful here, but Braze does have quite a few templates to get you started and comfortable.

Before we start, a quick note on permissions. In order to access Query Builder, you will need View PII permissions. Okay, let's get into it.

In your desired workspace, you can access Query Builder by hovering over Analytics and selecting Query Builder. Analytics, Query Builder. From here, you'll see a list of your saved queries, and you can also click to see the Query History of when those were last run. Also of note on this screen is the credit count at the top.

Each Braze workspace has five Snowflake credits available per month. A small portion of a Snowflake credit is used whenever you run a query or preview a table, and varies depending on the runtime of the query. However, writing, editing, and saving queries does not consume credits, and credits reset each month.

Now, on to writing the query itself. If you're unfamiliar with SQL or Snowflake data tables, it's a good idea to start with a Braze template to get acclimated to the format. In this case, I'll select Email Delivery Metrics by Day. Use template. Alright, and I'll just review the code to kind of get a feel for it.

There's also comments at the top to help make things a little bit clearer. So this is a pretty long one because it's gathering emails from multiple different campaigns and canvases So we can just kind of scroll through. if you're familiar with SQL, then obviously this will make a lot of sense. But if this is your first time seeing SQL, it'll be a little bit challenging to digest it first.

So we'll just kind of scroll through to the very bottom, and best way to learn too is just by running it and seeing what it outputs and then changing it from there. So I'm going to go ahead and click 'Run Query'. And it'll take a couple seconds. If it's your first time running a query or it's been a while since you've run a query, it might take a little bit longer.

If your lookback is really large, it could potentially time out. It times out after about six minutes. if that happens, you can either try to run it a couple more times or change your lookback window to say only like in the last 60 days or some other shorter time period and see if it works then.

And if you still have trouble, then you can contact Braze support. Okay, so we have our results now. You can just kind of quickly review down here. And you can also export as a CSV for, more comprehensive analysis.

That pretty much concludes the basics, so let's go a bit deeper. So you'll notice when we clicked into the editor from the template, there was also a list on the right hand side of available data tables with the option to copy the table name directly into the editor, preview the table contents, or see the table details.

So here's our available data tables, the option to copy the name into the editor, to preview the table, or see the details. So you can just kind of see a couple options there. And this also helps with formatting if you're not sure how things need to be formatted. So I can also just kind of show a quick example.

If we were to edit this query and say I wanted to add data from this, let's see, I'll actually find an email specific table, or just campaigns in general. I could do users. So say I wanted to include some data from there. I can just easily click the copy button and wherever your cursor is, it will drop in the name of that table.

you can also preview the table, as I mentioned before, essentially it just shows these fields with some example values and it populates down in your results tab as well. These tables are the same tables used for segment extensions and are essentially the same as those shipped to Snowflake. These are just in the Braze UI, and they allow for ease of use. You might recognize some of the values from Segment Builder, while the majority are more technical, device related, or campaign metadata.

Another cool feature within Query Builder are variables. Variables allow you to use predefined variable types in SQL to reference values without needing to manually copy the value. For example, instead of manually copying a campaign's ID to the SQL editor, you can use a variable to populate a dropdown on the right to directly set.

Select a campaign from the list of campaigns built in the workspace. Variables help save time that would normally be spent copy, pasting, prevent user error and increase usability of queries. Variables are created using one of the supported types, followed by a label to show in the right hand UI, surrounded by braces.

So, I'll just drop a couple examples in here, with the little list I have pre copied here.

So, once I put that formatting in there, the curly braces. So these are the examples of types, campaigns, workspace, analytics, you notice that it populated this additional tab on the right hand side. So before we just saw available data tables and query history and now we see variables with some selected drop downs.

So I have, a couple examples here as far as campaigns, workspaces, segments and tags. And you'll notice clicking those actually shows formatted campaigns in the workspace. And you can collect multiple, as well as segments, tags, and workspace options.

additional supported types include date range, campaigns, canvases, catalogs, segments, and tags to name a few. I demoed a lot of those. Furthermore, you can use variable metadata to configure how the variable looks in the UI. If it's required or not, a placeholder, description, etc. This allows you to create your own robust version of a query template that is reusable and user-friendly.

This was only a scratch on the surface of Query Builder and it's powerful capabilities. For full definitions and schemas of the data tables, check out Braze's and Snowflake's documentation. And the next time you need a report, you can't quite pull from a segment or engagement report, and you don't want to submit a full request to your analytics team, head to Query Builder to pull the data yourself.

Thanks for tuning in. 

You might also like...