Search query language

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 query 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:

The following example search request returns all resources matching the English name (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

A SearchQuery is a JSON object assigned as value to a query field on root level of a search request's payload: The object contains either:

One SearchQuery can contain up to 50 query or compound expressions.

String-type values in query expressions are limited to 256 characters. Exceeding this limit returns an invalid input error.

Example:

The following example SearchQuery demonstrates how to search for all Products which have 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"
}
}
]
}
]
}
}

Query expressions

The query language provides different query expressions supporting specific use cases, embed one of the following expression types into the SearchQuery as field specified by the field name:

Expression typeField nameExample use case
exactexactPerforms exact match on values of a specified field.
fullTextfullTextPerforms full-text search on a specified field.
prefixprefixSearches for values starting with a specified prefix.
rangerangeSearches for values within a specified range.
wildcardwildcardSearches for values with specified wildcards.
existsexistsChecks whether a specified field has a non-null value.

exact

Searches for exact matches of the provided search term with or without taking casing into account. With this expression, the search term 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 query expression instead. A prefix query expression is suitable when yellow car should match yellow cars also.

Required fields:

  • field: String - Query field.
  • fieldType : String - SearchFieldType. Must be provided when field is a non-standard field on a resource, like a Product Attribute.
  • language: Locale - Language of the localized value. Must be provided when field is of type localizedTextField. The provided Locale must be one of the languages of your Project. Otherwise, the search request does not return any result.
  • value: String - Search term the value of the specified field must match. If the search term contains several words separated by whitespaces, the value must match to the field value as a whole. With the additional caseInsensitive parameter you can control whether casing should be considered or ignored.

Optional fields:

  • caseInsensitive: Boolean

    • true: 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.

The following exact query searches for resources with the value search query expression in their English description. This query also returns resources that have the capitalized version of the value (Search Query Expression) in their description field for the English language since the caseInsensitive parameter is set to true.

{
"query": {
"exact": {
"field": "description",
"language": "en"
"value": "search query expression",
"caseInsensitive": true
}
}
}

fullText

Performs a full text search on the specified field.

Required fields:

  • field: String - Query field.
  • fieldType : String - SearchFieldType. Must be provided when field is a non-standard field on a resource, like a Product Attribute.
  • language: Locale - Language of the localized value. Must be provided when field is of type localizedTextField. The provided Locale must be one of the languages of your Project. Otherwise, the search request does not return any result.
  • value: String - The search term the values of the specified field must match. You can provide several terms separated by whitespaces. With the additional mustMatch parameter you can control whether all of the provided terms must match or any of those.

Optional fields:

  • mustMatch: String

    • any: 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:

If you search for 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"
}
}
}

If you want to search for resources that have either 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"
}
}
}

Note that all the provided search terms must match exactly in 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 - Query field.
  • fieldType : String - SearchFieldType. Must be provided when field is a non-standard field on a resource, like a Product Attribute.
  • language: Locale - Language of the localized value. Must be provided when field is of type localizedTextField. The provided Locale must be one of the languages of your Project. Otherwise, the search request does not return any result.
  • value: String - The search term the values of the specified field must match. You can provide several terms separated by whitespaces.

Optional fields:

  • caseInsensitive: Boolean

    • true: 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:

The following prefix query matches resources with names including card, carton, caravan, or carpet.

{
"query": {
"prefix": {
"field": "name",
"language": "en",
"value": "car"
}
}
}

Searching for 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:

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.

OperatorSymbolBehavior
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.

In the property value you specify the lower or upper boundary for the 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:

You want to find resources that were last modified on the 25 August 2018. For this, you specify the field to search for as 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

With a wildcard query you can use placeholders in values that specify which part of the value does not need to match the search term exactly. Such query expression is suitable when your query should tolerate slight variations in spellings for search terms, like whisky and whiskey. With a wildcard query, you don't need two exact queries for both terms separately, but only one.

wildcard queries are not as efficient as other expressions and should only be used when no other query 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 - Query field.

  • fieldType : String - SearchFieldType. Must be provided when field is a non-standard field on a resource, like a Product Attribute.

  • language: Locale - Language of the localized value. Must be provided when field is of type localizedTextField. The provided Locale must be one of the languages of your Project. Otherwise, the search request does not return any result.

  • value: String - Search term the value of the specified field must match. Use following characters as placeholders:

    • * for zero, one, or more characters
    • ? for exactly one character.

    With the additional caseInsensitive parameter you can control whether casing should be considered or ignored.

Optional fields:

  • caseInsensitive: Boolean

    • true: 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.

The following example query returns results for names written as whisky as well as whiskey.

{
"query": {
"wildcard": {
"field": "name",
"language": "en",
"value": "whisk*y",
"caseInsensitive": true
}
}
}

