Iterable's Segmentation tool provides a query-building interface that lets you run nuanced searches for users with shared characteristics or behavior.
This article describes the different elements of the query builder and provides an explanation of what they're for.
# In this article
# Getting started
When you build a segmentation query, you start by selecting the type of characteristic you want to search for among your users, and whether you want to segment for All, Any, or None of the attributes you've selected.
You can segment by:
User profile fields, which are attributes related to a user's demographic data, like their location and the type of device(s) they use
Event data that's related to a user's behavior, like their purchase history and engagement with the messages they've received from your brand.
# User profile fields
The User Profile Field option provides a mix of default and custom user data fields that you can select to segment by. To learn more about these fields, see User Profile Fields Used by Iterable.
Next to each field name, you'll see the associated data type.
A field's data type determines which comparators are available for segmentation.
# Event data
The Event option provides a mix of system events and custom events that you can select to segment by.
# Fields
Once you've selected the user characteristic or event you want to search by, you'll select the field that contains the value you're interested in.
In the Segmentation query builder, some user profile and event fields appear under a display name that differs from the data field name used in Iterable's API, exports, and backend. When you make calls to Iterable's API or reference fields in Handlebars, use the actual data field name.
| Display Name in Segmentation Tool | Data Field Name | Description |
|---|---|---|
| Profile Updated Date | profileUpdatedAt | Date when the user's profile was last updated via CSV upload or API call. |
| Brand Affinity™ | itblDS.brandAffinityLabel | User's engagement level score from Brand Affinity™. |
| User ID | userId | Unique identifier assigned to the user in a User ID-based project. |
email | User's email address. | |
| Signup Date | signupDate | Date the user's profile was created in Iterable. |
| Signup Source | signupSource | How the user was created (for example, API or IMPORT). |
Nested fields and custom fields that you create and manage use the same dot
notation in both the Segmentation tool and Iterable's API (for example,
address.city). For a full list of data fields and their meanings, see User Profile Fields Used by Iterable.
# Segmentation guardrails
As you build segmentation queries, Iterable applies certain guardrails to help keep queries safe, reliable, and efficient as your audience data grows. These guardrails are designed to reduce slowness, failed queries, and other issues caused by query patterns that can become resource-intensive at scale.
Depending on the query pattern involved, Iterable may:
- Display guidance on the Segmentation page
- Ask you to narrow the scope of a query
- Require you to simplify criteria or use a different comparator before saving
Guardrails are especially relevant for query patterns such as:
- Broad string searches across high-cardinality fields
- Regex-based searches (Matches Regex and Contains) on fields that are not considered safe for that type of query
- Queries that return very large result sets or combine many resource-intensive conditions
When possible, prefer the simplest comparator that supports your use case. For example, use Starts With or Is One Of instead of Matches Regex or Contains when a simpler comparator will return the same results. Contains is a regex-based comparator and is subject to the same field-cardinality restrictions as Matches Regex.
# Segmenting with campaign labels
When you include the Campaign Label field in a segmentation query, using a
date range is a best practice whenever possible, and it becomes required when
the query would exceed limits without one.
The date range filters campaigns by the date they were launched (the date they were scheduled or activated—not necessarily the date they were sent or delivered).
Using a date range in your query improves performance and helps keep the number of matching campaigns within supported limits. This is especially important in projects with many triggered campaigns or campaigns used in journeys, because those campaigns can remain in a matching status for long periods and contribute to large result sets.
A date range becomes required when the query would exceed either of these limits:
- Each clause that contains the
Campaign Labelfield can return a maximum of 3,000 matching campaigns. - An entire segmentation query that contains any
Campaign Labelcriteria can return a maximum of 20,000 matching campaigns.
If a query exceeds either limit, Iterable prevents you from running or saving it. To continue, define a time period and/or adjust other conditions to narrow the search and bring the number of matching campaigns within these limits.
NOTE
The number of matching campaigns returned for a clause or query includes all blast and triggered campaigns that have the status Running, Finished, Recalling, Recalled, Aborted, and Archived. Campaigns that have never been activated or sent—which have a status of Ready, Scheduled, Recurring, or Draft—are not included in the number of matching campaigns. To learn more about the possible statuses for a campaign and what they mean, see Campaign Status.
# Values
Once you've selected the field you're interested in, enter or select the value(s)
of the field that users should have in order to be eligible for your target
segment. For example, if you select a custom event called flightBooking.destination,
you might specify possible values of Paris, London, or New York to create
a user list of people who are traveling to one of those destinations.
NOTE
Searches are case- and format-sensitive (a search for a value of multicity
will yield different results than a search for multiCity or multi-city). For
the most accurate segmentation results, be sure to check your search values for
correct formatting, capitalization, spelling, and typos.
# Logical operators
Throughout the segmentation query builder, you can use logical operators to indicate how many of the specified criteria users must match (or not match) in order to be included in your target segment. Iterable supports the following three logical operators:
- All – Users must match all of the clause or group's specified criteria to be included in the target segment.
- Any – Users must match at least one of the clause or group's specified criteria to be included in the target segment.
- None – Users cannot match any of the clause or group's specified criteria to be included in the target segment.
# Comparators
The Segmentation tool supports a wide range of comparators for finding and/or excluding specific user and event data values from a search.
# String Comparators
Iterable supports eight comparators for fields that have the string data type.
- Is Set – A value has been set for the field (the field is not blank).
- Equals – The value of the field must exactly match a specified value.
- Does Not Equal – The value of the field must not match a specified value.
- Is One Of – The value of the field must match one of a specified list of possible values. You can specify a maximum of 100 possible values.
- Is Not One Of – The value of the field must not match any of a specified list of possible values. You can specify a maximum of 100 possible values.
- Contains – The value of the field must contain the specified word or phrase. This regex comparator isn't a simpler alternative to Matches Regex, and is available only on fields below the unique-value (cardinality) limit, with a pattern up to 1,000 characters in length. Queries that use this field count toward regex-condition limits. For the current limits, see Iterable-specific regex behavior and limitations.
- Starts With – The value of the field must start with the specified word or phrase.
- Matches Regex – The value of the field must match the specified regular expression. This comparator is available only on fields below the unique-value (cardinality) limit, and the regex pattern can be up to 1,000 characters. Queries that use this field count toward the regex-condition limits. For the current limits, see Iterable-specific regex behavior and limitations.
NOTE
When using the Is One Of / Is Not One Of comparators, there are three ways to specify your desired values:
- Select one or more existing values from the dropdown menu.
- Type individual values into the text entry box, and press Enter on your keyboard to submit each value.
- Paste multiple values into the text entry box (separated by commas, pipes, or line breaks).
NOTE
Availability of Matches Regex and Contains depends on the field you're
searching. Low-cardinality fields are more likely to support these comparators,
while fields with many possible values may be limited to alternatives such as
Starts With or Is One Of. Regex pattern strings have a 30,000-character
limit. (This character limit does not apply to the #ifMatchesRegexStr helper
in Handlebars expressions.) For details about regex syntax, see
Handlebars Reference: Regular Expressions.
# Numeric comparators
Iterable supports five comparators for fields that contain numeric values. These comparators work with fields that have the long or double data type:
- Greater Than – The value of the field is greater than the specified value.
- Less Than – The value of the field is less than the specified value.
- Is Between – The value of the field is between two specified values (inclusive).
- Greater Than Or Equal To – The value of the field is greater than or equal to the specified value.
- Less Than Or Equal To – The value of the field is less than or equal to the specified value.
# Date comparators
Iterable supports six comparators for fields that have the date data type.
- Is After – The value of the field must be at least one day later than the specified date.
- Is On Or After – The value of the field must be either the same day as or any day after the specified date.
- Is Before – The value of the field must be at least one day before the specified date.
- Is On Or Before – The value of the field must be at least one day before the specified date.
- Is Not – The value of the field can be any date except the one specified in the date comparison.
- Is Between – The value of the field must be a date that falls within the specified range.
# List comparators
Iterable supports two comparators for searches based on values of lists.
- Includes – Users must be members of the specified list(s).
- Includes Anything But – Users can be members of any list except the specified list(s).