Syntax description of the search query language.
This page lists the query expressions and the operators, Composable Commerce Search APIs have in common. Find the resource-specific elements of the query language, like searchable fields, on the respective API reference page:
A search request submitted as payload on a Search API is a JSON object that contains the following fields:
query
- SearchQuery - Required
A simple expression or compound expression.sort
- Array of SearchSorting - Optional
The parameters for sorting search results.limit
- Number - Optional
The limit parameter for pagination.offset
- Number - Optional
The offset parameter for pagination.
Example:
name.en
) "laptop stand" sorted by name in descending (desc
) order. The result is limited to the first 20 resources matching the query.{
"query": {
"exact": {
"field": "name",
"language": "en",
"value": "laptop stand"
}
},
"sort": [
{
"field": "name",
"language": "en",
"order": "desc"
}
],
"limit": 20,
"offset": 0
}
SearchQuery
query
field on root level of a search request's payload:
The object contains either:- A single simple expression, like
exact
orfullText
, or - A compound expression wrapper, like
and
,or
,not
,filter
, which contains a list of simple expressions.
50
simple or compound expressions.256
characters.
Exceeding this limit returns an invalid input error.Example:
banana
in their English name (name.en
), and a Product Variant with the text Attribute someattribute
that has a value equal to 12
:{
"query": {
"and": [
{
"fullText": {
"field": "name",
"language": "en",
"value": "banana"
}
},
{
"filter": [
{
"exact": {
"field": "variants.attributes.someattribute",
"fieldType": "text",
"value": "12"
}
}
]
}
]
}
}
Simple expressions
Expression type | Field name | Example use case |
---|---|---|
exact | exact | Performs exact match on values of a specified field. |
fullText | fullText | Performs full-text search on a specified field. |
prefix | prefix | Searches for values starting with a specified prefix. |
range | range | Searches for values within a specified range. |
wildcard | wildcard | Searches for values with specified wildcards. |
exists | exists | Checks whether a specified field has a non-null value. |
exact
yellow car
, for example, returns resources with values yellow car
or Yellow Car
, but not with car
or best yellow car
since those values match only partially, but not exactly.
If you want partial matches on several search terms to apply, consider using a fulltext expression instead.
A prefix expression is suitable when yellow car
should match yellow cars
also.Required fields:
-
field
: String - Searchable field. -
fieldType
: String - SearchFieldType. Must be provided iffield
is a non-standard field on a resource, like a Product Attribute.For Order Search, you must providecustomType
: String - CustomType instead iffield
is a Custom Field. -
value
: String - Search term the value of the specifiedfield
must match. If the search term contains several words separated by whitespaces, the value must match to thefield
value as a whole. With the additionalcaseInsensitive
parameter you can control whether casing should be considered or ignored. -
values
BETA: Array of String - List of search terms. At least one of the terms must match the specifiedfield
term (term_1 OR term_2 OR ... OR term_100). The maximum number of values per exact expression is 100. The maximum total number of values over all exact expression is 500.Eithervalue
orvalues
must be provided.values
must not be empty.
Optional fields:
-
caseInsensitive
: Booleantrue
: Returns resources for which the provided search term matches exactly or differs in casing only.false
(default): Returns only those resources for which the provided search term matches exactly including casing.
exact
query searches for resources with the key
= KEY101
.
This query also returns resources that have the lowercased version of the value (key101
) since the caseInsensitive
parameter is set totrue
.{
"query": {
"exact": {
"field": "key",
"value": "KEY101",
"caseInsensitive": true
}
}
}
KEY101
, KEY102
, or KEY201
.
Specify multiple search terms for the same field with the values
field instead of the value
field.{
"query": {
"exact": {
"field": "key",
"values": ["KEY101", "KEY102", "KEY201"],
"caseInsensitive": true
}
}
}
fullText
field
.Required fields:
-
field
: String - Searchable field. -
fieldType
: String - SearchFieldType. Must be provided whenfield
is a non-standard field on a resource, like a Product Attribute.For Order Search, you must providecustomType
: String - CustomType instead iffield
is a Custom Field. -
value
: String - The search term the values of the specifiedfield
must match. You can provide several terms separated by whitespaces. With the additionalmustMatch
parameter you can control whether all of the provided terms must match or any of those.
Optional fields:
-
mustMatch
: Stringany
: Returns resources for which at least one of the provided search terms match.all
(default): Returns only those resources for which all the provided search terms match.
Examples:
yellow car
without the mustMatch
parameter, the search result contains resources for which the English name
is exactly yellow car
:{
"query": {
"fullText": {
"field": "name",
"language": "en",
"value": "yellow car"
}
}
}
yellow
or car
in their English name
, add the mustMatch
parameter to the full text query
and set it to any
:{
"query": {
"fullText": {
"field": "name",
"language": "en",
"value": "yellow car",
"mustMatch": "any"
}
}
}
fullText
search expressions.
If you need partial matches, consider prefix search instead.prefix
Searches for values that start with a specified prefix.
Required fields:
-
field
: String - Searchable field. -
fieldType
: String - SearchFieldType. Must be provided whenfield
is a non-standard field on a resource, like a Product Attribute.For Order Search, you must providecustomType
: String - CustomType instead iffield
is a Custom Field. -
value
: String - The search term the values of the specifiedfield
must match. You can provide several terms separated by whitespaces.
Optional fields:
-
caseInsensitive
: Booleantrue
: Returns resources for which the provided search term matches exactly or differs in casing only.false
(default): Returns only those resources for which the provided search term matches exactly including casing.
Example:
prefix
query matches resources with names including card
, carton
, caravan
, or carpet
.{
"query": {
"prefix": {
"field": "name",
"language": "en",
"value": "car"
}
}
}
yell ca
will not match the value yellow car
as all terms form one prefix. You would need to search for yellow c
to match yellow car
instead.range
Searches for values between specified boundaries to restrict the search query to certain time frames or ranges of numerical values.
Required fields:
-
field
: String - Searchable field. -
fieldType
: String - SearchFieldType. Must be provided whenfield
is a non-standard field on a resource, like a Product Attribute.For Order Search, you must providecustomType
: String - CustomType instead iffield
is a Custom Field.
The range must contain either an upper or a lower boundary. Hence you must provide at least one of the operators below as key for the JSON property.
Operator | Symbol | Behavior |
---|---|---|
gt | > | Only matches values strictly greater than the specified value. |
lt | < | Only match values strictly lesser than the specified value. |
gte | >= | Only matches values greater than or equal to the specified value. |
lte | <= | Only matches values lesser than or equal to the specified value. |
field
to search for.
The data type of the specified value must match the data type of the searchable field.Optional fields:
By providing only one of the above operators, you specify an open range for the value to search for. You optionally close the range with a corresponding boundary when you provide a second operator with a value.
Example:
lastModifiedAt
and determine its data type as DateTime.
Since the dates you are looking for are in the past, you can limit your search request to everything that happened between the least possible DateTime on that very day (gte
as lower boundary) and the least possible DateTime on the following day (lt
as upper boundary), like so:{
"query": {
"range": {
"field": "lastModifiedAt",
"gte": "2018-08-25T12:00:00.000Z",
"lt": "2018-08-26T12:00:00.000Z"
}
}
}
wildcard
wildcard
expression you can use placeholders in values that specify which part of the value does not need to match the search term exactly. Such expression is suitable when your query should tolerate slight variations in spellings for search terms, like whisky
and whiskey
. With a wildcard
expression, you don't need two exact
expressions for both terms separately, but only one.wildcard
expressions are not as efficient as other expressions and should only be used when no other expression is applicable for your use case. For example, when the search term starts with a static string followed by a wildcard, a prefix expression is sufficient and should be applied instead.Required fields:
-
field
: String - Searchable field. -
fieldType
: String - SearchFieldType. Must be provided whenfield
is a non-standard field on a resource, like a Product Attribute.For Order Search, you must providecustomType
: String - CustomType instead iffield
is a Custom Field. -
value
: String - Search term the value of the specifiedfield
must match. Use following characters as placeholders:*
for zero, one, or more characters?
for exactly one character.
With the additionalcaseInsensitive
parameter you can control whether casing should be considered or ignored.
Optional fields:
-
caseInsensitive
: Booleantrue
: Returns resources for which the provided search term matches exactly or differs in casing only.false
(default): Returns only those resources for which the provided search term matches exactly including casing.
whisky
as well as whiskey
.{
"query": {
"wildcard": {
"field": "name",
"language": "en",
"value": "whisk*y",
"caseInsensitive": true
}
}
}
car
, but having exactly one additional character, not more. With a prefix
query you cannot restrict the characters followed by the prefix term, but in a wildcard
query you can use the ?
character to specify that exactly one character must follow the prefix to match the query:{
"query": {
"wildcard": {
"field": "name",
"language": "en",
"value": "car?",
"caseInsensitive": true
}
}
}
wildcard
query matches resources with names including career
, corner
, cursor
, and corr
.{
"query": {
"wildcard": {
"field": "name",
"language": "en",
"value": "c?r*r",
"caseInsensitive": true
}
}
}
exists
exists
query matches resources that have a field with a non-null value.Required fields:
-
field
: String - Searchable field. -
fieldType
: String - SearchFieldType. Must be provided whenfield
is a non-standard field on a resource, like a Product Attribute.For Order Search, you must providecustomType
: String - CustomType instead iffield
is a Custom Field.
exists
query matches Products that have a value for the Attribute someattribute
:{
"query": {
"exists": {
"field": "variants.attributes.someattribute"
}
}
}
Compound expressions
The following compound expressions are currently supported:
Expression | Behavior |
---|---|
and | only matches resources that match all sub-expressions. |
or | only matches resources where at least one of the sub-expressions is matched. If you want to search for multiple OR-combined values for the same field , you can specify them in the values of an exact simple expression instead. This reduces the number of expressions that count toward the 50 expressions limit in a query. |
not | only matches resources that do not match any of its sub-expressions. |
filter | Matching resources of a query are checked for their relevancy to the search. The relevancy is expressed by an internal score. All expressions except filter expressions contribute to that score. All sub-expressions of a filter are implicitly connected with an and expression. |
and
compound expression query to find the price of EUR 22.22 across Product Variants.
In addition, we want to search for specific countries (Austria, Belgium, Croatia) for which the price is specified.
Therefore, the query consists of three exact expressions; one for the currencyCode
field, one for the centAmount
field, and one for the country
field of the variants.prices
:{
"query": {
"and": [
{
"exact": {
"field": "variants.prices.currencyCode",
"value": "EUR"
}
},
{
"exact": {
"field": "variants.prices.centAmount",
"value": 2222
}
},
{
"exact": {
"field": "variants.prices.country",
"values": ["AT", "BE", "HR"]
}
}
]
}
}
exact
expression contains the values
field, which lists multiple values for the country.
This means, the query will match if any of these values match.Searchable fields
field
property to specify which field of a resource should be searched through.
The API matches the search term only against the values of the specified field, not against any field of a resource.
If you want to search through several fields of a resource, you need to formulate simple expressions for each of those fields.Find the searchable fields specific to the resource on the respective Search API documentation:
SearchFieldType
fieldType
property on simple expressions indicating the data type of the field
.boolean
- For Boolean fields, AttributeBooleanType Attributes, and BooleanType Custom Fields.
text
- For string fields, AttributeTextType Attributes, and StringType Custom Fields.
ltext
- For LocalizedString fields, AttributeLocalizableTextType Attributes, and LocalizedStringType Custom Fields.
enum
lenum
- For localized enum fields, AttributeLocalizedEnumType Attributes, and LocalizedEnumType Custom Fields.
number
- For number fields, AttributeNumberType Attributes, and NumberType Custom Fields.
money
- For Money fields and AttributeMoneyType Attributes.
date
datetime
time
reference
- For Reference fields and AttributeReferenceType Attributes.
set_boolean
- For Set of Boolean fields, AttributeSetType of
boolean
Attributes, and SetType ofboolean
Custom Fields. set_text
set_ltext
- For Set of LocalizedString fields, AttributeSetType of
ltext
Attributes, and SetType ofltext
Custom Fields. set_enum
set_lenum
- For Set of localized enum fields, AttributeSetType of
lenum
Attributes, and SetType oflenum
Custom Fields. set_number
- For Set of number fields, AttributeSetType of
number
Attributes, and SetType ofnumber
Custom Fields. set_money
set_date
set_datetime
- For Set of DateTime fields, AttributeSetType of
datetime
Attributes, and SetType ofdatetime
Custom Fields. set_time
set_reference
Types of fields
For standard fields on indexed resources, the Search APIs classify the following types of fields:
- boolean: for boolean fields.
- long: for integer number fields.
- double: for floating point number fields.
- date: for Date fields.
- dateTime: for DateTime fields.
- keyword: for fields holding unique identifiers.
- text: for string fields.
- localizedText: for LocalizedString fields.
- phone: for phone numbers containing non-numerical characters for formatting.
Simple expression supported for which type of field
Types | fullText | exact | prefix | range | wildcard | exists |
---|---|---|---|---|---|---|
boolean | ✓ | ✓ | ||||
long, double, date, dateTime | ✓ | ✓ | ✓ | |||
keyword | ✓ | ✓ | ✓ | ✓ | ||
text and localizedText | ✓ | ✓ | ✓ | ✓ | ✓ | |
phone | ✓ | ✓ | ✓ | ✓ |
Boost query results
boost
field is a way to make the results that match one particular query more relevant than results that match the others.
A boost
value between 0
and 1
lowers the relevance, values greater than 1
give the simple expression a higher relevance.name
score more relevant than those with "butter" in the description
.{
"query": {
"or": [
{
"fullText": {
"field": "name",
"language": "en",
"value": "butter",
"boost": 2
}
},
{
"fullText": {
"field": "description",
"language": "en",
"value": "butter"
}
}
]
}
}
SearchSorting
Sorting parameters provided with a Search request.
field String | Use any searchable field of the resource as sort criterion, or "score" to sort by relevance score calculated by the API. |
language | String value specifying linguistic and regional preferences using the IETF language tag format, as described in BCP 47. The format combines language, script, and region using hyphen-separated subtags. For example: DisplayName: en , en-US , zh-Hans-SG .Locale |
order | Specify the order in which the search results should be sorted.
Can be asc for ascending, or desc for descending order. |
mode | Specify the sort mode to be applied for a set-type field . |
fieldType | Provide the data type of the given field . |
filter | Allows you to apply a sort filter. |
createdAt
:{
"sort": [
{
"field": "createdAt",
"order": "asc"
}
]
}
Sort order
asc
Ascending sort order, the lowest value is listed first.
desc
Descending sort order, the highest value listed first.
Sort mode
variants.prices.centAmount
) you can optionally pass a sort mode.
This is relevant because a single Product can have multiple variants and thus multiple centAmount
fields.
That means that there might not be a single value to sort on, but multiple.
Using the sort mode we can choose which of the values in the array to use for sorting or how to aggregate them.
The default sorting mode is min
Following four sort modes are provided:
min
- Use the minimum of all available valuesmax
- Use the maximum of all available valuesavg
- Use the average of all available valuessum
- Use the sum of all available values.
If a Product is missing that field, it will be at the last position.
min
sort mode to sort by variants.prices.centAmount
in descending order:{
"sort": [
{
"field": "variants.prices.centAmount",
"language": "en",
"order": "desc",
"mode": "min"
}
]
}
Sort filter
filter
with a simple expression.filter
to only return Products in the Category whose id
is 4054a159-7f3e-4fe9-a30c-8db80ca7d665
.{
"sort": [
{
"field": "name",
"language": "en",
"order": "asc",
"filter": {
"exact": {
"field": "categories",
"value": "4054a159-7f3e-4fe9-a30c-8db80ca7d665"
}
}
}
]
}
You can only filter on the same parent field you sort by. In this case on the root of the Product.
Pagination
10 000
results by requesting them page by page.
The total
field in a query result indicates how many results match the search query in total.Limit
limit
parameter you can set the maximum number of results returned on a page.
Any value between 1
and 100
is allowed, the default limit is 20
.Offset
offset
parameter controls the starting point for retrieving paginated results.
With the default value 0
you retrieve the first page of query results.
Setting "offset" : 1
skips the first page and returns the second page of results, and so on.
Each page contains a number of results defined by the limit
parameter.offset
is 9900
. When combined with the maximum limit
of 100
, this allows you to retrieve the first 10 000
results in total.