Search query language
Search query language
A search expression narrows the records returned by a supported GraphQL connection’s query argument.
It is different from a GraphQL document and from a commerce-rule predicate.
Pass the expression as a variable rather than inserting it into the operation text.
Use the field’s own filter contract
Supported filters depend on the resource and API. Use the filter table on Storefront products, Admin products, or the exact connection you are calling. A filter supported by one connection is not automatically supported by another. This page explains composition; the API reference owns the field inventory.
Compose clear clauses
| Expression | Purpose |
|---|---|
lamp | Search a term using the resource’s text behavior |
vendor:"Acme Lighting" | Match a quoted value on a supported field |
tag:lighting AND tag:portable | Require both clauses |
(tag:desk OR tag:reading) AND tag:lighting | Group alternatives with a required clause |
NOT tag:retired | Exclude a clause |
Use uppercase boolean operators and parentheses when combining alternatives. Use the exact documented field name, including snake_case spelling where applicable. Text matching behavior depends on the field; do not assume a name, SKU, and numeric filter use identical matching.
Price filtering, dates, and custom fields
Use range operators only where the operation documents them.
Storefront price comparisons use minor currency units and require matching currency context.
For example, in an EUR request, price:>=5000 AND price:<=15000 describes EUR 50.00 through EUR 150.00.
It does not perform currency conversion.
For configured facets, use the returned queryField.
For public metafields, use the supported owner and field contract when choosing a dynamic search path.
Do not guess a searchable field from the shape of a GraphQL object.
Escape values and preserve context
Quote values containing spaces or query punctuation. Keep JSON escaping separate from search escaping by passing a GraphQL variable. Only accept filter field names that your application supports; do not blindly forward arbitrary browser-provided field names.
Restart pagination whenever text, filters, sort, or commerce context changes. If a result is unexpectedly empty, remove clauses and add them back one at a time. Follow Add search and filters for the application workflow.