Segment query language reference

Use ShopifyQL to query the GraphQL Admin API for segmentation data. Segmentation data represents data subsets, which users have created according to some criteria.

Segmentation data corresponds to saved search queries in the Shopify admin. For example, a user can save a segment for customers that are subscribed to email marketing. These customers are the segment members.

The following guide explains the syntax for forming queries.

Anchor to Segment queriesSegment queries

Segmentation queries in API requests are precise definitions of segments. The queries indicate the condition or conditions that data must satisfy to be selected. The syntax performs a similar function to WHERE statements in SQL. Query syntax acts as a filter to determine the data returned.

For example, a segment query can retrieve segment members that have left a checkout without completing their purchase in the last 30 days.

You can query a maximum of 250 segments. The maximum value that first and last arguments accept is 250.

Anchor to Query syntaxQuery syntax

Segment queries are composed of a clause, or multiple clauses, specifying facts about the segment. The clauses specify a segment by applying a condition to an attribute using an operator.

An individual clause consists of the following components:

• attribute: The properties that define all items in a specific category.
• operator: A reserved character pattern that performs tasks such as comparisons and arithmetic operations.
• condition: The state required for data to be either selected or filtered out.

Anchor to Clause formatClause format

The following is the query clause format:

For example, in the following clause, email_subscription_status is the attribute, = is the operator, and SUBSCRIBED is the condition:

You can also group clauses.

Anchor to AttributesAttributes

An attribute's data type determines the valid operators and conditions for defining segment queries.

The following are supported attributes and their data types:

Anchor to Boolean attributesBoolean attributes

Boolean attributes support specific operators and conditions.

Anchor to OperatorsOperators

Anchor to ConditionsConditions

Anchor to Date attributesDate attributes

Date attributes support specific operators and conditions.

Anchor to OperatorsOperators

Date operators act on complete 24-hour days and default to a shop's time zone.

For example, a New York shop (GMT-4) with the following query would include customers who last ordered between midnight (T00:00:00) on May 30th, 2020 to midnight on May 31st, 2020 in the shop's timezone.

In SQL, with UTC-based times, this would look like the following:

The following segment query would include customers who last ordered from midnight on May 31st:

The following are supported operators for date-type attributes.

Anchor to ConditionsConditions

Date-type attributes accept specific conditions.

Anchor to [object Object]{absoluteDate}

Language-sensitive formatted dates aren't accepted.

Anchor to [object Object]{dateOffset}

Syntactic sugar for an absolute date without time. For example, if the date is May 15th 2021, then -7d is syntactic sugar for 2021-05-07.

The following are examples of {dateOffset}:

Anchor to [object Object]{namedDate}

Syntactic sugar for an absolute date without time.

{namedDate} supports the following operators:

When using the BETWEEN operator, condition types can be mixed.

The -12m, -90d, -30d, and -7d standard syntax is preferred to the now-deprecated 12_months_ago, 90_days_ago, 30_days_ago, and 7_days_ago syntax.

Anchor to [object Object]{absoluteDateTime}

In some cases, users might want finer segment granularity, such as the segment of customers that participated in a timed flash sale. The segmentation query syntax supports an absolute datetime in place of an absolute date.

Times default to a shop's timezone. For example, a New York shop (GMT-4) with the following query would include customers means last_order_date > 2020-05-30T20:00:00 in UTC.

Anchor to NotesNotes

• Only 24h format is supported. For example, HH needs to be be <= 23 (24h = 00:00:00).

• Leading zeros are required, for example, 23:00:00.

• Time-only syntax is not supported. For example, the following syntax is invalid:

• You can't extend {namedDate} or {dateOffset} with a time-specifier.

Anchor to Enum attributesEnum attributes

Enum attributes support specific operators and conditions.

Anchor to OperatorsOperators

Anchor to ConditionsConditions

• Conditions accept UTF-8 characters and must be wrapped with single quotes ', similar to the ENUM type in MySQL.

• Conditions only accept a value chosen from a list of permitted values.

• Conditions are case-sensitive and whitespaces are syntactically significant.

• Single quotes within a condition must be escaped (ie. '\'VIP\'').

• For Segmentation, we're using multiple clauses with connectors to specify multiple values.

Anchor to Float attributesFloat attributes

Float attributes support specific operators and conditions. The underlying data type is a float64 (double-precision floating-point format).

Anchor to OperatorsOperators

Anchor to ConditionsConditions

• Conditions accept float (float64) and integer numbers.

• Integers automatically get converted to floating point (ie. 99 => 99.0).

• Operators and functions returning a Float, for example COUNT, SUM, MAX, and MEDIAN, aren't supported for querying segments.

Anchor to Formatting and separatorsFormatting and separators

• A decimal point (.) is used as a decimal separator, by default.

• Thousand separators, such as commas and spaces, aren't supported.

• Language-sensitive formatted numbers aren't supported.

Anchor to Function attributesFunction attributes

A Function accepts 0 or more parameters, individually supporting specific <operator>s and <condition>s that you can use to select specific customers. For example, products_purchased MATCHES (id = 1234, count > 1) would select all customers who purchased product id 1234 more than once.

Anchor to SyntaxSyntax

• Function names accept the same characters as regular filters, using lowercase alphanumerical and underscore (snake_case()).

