Composable Audiences (Early Access)

With mParticle’s Composable Audiences feature, you can create dynamic user segments using data stored directly in your data warehouse. This approach enables you to leverage rich, custom attributes and events that are maintained in your own systems without needing to copy data.

By querying your warehouse directly, you can ensure that audiences are built on the most up-to-date and complete picture of your users, all while eliminating data duplication and minimizing operational overhead.

Creating a composable audience happens in two stages:

1. You connect mParticle to your warehouse and identify what data to use.

   • This includes configuring a connection and one or more data models that specify what data to ingest and how to interpret it.

2. You create an audience based on your data models.

   • These audiences can then be forwarded to downstream partners for activation across paid media, CRM platforms, and more, just like traditional mParticle audiences.

How is data from your warehouse processed?

When a composable audience initializes, mParticle translates your audience definition (the criteria that determine which users should be included in the audience) into a SQL query. This query is then executed directly within your data warehouse using your warehouse’s compute resources.

The SQL query returns a list of users and (optional) attributes that make up the audience at that particular point in time. This data is stored in a temporary table in your data warehouse that is provisioned for internal processing only. These datasets are not part of your production tables and are only used by mParticle to track audience membership over time. These additional datasets are automatically managed and cleaned up by mParticle.

mParticle pulls the users and any optional attribute data from your warehouse before forwarding them to your connected downstream integration.

When you create a composable audience, you specify the cadence at which it refreshes. Note that composable audiences can’t be refreshed in real-time.

Composable Audiences operates independently of mParticle’s identity resolution framework (IDSync). No user profile enrichment or merging takes place. Audience membership is based solely on the logic provided in the SQL query and the structure of the source data. This makes the feature highly transparent and deterministic, giving you full control over how your audiences are built and updated. It also means that the records in your data warehouse must include some form of user identifier (like a user ID or customer ID) that can be used when determining audience membership.

What data is stored in mParticle?

mParticle only stores data about your warehouse that’s needed to create and activate composable audiences, including:

• Information needed to connect with, and authenticate to, your warehouse provider.
• Metadata about your warehouse database and tables, like column names.
• If explicitly enabled, mParticle caches up to 1000 of the most frequent values from each column in your table for up to 7 days to power the autocomplete feature within the audience builder. You must enable autocomplete for each column included in your data model.
• A future release of Composable Audiences will allow you to create “hybrid composable audiences” in which composable audience membership can be optionally noted on user profiles in Customer 360 or the User Activity View.

No other data is stored in mParticle beyond these items.

How are your user profiles modified?

Composable Audiences does not modify your user profiles in any way.

A future release will add the ability to optionally have composable audience membership reflected on user profiles.

How are composable audiences refreshed?

To improve performance, mParticle only tracks changes in audience membership (specifically, the users who have been added to or removed from the audience) rather than recomputing the full list each time. The first time the audience is executed, the entire set of qualifying users is returned. For subsequent runs, mParticle compares the new audience snapshot with the previous one to determine which users have been added or dropped.

This “diff-ing” logic happens entirely within the data warehouse environment. Two snapshots of the audience (previous and current) are compared using SQL, and only the incremental changes are passed back into mParticle for forwarding to downstream integrations. This approach ensures both scalability and efficiency in audience refresh cycles.

Are composable audiences compatible with native mParticle Audiences?

While support for this functionality is planned for a future release, you can’t currently clone audiences comprising data stored in the mParticle CDP from a composable audience, nor can you reference audiences built with mParticle data from a composable audience using the isMemberOf() function (or vice versa).

Setup guide

This guide walks you through connecting your data warehouse, creating data models, and building your first composable audience.

1. Connect to your data warehouse

1. In the mParticle UI, navigate to Data Platform > Setup > Inputs, and open the Feeds tab.
2. Select either Google BigQuery or Snowflake — currently, these are the only supported warehouse providers.
3. Click the + button to add a new input.

4. In the “How would you like to connect your Data Warehouse?” modal, select Use data directly from your Data Warehouse.

   • This option allows you to query your warehouse directly and use that data to power audience segmentation.

Connecting to Google BigQuery

Step 1: Create a new service account for mParticle in Google Cloud Console

1. Go to the Google Cloud Console IAM & Admin > Service Accounts page.
2. Click Create Service Account.
3. Enter a name for the service account. For example, “mparticle-warehouse-connectivity”.
4. Add a description. For example, “Service account for mParticle data warehouse connectivity”.

5. Click Create and Continue.

   

Step 2: Grant BigQuery permissions to the service account

1. In the Grant this service account access to project section, click Select a role.
2. Search for and select BigQuery Data Editor.
3. Click Continue.

4. Click Done to create the service account.

   

Step 3: Create and download a service account key

1. Find and select your newly created service account in the list.
2. Go to the Keys tab.
3. Click Add Key > Create new key.
4. Select JSON as the key type.
5. Click Create.
6. The JSON key file will automatically download to your computer.

