Segment Query Language Reference

Audience definitions specify the criteria for identifying users or accounts as members of a particular audience, while computed trait definitions outline the logic for aggregating or calculating values stored as traits on user or account level profiles.

With Segment's query language, you can create these definitions and use them with Segment APIs to generate audiences and computed traits.

This section outlines the functions and operators you can use with the query language.

Follow these syntax rules when you create definitions:

• All definitions consist of expressions connected by optional junctions.
• Expressions are composed of chained functions, starting with an extractor and ending with a result.
• . serves as the delimiter when chaining functions.
• Audience definitions must return a boolean result (for example, a comparator), while computed trait definitions must return a scalar.
• Functions have well-defined return types that determine the permissible functions in the call chain.
• When you use junctions, AND holds precedence over OR, but parentheses offer control over expression combination.
• Each definition allows a maximum of 50 primary expressions.

The language supports the following syntactic sugar adjustments:

• The language automatically wraps a 'literal' extractor function around string or number inputs wherever a scalar expression expects them.
• You can invoke the boolean comparator functions equals, differs, greater_than, at_least, less_than, and at_most by omitting the period and parenthesis and replacing the function name with the equivalent symbols =, !=, >, >=, <, and <=. Regardless of the syntactic sugar, the comparison still dictates the operations allowed in the call-chain.

The definition type (USERS or ACCOUNTS) determines whether the computation operates at the user or account level. For account-level audiences, you can apply additional functions ANY (to verify that all underlying users meet the defined conditions) and ALL (to check if any of the underlying users meet the defined conditions).

These functions use the association between accounts and users to determine audience membership.

The following tables list the query languages's available functions.

Suppose you wanted to collect all users who performed the Shoes Bought event at least once within the last seven days, where the purchase price was greater than or equal to 100.

Another way to think of this scenario would be:

• Collect all users who performed the Shoes Bought event.
• Filter down to only consider events with a price greater than or equal to 100.
• Filter for events that occurred within the last seven days.
• Only include users who have one or more of the previous events.

Here's how you could do that in Segment's query language:

event('Shoes Bought').where( property('price') >= 100 ).within(7 days).count() >= 1

This example collects:

• all users who performed the Shoes Bought event at least once within the last 30 days
• where the price was greater than or equal to the average spend
• and the user performed the Shoes Returned event at least once, five days after the Shoes Bought event

1
event('Shoes Bought').where( 
2
property('price') >= trait('avg_spend')
3
AND 
4
event('Shoes Returned').within(parent: 5 days).count() >= 1 
5
).within(30 days).count() >= 1

This example collects all users who did not perform the Shoes Bought event at least once and don't have a total_spend trait with a value greater than 200:

NOT ( event('Shoes Bought').count() >= 1 AND trait('total_spend') > 200 )

This example collects all accounts where all associated users performed the Shoes Bought event at least once and have a total_spend trait greater than 200:

ALL ( event('Shoes Bought').count() >= 1 AND trait('total_spend') > 200 )

This example collects all accounts where no associated users performed the Shoes Bought event at least once:

ALL NOT event('Shoes Bought').count() >= 1

This example collects all accounts where any associated users performed the Shoes Bought event at least once:

ANY event('Shoes Bought').count() >= 1

This example collects all users who have at least 1 association to an orders entity where the orders entity has at least 1 association to an order-products entity:

entity('orders').where(entity('order-products').count() >= 1).count() >= 1

This example collects all users who have at least 1 association to an order entity or have a VIP trait equal to true:

entity('orders').count() >= 1 OR trait('VIP') = 'true'

This example collects all users with at least 1 association to an orders entity where the orders entity has a total property greater than 500:

entity('orders').where(property('total') > 500).count() >= 1

Suppose you wanted to calculate the average spend based on all Shoes Bought events performed within the last 30 days for each user.

Another way to think of this would be:

• Find all Shoes Bought events.
• Filter down to only consider events that occurred within the last 30 days.
• For these events, calculate the average spend for each user.

Here's how you could do that in Segment's query language:

event('Shoes Bought').within(30 days).avg(property('spend'))

This example calculates the minimum spend for each user, based on all Shoes Bought events, where the price was greater than 100 and the brand was My_Brand:

event('Shoes Bought').where( property('price') > 100 AND property('brand') = 'My Brand' ).min(property('spend'))

This example calculates the first-seen spend value for each user, based on all Shoes Bought events performed within the last 30 days:

event('Shoes Bought').within(30 days).first(property('spend'))

This example calculates the most frequent spend value for each user, based on all Shoes Bought events performed within the last 30 days. It only considers spend values that have a minimum frequency of 2:

event('Shoes Bought').within(30 days).mode(property('spend'), 2)