Search query language

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:

• A single query expression, like exact or fullText, or
• A compound expression wrapper, like and, or, not, filter, which contains a list of query expressions.

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:

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 if field is a non-standard field on a resource, like a Product Attribute.

  For Order Search, you must provide customType: String - CustomType instead if field is a Custom Field.

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

• values BETA: Array of String - List of search terms. At least one of the terms must match the specified field 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.

  Either value or values must be provided. values must not be empty.

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 key = KEY101. This query also returns resources that have the lowercased version of the value (key101) since the caseInsensitiveparameter is set totrue.

{
  "query": {
    "exact": {
      "field": "key",
      "value": "KEY101",
      "caseInsensitive": true
    }
  }
}

The following example query searches for multiple resources, that have a key of 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

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.

  For Order Search, you must provide customType: String - CustomType instead if field is a Custom Field.

• 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"
    }
  }
}

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.

  For Order Search, you must provide customType: String - CustomType instead if field is a Custom Field.

• 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"
    }
  }
}

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 - Query field.

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

  For Order Search, you must provide customType: String - CustomType instead if field 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.

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.

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.

  For Order Search, you must provide customType: String - CustomType instead if field is a Custom Field.

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

• field: String - Query field.

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

  For Order Search, you must provide customType: String - CustomType instead if field is a Custom Field.

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:

• Product
• Customer Search
• Order Search BETA
• Business Unit Search BETA

SearchFieldType

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.

Query expression supported for which type of field

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

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:

The following example shows an 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 query 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"]
        }
      }
    ]
  }
}

The last 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.

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

The following example sorts the results ascending by createdAt:

{
  "sort": [
    {
      "field": "createdAt",
      "order": "asc"
    }
  ]
}

Sort order

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"
        }
      }
    }
  ]
}

Pagination

A response to the search request contains the first 20 results by default (10 results for Order Search). 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

The limit field allows you to set the maximum number of results returned on a page. Any value between 0 and 100 is allowed. The default limit for search APIs is 20, except for Order Search, where it is 10.

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.