• Functions names are follow by either MATCHES or NOT MATCHES and parentheses enclosing the list of optional parameters.

• Parameters are expressed by name with an appropriate, typed operator and value.

• The previous syntax is now deprecated syntax (for example, `products_purchased (id: 1234) = true).

• The anniversary expression is a modifier for a date filter, not a function. It determines whether a specified date falls on the annual anniversary of another data. For example, anniversary ('metafields.facts.birth_date') = today.

Anchor to SupportSupport

The segmentation query syntax has limited support for function-type attributes.

Anchor to [object Object]products_purchased

This function returns a Boolean. Supported <operator> values are = and !=.

For example,

Anchor to Named parametersNamed parameters

Anchor to [object Object], (optional)id (optional)

Where ID is a single value and List<ID> is a set of comma-separated values wrapped in parenthesis. An implicit OR between values is applied for lists.

Each ID is a product ID.

Notes

• A single value in a list is valid.

• Multiple values must be provided as a list. For example (1012132033639, 2012162031638, 32421429314657).

• A list can contain up to 500 IDs.

For example,

Omitting the id parameter returns results for all products.

Anchor to [object Object], (optional)tag (optional)

Where tag is a product tag.

Notes

• A single tag can be provided.

For example,

Anchor to [object Object], (optional)date (optional)

Where

This parameter is the date when the product was purchased.

For example,

Omitting the date parameter returns results from all time.

Anchor to [object Object]shopify_email.EVENT()

Shopify Email functions enable segmenting on Shopify Email events. They are namespaced under the shopify_email. prefix. The following events are supported:

• bounced
• clicked
• delivered
• marked_as_spam
• opened
• unsubscribed

All of these functions accept the same named parameters and return a Boolean.

For example,

Anchor to Named parametersNamed parameters

Anchor to [object Object], (optional)activity_id (optional)

Where ID is a single value and List<ID> is a set of comma-separated values wrapped in parenthesis. An implicit OR between values is applied for lists.

Each ID is a marketing activity ID to filter on.

Notes

• A single value in a list is valid.

• Multiple values must be provided as a list. For example (5240029206, 1932881090, 3250045832).

• A list can contain up to 500 IDs.

For example,

Omitting the activity_id parameter returns results for all Shopify Email activities.

Anchor to [object Object], (optional)date (optional)

Where

This parameter is the date for the Shopify Email event.

For example,

Omitting the date parameter returns results from all time.

Anchor to Integer attributesInteger attributes

Integer attributes are int64 types that support specific operators and conditions.

Anchor to OperatorsOperators

Anchor to ConditionsConditions

• Conditions accept only integer numbers.

• Floats aren't valid.

• Minimum value of -9,223,372,036,854,775,808.

• Maximum value of 9,223,372,036,854,775,807, inclusive.

• Operators and functions returning a Float, for example COUNT, SUM, MAX, and MEDIAN, aren't supported for querying segments.

Anchor to Formatting and separatorsFormatting and separators

• Thousand separators, such as commas and spaces, aren't supported.

• Language-sensitive formatted numbers aren't supported.

Anchor to List attributesList attributes

List attributes represent multi-value attributes. The values in the list have a type.

The arguments the operator admits will depend on the type of the values within the list. An example is customer_tags, which is a multi-value list of strings. Its full type is therefore List<String>.

Lists support the following operators and conditions.

Anchor to OperatorsOperators

Anchor to ConditionsConditions

• The semantics of CONTAINS as applied to a LIST is that the arguments must be a subset of the preceding list attribute.

• Segmentation queries currently use multiple clauses with connectors to specify multiple values, rather than a multi-argument form.

Anchor to [object Object], conditionsList<String> conditions

• String conditions accept UTF-8 characters and must be wrapped with single quotes ', similar to the ENUM type in MySQL.

• Conditions are NOT case-sensitive and whitespaces are syntactically significant.

• Single quotes within a condition must be escaped (ie. '\'VIP\'').

Anchor to [object Object], conditionsList<ID> conditions

• ID is an alias for an unsigned integer. The underlying data type is a uint64.

• Conditions don't have to be wrapped in single quotes '.

Anchor to String attributesString attributes

String attributes support specific operators and conditions.

Anchor to OperatorsOperators

Anchor to ConditionsConditions

• Conditions accept UTF-8 characters and must be wrapped around single quotes '.

• Conditions are case-sensitive and whitespaces are syntactically significant.

• Single quotes within a condition must be escaped. For example, '\'VIP\'').

• Conditions can be empty strings. The API verifies that the attribute exists and is an empty string.

• All operators/functions returning a String, such as CONCAT, SUBSTR, LOWER, UPPER, and TRUNCATE, are not supported for querying segments.

Anchor to Grouped clausesGrouped clauses

The following are syntax examples of grouped clauses.

Anchor to Multiple clauses with same connector(s)Multiple clauses with same connector(s)

Two clauses linked with AND

Two clauses linked with OR

Invalid query: Too many clauses (>10)

Anchor to Multiple clauses with different connectorsMultiple clauses with different connectors

By default AND takes precedence over OR. Parenthesis are optional. For example, the following queries are equivalent.

Change implicit order of precedence: OR now takes precedence over AND