The Shopify API has a flexible and powerful method of constructing search queries to allow developers to filter, combine and refine their search results through multiple different interfaces (storefront search (also referred to as ‘search’ or ‘Search on Shopify’), admin dashboard, mobile apps, customer group queries, GraphQL Admin API, and Search API).

In this guide we will provide an overview of the Shopify API’s various search query components in a developer-friendly manner with examples that can be used.

Understanding the Search Query Structure

There are 4 main components to each search query that constitute a valid search query in the Shopify API:

• Terms, which represent what you’re searching for
• Connectives, which are logical operators; i.e. AND / OR
• Modifiers, which are exclusion operators; i.e. – or NOT
• Comparators, which are operators; i.e. :, >, <, >=, <=

These Components allow you to build simple or complex search filter(s)/criteria for your search queries.

Basic Query Format

Queries consist of multiple terms, separated by whitespace. When you don’t specify a logical operator, Shopify assumes that you want to do an ‘AND’ query.

For example: query=John Smith

This will search for all documents containing both “John” and “Smith.”

Logical Operators (Connectives)

Shopify supports two logical operators:

• AND (this is the default)
• OR

For example: query=state:enabled OR state:disabled

When there isn’t a logical operator between terms, Shopify assumes AND.

Terms and Modifiers

There are three types of terms:

• Simple (value)
• Specific field query
• A grouped subquery, indicated by parentheses

You can also use modifiers to exclude terms from your query.

Excluding Results

There are two methods of excluding results in Shopify:

• – (no space between the minus and the term you want to exclude)
• NOT (case-sensitive; must be uppercase)

For example:

• query=-first_name: Bob
• query=NOT first_name: Bob

These queries show all records except those where first_name=’Bob’.

Comparators Explained

Comparators define how values are matched.

Comparator	Meaning
:	Equality
:>	Greater than
:<	Less than
:>=	Greater than or equal
:<=	Less than or equal

Important Note on Equality (:):

• For numeric fields – the values must match exactly.
• For tokenized text fields – the values can match anywhere in the field(s).
• For non-tokenized fields – the values must match exactly, in their entirety.

Handling Special Characters

Some characters have special meaning in Shopify search syntax and must be escaped using a backslash (\):

• :
• \
• (
• )

Field names can include -, ‘, and ” but cannot start with them unless escaped.

Need Better Shopify Search Results? Shopify search syntax is powerful but strict. Expertrec enhances native search with better relevance, typo tolerance, and higher conversions—without replacing Shopify. Try Expertrec Smart Search

Common Shopify Search Query Types

Shopify has various search options available to help narrow down to specific fields of a product or customer. Here are the most common types of searches that can be performed by using Shopify:

Field-Specific Search

Searches can be performed on a certain field.

The example listed is:

query=first_name: Bob age:27

This returns any record that is found where the first_name is Bob and the age is 27.

Important Note: if the field does not exist in the database will be ignored by Shopify and the result set will include all records.

Default Search

Search against all searchable fields with no case sensitivity.

The example listed is:

query=Bob Norman

If you’ve added multiple word combinations to search for a particular field, the whole phrase must be enclosed in quotation marks for successful results.

Range Search

This type of search can be used on numeric or date ranges.

The example listed is:

query=orders_count:>16 orders_count:<=30

This returns any record that has an orders_count that is greater than 16 and less than or equal to 30.

Tip: – if there are many records in the data set that are being searched against, it may cause performance problems to use range filters, but sorting the results by the same field as the range filter will give you better performance.

NOT Queries

It is used to filter records that won’t contain a particular term.

Here are two examples:

query=-bob
query=NOT bob

Both will filter away any record that has “bob” in it.

Boolean Logic

The OR operator is processed prior to the AND operator.

The example below illustrates that:

query=bob OR norman AND Shopify

This indicates:

• The search results must contain the term “Shopify”
• The search results must contain either “bob” or “norman”

Grouping with Parentheses

Use parentheses in combination with logical connectors to form subqueries.

For instance, your query can be structured as follows:

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

This will locate disabled customers who have been tagged as either “sale shopper” or “VIP.”

Phrase Queries

Use double-quotes in a STRING to create a string match for the entire phrase.

Example of this type of string match will be:

query=first_name:"Bob Norman"

In this case, “Bob” and “Norman” must be in proximity to one another in order for a match to take place.

Prefix (Wildcard) Search

Wildcard characters can be used to search for specific letters within a string.

List of Examples

query=norm*

This example would return results that include the following: norman, normal…

Exists Query

To find all records where a field has non-null data, use the following query structure:

query=published_at:*

To find empty records, combine it with “NOT”:

query=-published_at:*

Shopify GraphQL API Examples

products(first: 5, query: "created_at:>'2020-10-21T23:39:20Z'") {
  edges {
    node {
      id
      title
      createdAt
    }
  }
}

products(first: 5, query: "title:\"Caramel Apple\"") {
  edges {
    node {
      id
      title
    }
  }
}

products(
  first: 5,
  query: "(title:Caramel Apple) OR (inventory_total:>500 inventory_total:<=1000)"
) {
  edges {
    node {
      title
      totalInventory
    }
  }
}

Debugging Search Queries

The GraphQL admin API for Shopify has built-in tools for debugging searches. If a search query is malformed or tries to use invalid fields, warnings are issued in the extensions.search portion of the response. This gives visibility into:

• How the search was parsed
• What fields were ignored
• Any compatibility issues

Enabling debugging on all queries is done by sending this header:

Shopify-Search-Query-Debug: 1

Final Thoughts

Although Shopify’s search syntax allows for robust search options, it is also very restrictive. A good understanding of operators, fields, and how indexing works will help you:

• Construct your queries faster
• Reduce the number of unexpected search results
• Provide better experiences for searching and filtering

For stores that are looking for advanced, typo-tolerant, and relevancy-based search options, the built-in syntax can be accompanied by an external search provider such as Expertrec and provide a vastly improved customer experience.