Shopify API search syntax

This page provides information on the syntax for searching text fields.

The same search query syntax is used across Shopify as an interface to search functionality. This includes the storefront, admin, mobile apps, customer group queries, Admin API, and Storefront API. For the APIs, the specific resources that can be queried are defined in the reference documentation.

Search query grammar overview

A string query is a text search made up of terms, connectives, modifiers, and comparators. The search grammar rules defined here can be built into larger structures as defined by the search query syntax.

The search grammar is expressed similarly to EBNF and uses some baseline terminal symbols as follows:

Item Description
whitespace Any sequence of space, tab, or newline characters.
name Any sequence of non-whitespace, non-special characters. See Special characters for more information.
value Any name, or any quoted string (single or double quotes are both permitted).

Query

The root of the grammar is a Query.

A Query is one or more Terms separated by whitespace and optionally by single Connectives. A Query may have optional leading and trailing whitespace.

query=John Smith

Connectives

When a Connective is not specified between two Terms, AND is implied.

query=state:enabled OR state:disabled

Terms

A term consists of an optional modifier, followed either by a sub-Query (enclosed in parentheses) or a value with an optional name-and-Comparator.

query=-first_name:Bob AND orders_count:>3 orders_count:<=4

Modifier

A modifier can be "-" (in which case it must not be followed by whitespace) or it may be "NOT" (in which case it must be followed by whitespace). Both mean the same thing.

query=-first_name:Bob

Comparators

The current list of comparators is:

  • : is equality*
  • :< is less-than
  • :> is greater-than
  • :<= is less-than-or-equal-to
  • :>= is greater-than-or-equal-to

* equality depends on how a field is indexed. For numeric fields : represents equality. For tokenized fields, equality exists if the term is found anywhere in the field. For non-tokenized fields, the search query string must match the searched field exactly.

Search query syntax

Shopify search query syntax is based on the defined grammar and enables the following search behavior.