7. Keep this file secure - you’ll need to upload it in the form on the left.

   

Step 4: Grant access to the dataset in BigQuery

1. Go to the BigQuery Console.
2. Navigate to your dataset.
3. Click on the Share button (three dots menu) next to your dataset.
4. Click Share dataset.
5. In the Add principals section, enter your service account email address.
6. Assign the BigQuery Data Editor role.
7. Click Add.

8. Click Done.

   

Step 5: Create a BigQuery Connection in mParticle

1. Provide a Connection Name.
2. Upload the JSON service account key file you downloaded.
3. Enter your BigQuery project ID.
4. Enter your dataset name.
5. Click Create Connection to complete the setup.

Connecting to Snowflake

Step 1: Configure Snowflake

1. An administrator in your Snowflake account will need to create a service user that mParticle can use when connecting to, and retrieving data from, your database. Make note of the username and role when creating your service user, as these are referenced in the steps below. Learn more about service users in Snowflake’s documentation.

2. Provide a Storage Integration Name, and use the Username and Role for the mParticle service user you created.

    CREATE OR REPLACE STORAGE INTEGRATION mp_[your_name]
        WITH TYPE = EXTERNAL_STAGE
        STORAGE_PROVIDER = 'S3'
        ENABLED = TRUE
        STORAGE_AWS_ROLE_ARN = "arn:aws:iam::[your_value]"
        STORAGE_AWS_OBJECT_ACL = "bucket-owner-full-control"
        STORAGE_ALLOWED_LOCATIONS = ("s3://[your_value]");`
   
    GRANT USAGE ON INTEGRATION your_name TO ROLE [your_role];

3. Create a schema named “MPARTICLE” in your Snowflake database and grant the service user read/write access. This is used to track audience membership over time and is automatically managed by mParticle.

   CREATE SCHEMA IF NOT EXISTS "MPARTICLE";
   GRANT USAGE ON SCHEMA "MPARTICLE" TO ROLE [your role];
   GRANT CREATE TABLE ON SCHEMA "MPARTICLE" TO ROLE [your role];
   GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA "MPARTICLE" TO ROLE [your role];
   GRANT SELECT, INSERT, UPDATE, DELETE ON FUTURE TABLES IN SCHEMA "MPARTICLE" TO ROLE [your role]

4. Grant the role access to any schemas and tables in your database that will be used build audiences.

   GRANT USAGE ON SCHEMA [your database]."[your schema]" TO ROLE [your role]; 
   
   CREATE OR REPLACE STORAGE INTEGRATION mp_[your_name]
       WITH TYPE = EXTERNAL_STAGE
       STORAGE_PROVIDER = 'S3'
       ENABLED = TRUE
       STORAGE_AWS_ROLE_ARN = "arn:aws:iam::[your_value]"
       STORAGE_AWS_OBJECT_ACL = "bucket-owner-full-control"
       STORAGE_ALLOWED_LOCATIONS = ("s3://[your_value]");

Step 2: Create a Snowflake Connection in mParticle

1. Provide a Connection Name, Account Identifier, Region, Warehouse, and Database in the Connection UI.
2. Once complete, click Create Connection.

2. Create a data model

Your data model specifies the exact data from your warehouse that you’ll create your audiences from. To create a data model, select one of the following Model Types, and follow the specific instructions for that type.

• User data models

  • User Data models define the primary dataset (users or customers) that audiences are built from. When creating a composable audience, start by creating a user data model first that you can later supplement with additional event or behavioral data.

• Event data models

  • Event Data models are used to pull timestamped actions (like logins, purchases, or other conversions) that you can use to enrich your user data by creating a relationship between your user data and event data models.

• General data models

  • General models can be used to enrich audiences with other data (e.g., subscriptions, device types).

Create a user data model

User data models define the core user dataset that Composable Audiences use for segmentation, so you must create a user data model in order to create a composable audience. Like all data models, they’re built from a SQL query that selects user records and attributes from your warehouse, with a required primary ID column to uniquely identify each user. This model forms the base for all audiences and can be linked to other models, like events or subscriptions, for richer targeting.

1. Write your SQL query

Enter the SQL that will be executed against your warehouse. Because data models are defined using SQL, you can use features like joins, filters, grouping, and case statements to target the exact data you want to build your audiences with. This determines which fields and records are made available for targeting.

2. Enter your model details

Name your model for easy reference, and choose a primary ID column (e.g., user_id, customer_id) to identify users in the data.

3. Map columns (optional)

Creating mappings is an optional step that helps you control how your warehouse data is interpreted and used within mParticle and by downstream partners. For example, you can specify whether a column should be treated as a user attribute or event attribute, and assign a more readable display name for use in the audience builder. This makes your data easier to work with, especially for team members who aren’t familiar with the raw schema used in your warehouse.

For each column returned by your query, review the data type mParticle detects and update it if you want mParticle to interpret it a different way.

• Choose the corresponding field name (user attribute or user identifier) for how mParticle should interpret the column.
• Assign a display name if you want the column to have a more marketer-friendly name in the audience builder.

4. Define relationships (optional)

Creating relationships between data model types helps you build more advanced audiences by combining different kinds of data. For example, linking a user data model with event data lets you target users who meet specific profile criteria and have performed certain actions. This also keeps your data models modular, making them easier to reuse across different audience definitions.

Create an event data model

Event Data Models capture timestamped user actions (like logins, purchases, or conversions) that can be used to refine or enrich your audience definitions. These models pull event-level data from your warehouse and can be linked to user data models through a shared user ID. These relationships allow you to build audiences based on specific behaviors or activity patterns over time.

To create an event data model:

1. Write your SQL query

Write the SQL query that selects the event data you want to use for audience segmentation.

• Your query should return timestamped actions (e.g., purchases, app logins, conversions) associated with user identifiers.
• You can include joins, filters, and calculated fields to shape the dataset as needed.

2. Enter your model details

After writing your query, give the model a clear name so it’s easy to reference when building audiences.

• Choose a primary ID column—this should be a unique identifier for the event (EVENT_ID, for example) and must be of type string or number.
• Select a timestamp column that represents when the event occurred. This is required for the model to function as event-based.
• You should also include a user identifier (like USER_ID) to denote who performed each event. This ID is used when relating your event data model with a user data model.

3. Columns (optional)

Review the columns returned by your query and update the detected data types if needed.

Create a General Data Model

General data models are a flexible, catch-all option for data that doesn’t neatly fit into user or event categories (like subscriptions, device types, or other contextual attributes). Like other models, general data models are defined using SQL and can be linked to user models to enrich audience criteria.

To create a General Data Model in the mParticle UI, follow these steps:

1. Write your SQL query

Write the SQL query that selects the dataset you want to use to enrich audience segmentation.

• This can include contextual data such as device types, subscription plans, or any other non-user, non-event attributes.
• Use SQL features like joins and filters to shape the data as needed.
• Make sure your query includes a column that can be used to join this data with a User Data Model.

2. Enter your model details

After defining your query, name the model for easy identification.

• Choose a primary ID column that corresponds to the user identifier you’ll use to link this model to a User Data Model.
• The primary ID should be unique per record and of type string or number.

3. Create an audience

Once you’ve defined your data models, you’re ready to create an audience. You’ll choose the data model to base your audience on, set criteria for segmentation, and schedule regular audience refreshes to ensure your segments stay current. After your audience is created, you can activate it across your marketing platforms and monitor its performance.

To create your audience:

1. Navigate to Segmentation > Audiences and click + New Audience.
2. Select Choose from data model from the available options.
3. Use the dropdown menu to select the data model you want to base your audience on.
4. Click Next.
5. Enter a name for the audience and select a refresh cadence.

6. Define audience criteria based on the imported fields from your model.

   • The audience builder displays a live preview of your audience size based on the selected criteria, helping you validate your logic before activation. A future release will include additional insights to support audience validation.

Activating and Monitoring Your Audience

Once your audience is created, you can:

• Activate your audience across downstream advertising platforms such as Google Ads, Facebook, or TikTok.
• Monitor audience size and delivery logs to confirm data quality and validate your targeting criteria.

Key differences between Composable and Native Audiences

• Audience sizes shown in the UI are actual sizes (not estimates) ensuring you always have an accurate picture of your segment.
• The audience builder UI for composable audiences differs slightly from the native mParticle audience builder. For example, composable audiences have clearer logical groupings and support drag-and-drop to rearrange segmentation clauses.
• Composable audiences are clearly labeled as such on the Audiences landing page.

FAQ

Can I use composable audiences for real time use cases?

No, composable audiences run on a scheduled refresh cadence. They are not designed for real-time updates. You define the refresh schedule when creating the audience.

Does mParticle ingest all audience members every time it runs?

No. The first time your audience runs, mParticle ingests the full list of qualifying users. On subsequent runs, only users who have been added or removed are ingested.

Does composable audience data update my user profiles?

No. Composable Audiences does not modify user profiles or interact with identity resolution (IDSync). A future release will allow you to opt in to reflecting audience membership on profiles.

Can I clone or convert a native mParticle audience into a composable audience?

No. Native audiences (audiences built using data stored in mParticle) and composable audiences are separate features and cannot be cloned across types.

What happens if I change my SQL query in a data model?

If you update a data model’s SQL, any audiences built on that model will reflect the new structure the next time they refresh. You should verify that the model still returns the expected fields and structure.

How accurate is the size shown in the audience builder?

For composable audiences, the audience size preview reflects actual user counts based on your current criteria.

What kinds of data can I include in my models?

You can use user data, timestamped event data (like purchases or logins), and general contextual data (like device types or subscription plans). Each is configured using a SQL query.