The following example is similar to the example query for prefix, but this time we are searching for names starting with 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
}
}
}

Multiple wildcards can also be used. The following wildcard query matches resources with names including car, care, cereal, and career.

{
"query": {
"wildcard": {
"field": "name",
"language": "en",
"value": "c?*r",
"caseInsensitive": true
}
}
}

exists

An exists query matches resources that have a field with a non-null value.

Required fields:

The following exists query matches Products that have a value for the Attribute someattribute:

{
"query": {
"exists": {
"field": "variants.attributes.someattribute"
}
}
}

Query fields

Each query expression contains a 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 query expressions for each of those fields.

Find the searchable fields specific to the resource on the respective Search API documentation:

SearchFieldType

Possible values for the fieldType property on query expressions indicating the data type of the field.

boolean

For Boolean fields and AttributeBooleanType Attributes.

text

For string fields and AttributeTextType Attributes.

ltext

For LocalizedString fields and AttributeLocalizableTextType Attributes.

enum

For enum fields and AttributeEnumType Attributes.

lenum

For localized enum fields and AttributeLocalizedEnumType Attributes.

number

For number fields and AttributeNumberType Attributes.

money

For Money fields and AttributeMoneyType Attributes.

date

For Date fields and AttributeDateType Attributes.

datetime

For DateTime fields and AttributeDateTimeType Attributes.

time

For Time fields and AttributeTimeType Attributes.

reference

For Reference fields and AttributeReferenceType Attributes.

set_boolean

For Set of Boolean fields and AttributeSetType of boolean Attributes.

set_text

For Set of string fields and AttributeSetType of text Attributes.

set_ltext

For Set of LocalizedString fields and AttributeSetType of ltext Attributes.

set_enum

For Set of enum fields and AttributeSetType of enum Attributes.

set_lenum

For Set of localized enum fields and AttributeSetType of lenum Attributes.

set_number

For Set of number fields and AttributeSetType of number Attributes.

set_money

For Set of Money fields and AttributeSetType of money Attributes.

set_date

For Set of Date fields and AttributeSetType of date Attributes.

set_datetime

For Set of DateTime fields and AttributeSetType of datetime Attributes.

set_time

For Set of Time fields and AttributeSetType of time Attributes.

set_reference

For Set of Reference fields and AttributeSetType of reference Attributes.

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.

Query expression supported for which type of field

A checkmark indicates which query expression you can use for which type of field.

TypesfullTextexactprefixrangewildcardexists
boolean
long, double, date, dateTime
keyword
text and localizedText
phone

Compound expressions

The outermost layer of the query is a compound expression. This expression specifies how the composition of the sub-expressions is evaluated. Sub-expressions can be query expressions or compound expressions.

The following compound expressions are currently supported:

ExpressionBehavior
andonly matches resources that match all sub-expressions.
oronly matches resources where at least one of the sub-expressions is matched.
notonly matches resources that do not match any of its sub-expressions.
filterMatching 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.

The following example demonstrates an and compound expression query to search for the price of EUR 22.22 on Product Variants. Since prices are combinations of amount and currency, the query is composed of two exact query expressions; one for the currencyCode field and one for the centAmount field of the variants.prices:

{
"query": {
"and": [
{
"exact": {
"field": "variants.prices.currencyCode",
"value": "EUR"
}
},
{
"exact": {
"field": "variants.prices.centAmount",
"value": 2222
}
}
]
}
}

Boosting

If you include multiple query expressions, the optional 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 query expression a higher relevance.

The following query demonstrates how to make results with "butter" in the 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. Sorting allows you to control how results to your query are sorted. If no sorting is specified, the results are sorted by relevance in descending (desc) order.

field
String

Use any searchable field of the resource as sort criterion.

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: en, en-US, zh-Hans-SG.

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.

Allows you to apply a sort filter.

The following example sorts the results ascending by 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

If you sort by a field in an array (like 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 values
  • max - Use the maximum of all available values
  • avg - Use the average of all available values
  • sum - Use the sum of all available values.

If a Product is missing that field, it will be at the last position.

The following example uses 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

If sort modes are not enough to specify exactly which resources or aggregation you want to sort on, use a sort filter.

The following example uses a 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

A response to the search request contains the first 20 results by default. With pagination, you are able to retrieve all the results that exceed this number. The total field in a query result indicates how many results match the search query in total.

Limit

You can set the maximum number of results to return in one page using the limit field. Allowed is a value between 0 and 500. The default limit on search endpoints is 20.

Offset

The offset field allows you to control which page number you want to retrieve. The default value is 0 means that you retrieve the first page of query results containing as many results as specified by limit. A value of 1 means, the first page of results is skipped and your result contains the second bucket of results with the specified limit. The maximum offset is 9900.