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.

Query = Term { [ whitespace Connective ] whitespace Term }

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

Connective = "AND" | "OR"

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

query=state:enabled OR state:disabled

Terms

Term = [ Modifier ] ( "(" Query ")" | [ name Comparator ] value )

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

Modifier = "-" | "NOT" whitespace

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

Comparator = ":" | ":<" | ":>" | ":<=" | ":>="

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.

Term search

Term searches will make a case-insensitive search appearing in any field in a document.

query=Bob Norman

This will make a case insensitive search for both "bob" AND "norman".

Field search

Field searches apply to terms in specific fields.

query=first_name:Bob age:27

This will search for the "Bob" in the "first_name" field AND "27" in the "age" field. The value must immediately follow the field with no whitespace: first_name: Bob will actually search for the terms "first_name" and "Bob".

Range search

A range search specifies a range of values to search against.

query=orders_count:>16 orders_count:<=30

This will match documents where the orders_count field is greater than 16 and less than or equal to 30. The supported operators are >, >=, < and <=.

Equality is done as orders_count:16, not orders_count:=16; the latter will actually search for the term "=16" in the orders_count field.

Not query

This query excludes documents that include the NOT operator.

query=-bob

query=NOT bob

Both of these queries will not return documents including the term "bob".

The "NOT" operator must be capitalized to execute a Not Query, and only applies to the following space separated term or query. The minus sign must precede the field, value, or subquery e.g. -field:value -value -(subquery).

Boolean operators

Boolean operators allow terms to be combined through logic operators.

query=bob OR norman AND Shopify

This will search for documents that MUST have the term "Shopify" and SHOULD have at least one of the terms "bob" or "norman".

query=bob OR norman Shopify

This query is equivalent to the query above, since OR has a higher operator precedence than AND. Furthermore, the default boolean operator between terms or queries is AND, so no explicit AND operator is needed.

Grouping

Shopify supports using parentheses to group clauses to form sub queries.

query=state:disabled AND ("sale shopper" OR VIP)

This searches for disabled customers with tags sale shopper or VIP.

Phrase query

A Phrase is a group of words surrounded by double quotes

query=name:"Bob Norman"

This will search for the term "bob" followed immediately by the term "norman" in the "name" field. Phrase queries can be used outside of a field query, e.g. "Bob Norman".

Special characters

Shopify supports the ability to escape special characters using backslash escaping. The current list of special characters is:

 : \ ( )

Names can include the characters -, ', and " but cannot start with them. Names can include escaped characters using backslash escaping.

Exists query

The exists query will match documents with a non-NULL value in the specified field.

query=published_at:*

This query can be combined with a Not Query to find fields missing a value, e.g. -published_at:*