Warehouse Audience

Warehouse audience enables you to create segments on MoEngage based on data from your data warehouse without the hassles of copying or moving it to MoEngage. 

Let's say that your brand wishes to offer exclusive discounts to loyal shoppers based on an engagement score that is computed with your proprietary logic. This data is stored and accessible only from your data warehouse. With Warehouse Audience you can access this data from the warehouse directly, build an audience on MoEngage, and send a campaign from MoEngage within a few clicks.

With Warehouse Audience, you get real-time access to warehouse data without any syncing delays, accelerating audience generation and enabling timely engagement. Moreover, with data securely stored within the warehouse, Warehouse Audience ensures data security, simplifying compliance with privacy regulations and industry standards.


Early Access

Warehouse audience for Google BigQuery is currently in early access.

Creating a Warehouse audience

Step 1: Set up your data source

Follow the below steps to grant read access to certain tables in BigQuery to Moengage. Additionally, it covers providing access to BigQuery Jobs API, enabling Moengage to submit jobs and download query results.

These instructions assume you have administrative privileges in the Google Cloud Platform, specifically in the project that hosts the BigQuery dataset and jobs.

Create a Service Account for MoEngage

  1. Open the Google Cloud Console.
  2. Navigate to the project housing the BigQuery dataset and jobs.
  3. Go to the IAM & Admin section and select Service Accounts.
  4. Click Create Service Account.
  5. Provide a name for the service account (e.g., moengage-access).
  6. Set the appropriate role for the service account as BigQuery Job User.
  7. Create the service account.
  8. Navigate to the service account and select the KEYS tab.
  9. Click the ADD KEY dropdown and then select Create new key.
  10. Select JSON as the Key type in the pop-up.
  11. Click CREATE to generate and download the JSON key file.

Share Access to Specific Tables with Moengage

  1. Keep the JSON key file securely and share it with MoEngage through your CSM.
  2. In the BigQuery console, navigate to the dataset containing the tables you want Moengage to access.
  3. Click the SHARING dropdown and then select Permissions.

  4. Add the service account's email address (found in the JSON key file) as a member with the "BigQuery Data Viewer" role.

  5. Click Save to grant access to the dataset.

Grant Access to BigQuery Jobs API

Skip if access is already given in the first step.

  1. In the Google Cloud Console, go to the IAM & Admin section and then select IAM.
  2. Click Grant Access to add a new member.
  3. Enter the service account's email address (found in the JSON key file).
  4. Assign the Role as BigQuery Job User to enable interaction with the BigQuery Jobs API.
  5. Click Save to grant access to the API.
arrow_drop_down Limit Access to Specific Tables (Optional)
  1. Open the JSON key file shared with Moengage.
  2. Locate the private_key_id attribute in the JSON content.
  3. In the BigQuery console, open the dataset with the desired tables.
  4. Select the table(s) you want to restrict access to and click on "Share Table" from the context menu.
  5. Add the service account's email address as a member and restrict the role to "BigQuery Data Viewer" only for these table(s).

By following the above steps, you have successfully granted Moengage read access to specific tables in BigQuery.

Additionally, you have authorized access to the BigQuery Jobs API, allowing them to submit jobs and download query results.

It is essential to review and manage access permissions periodically to maintain data security.

Step 2: Define your audience

  1. Navigate to the Warehouse audience tab under Segment on the MoEngage dashboard.
  2. Here, you will be able to choose the data warehouse (that has been set up from the previous step) from the Source dropdown on the top.
  3. Once a source is chosen, the data warehouse schema - database, tables, and columns, will be populated on the left panel. You can search for any database, table, or column that you would want to use in your query from here.
  4. You can enter your SQL query in the SQL editor on the right. You can perform any operations such as joining multiple tables, sub-queries, aliases, etc. as required. We expect the final query to return a single column of IDs (the unique user identification that is present as an ID in MoEngage).

nandhini scr rec 1.gif



1. The SQL query must return a single column of IDs to produce valid results. If the query returns multiple columns, the segment will not return any users.

2. The SQL query runs on your data warehouse directly. Please note that when utilizing this feature you will incur the costs associated with running the queries from your data warehouse.

3. The SQL query will timeout in 15 min. Please reach out to your CSM to configure this limit.

4. The SQL query should be compatible with your DWH. For eg: If you are using Warehouse Audience on BigQuery, the SQL query must be supported by GoogleSQL

Step 3: Create a custom segment

Once the SQL query is finalized, you can proceed to create a custom segment. Give a name and a description for the segment.

Screenshot 2024-06-26 at 3.37.51 PM.png

Step 4: Use the warehouse custom segment

Custom segments created using warehouse audience are of type SQL - external. They will be listed on the All Segments page.

Actions possible on external custom segments:

  • View - View the details of the custom segment on the segment info page. Here you can:
    • View the SQL query that defines the segment
    • Run the custom segment to update user count - This is when MoEngage connects to your data warehouse, runs the SQL query, and updates the user count.
  • Edit - You can edit the SQL query that was used to define the custom segment
  • Create campaign - You can create a campaign directly from the All Segments page. The target audience section of campaign creation will be populated with the selected custom segment. 
  • External data warehouse segments can be combined with other custom segments as well as user attributes, and behaviors captured in MoEngage. 

Refresh the user count of a Warehouse segment

You can update the user count of an external data warehouse segment in two ways:

  • On campaign run-time - The data warehouse segment that is part of the Target audience of a campaign will auto-refresh at the campaign run-time.
  • Run the custom segment from the segment info page - You can also run the segment manually from the segment info page.

nandhini scr rec2.gif


  • One warehouse segment can be defined on one data warehouse connection. You can combine multiple custom segments pointing to different sources and create a new custom segment.
  • Running analysis - Behaviour, Funnel, etc. will not refresh the user count of a warehouse segment. The target audience containing a warehouse segment will either:
    • Return 0 if the segment has never run
    • Return the last run count of users if the segment has run before



Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?