# Search query language Syntax description of the search query language. This page lists the query expressions and the operators that the Search APIs have in common. Find the resource-specific elements of the query language, like searchable fields, on the respective API reference page: - [Product Search](/api/projects/product-search.md) - [Customer Search](/api/projects/customer-search.md) - [Order Search](/api/projects/order-search.md) - [Business Unit Search](/api/projects/business-unit-search.md) A search request submitted as payload on a Search API is a JSON object that contains the following fields: - `query` - [SearchQuery](/api/search-query-language.md#searchquery) - Required A simple expression or compound expression. - `sort` - Array of [SearchSorting](/api/search-query-language.md#searchsorting) - Optional The parameters for sorting search results. - `limit` - Number - Optional The [limit](/api/search-query-language.md#limit) parameter for pagination. - `offset` - Number - Optional The [offset](/api/search-query-language.md#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](/api/general-concepts.md#limit) to the first 20 resources matching the query. ```json { "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: - A single [simple expression](/api/search-query-language.md#simple-expressions), like `exact` or `fullText`, or - A [compound expression](/api/search-query-language.md#compound-expressions) wrapper, like `and`, `or`, `not`, `filter`, which contains a list of simple expressions. A SearchQuery can contain up to **50** simple or compound expressions. String-type values in simple 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`: ```json { "query": { "and": [ { "fullText": { "field": "name", "language": "en", "value": "banana" } }, { "filter": [ { "exact": { "field": "variants.attributes.someattribute", "fieldType": "text", "value": "12" } } ] } ] } } ``` ### Simple expressions Simple expressions specify a search query for a single [searchable field](/api/search-query-language.md#searchable-fields). 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 type | Field name | Example use case | | --- | --- | --- | | [exists](/api/search-query-language.md#exists) | `exists` | Checks whether a specified field has a non-null value. | | [exact](/api/search-query-language.md#exact) | `exact` | Performs exact match on values of a specified field. | | [prefix](/api/search-query-language.md#prefix) | `prefix` | Searches for values starting with a specified prefix. | | [range](/api/search-query-language.md#range) | `range` | Searches for values within a specified range. | | [wildcard](/api/search-query-language.md#wildcard) | `wildcard` | Searches for values with specified wildcards. | | [fullText](/api/search-query-language.md#fulltext) | `fullText` | Performs full-text search on a specified field. | | [fuzzy](/api/search-query-language.md#fuzzy) | `fuzzy` | Searches for values with minor spelling variations. | #### exists An `exists` query matches resources that have a field with a non-null value. Required fields: - `field`: String - [Searchable field](/api/search-query-language.md#searchable-fields). - `fieldType` : String - [SearchFieldType](/api/search-query-language.md#searchfieldtype). Must be provided when `field` is a non-standard field on a resource, like a Product [Attribute](/search.md?urn=ctp:api:type:Attribute). For [Order Search](/api/projects/order-search.md), you must provide `customType`: String - [CustomType](/api/projects/order-search.md#customtype) instead if `field` is a [Custom Field](/api/projects/custom-fields.md). The following `exists` query matches Products that have a value for the Attribute `someattribute`: ```json { "query": { "exists": { "field": "variants.attributes.someattribute" } } } ``` #### 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](/api/search-query-language.md#fulltext) expression instead. A [prefix](/api/search-query-language.md#prefix) expression is suitable when `yellow car` should match `yellow cars` also. Required fields: - `field`: String - [Searchable field](/api/search-query-language.md#searchable-fields). - `fieldType` : String - [SearchFieldType](/api/search-query-language.md#searchfieldtype). Must be provided if `field` is a non-standard field on a resource, like a Product [Attribute](/search.md?urn=ctp:api:type:Attribute). For [Order Search](/api/projects/order-search.md), you must provide `customType`: String - [CustomType](/api/projects/order-search.md#customtype) instead if `field` is a [Custom Field](/api/projects/custom-fields.md). - `language`: [Locale](/api/types.md#locale) - Language of the localized value. Must be provided when `field` is of [type](/api/search-query-language.md#types-of-fields) `localizedTextField`. The provided Locale must be one of the `languages` of your [Project](/api/projects/project.md#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`: 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 `caseInsensitive`parameter is set to`true`. ```json { "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. ```json { "query": { "exact": { "field": "key", "values": ["KEY101", "KEY102", "KEY201"], "caseInsensitive": true } } } ``` #### prefix Searches for values that start with a specified prefix. Required fields: - `field`: String - [Searchable field](/api/search-query-language.md#searchable-fields). - `fieldType` : String - [SearchFieldType](/api/search-query-language.md#searchfieldtype). Must be provided when `field` is a non-standard field on a resource, like a Product [Attribute](/search.md?urn=ctp:api:type:Attribute). For [Order Search](/api/projects/order-search.md), you must provide `customType`: String - [CustomType](/api/projects/order-search.md#customtype) instead if `field` is a [Custom Field](/api/projects/custom-fields.md). - `language`: [Locale](/api/types.md#locale) - Language of the localized value. Must be provided when `field` is of [type](/api/search-query-language.md#types-of-fields) `localizedTextField`. The provided Locale must be one of the `languages` of your [Project](/api/projects/project.md#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`. ```json { "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: - `field`: String - [Searchable field](/api/search-query-language.md#searchable-fields). - `fieldType` : String - [SearchFieldType](/api/search-query-language.md#searchfieldtype). Must be provided when `field` is a non-standard field on a resource, like a Product [Attribute](/search.md?urn=ctp:api:type:Attribute). For [Order Search](/api/projects/order-search.md), you must provide `customType`: String - [CustomType](/api/projects/order-search.md#customtype) instead if `field` is a [Custom Field](/api/projects/custom-fields.md). 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. | 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](/api/types.md#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: ```json { "query": { "range": { "field": "lastModifiedAt", "gte": "2018-08-25T12:00:00.000Z", "lt": "2018-08-26T12:00:00.000Z" } } } ``` #### wildcard With a `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](/api/search-query-language.md#prefix) expression is sufficient and should be applied instead. Required fields: - `field`: String - [Searchable field](/api/search-query-language.md#searchable-fields). - `fieldType` : String - [SearchFieldType](/api/search-query-language.md#searchfieldtype). Must be provided when `field` is a non-standard field on a resource, like a Product [Attribute](/search.md?urn=ctp:api:type:Attribute). For [Order Search](/api/projects/order-search.md), you must provide `customType`: String - [CustomType](/api/projects/order-search.md#customtype) instead if `field` is a [Custom Field](/api/projects/custom-fields.md). - `language`: [Locale](/api/types.md#locale) - Language of the localized value. Must be provided when `field` is of [type](/api/search-query-language.md#types-of-fields) `localizedTextField`. The provided Locale must be one of the `languages` of your [Project](/api/projects/project.md#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`. ```json { "query": { "wildcard": { "field": "name", "language": "en", "value": "whisk*y", "caseInsensitive": true } } } ``` The following example is similar to the example query for [prefix](/api/search-query-language.md#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: ```json { "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 `career`, `corner`, `cursor`, and `corr`. ```json { "query": { "wildcard": { "field": "name", "language": "en", "value": "c?r*r", "caseInsensitive": true } } } ``` #### fullText Performs a full text search on the specified `field`. Required fields: - `field`: String - [Searchable field](/api/search-query-language.md#searchable-fields). - `fieldType` : String - [SearchFieldType](/api/search-query-language.md#searchfieldtype). Must be provided when `field` is a non-standard field on a resource, like a Product [Attribute](/search.md?urn=ctp:api:type:Attribute). For [Order Search](/api/projects/order-search.md), you must provide `customType`: String - [CustomType](/api/projects/order-search.md#customtype) instead if `field` is a [Custom Field](/api/projects/custom-fields.md). - `language`: [Locale](/api/types.md#locale) - Language of the localized value. Must be provided when `field` is of [type](/api/search-query-language.md#types-of-fields) `localizedTextField`. The provided Locale must be one of the `languages` of your [Project](/api/projects/project.md#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`: ```json { "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`: ```json { "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](/api/search-query-language.md#prefix) search instead. #### fuzzy A `fuzzy` search expression matches resources that contain terms similar to the search term, allowing for slight variations such as typos or minor character differences. This is useful when you want to find results even if the user makes small spelling mistakes. The API automatically adjusts the effective fuzziness level based on the length of the search term to maintain relevance and to prevent excessively broad matches for short search terms. As a result, clients do not need to manually validate or constrain the level based on term length. `fuzzy` expressions are not as efficient as other expressions and should only be used when no other expression is applicable for your use case. In most cases, a [fullText](/api/search-query-language.md#fulltext) or an [exact](/api/search-query-language.md#exact) expression is sufficient for handling common search requirements. **Usage guidelines for fullText and fuzzy search:** - Use `fullText` search for longer text fields, such as product descriptions or detailed content, where users are likely to enter multiple words or phrases. - Apply `fuzzy` search primarily to short fields that users type directly, such as product names, SKUs, or attributes like color. Fuzzy search helps account for typos or minor spelling mistakes. - We suggest limiting the use of `fuzzy` expressions to 10 per query to maintain good performance and relevance. - Avoid using `fuzzy` search indiscriminately across all fields, as it can negatively impact performance and may return less relevant results. - Combine `fullText` and `fuzzy` in queries when you want to balance precision and tolerance for user input errors. For example, use an `OR` expression to search both the exact term (with `fullText` and a `boost`) and a fuzzy match for user-entered fields: ```json { "query": { "or": [ { "fullText": { "field": "name", "language": "en", "value": "shoes", "boost": 3 } }, { "fuzzy": { "field": "name", "language": "en", "value": "shoes", "level": 1 } } ] } } ``` - It can be helpful in cases where users might enter free text fields (e.g.: search bar in storefront applications). For example, imagine users searching for "Red Shoes": you can craft a query that searches the product name with `fuzzy` (e.g.: "Shoes") and the color attribute with `fuzzy` (e.g.: "red"), using `mustMatch: "any"` to combine the expressions for each field, e.g.: ```json { "query": { "and": [ { "fuzzy": { "field": "name", "language": "en", "value": "red shoes", "level": 1, "mustMatch": "any" } }, { "fuzzy": { "field": "variants.attributes.color", "fieldType": "text", "value": "red shoes", "level": 1, "mustMatch": "any" } } ] } } ``` Anti-patterns: - Do not use `fuzzy` on long text fields, as it can lead to irrelevant matches and performance issues. - Avoid combining multiple fuzzy expressions without clear intent, as this can degrade both relevance and speed. In summary, use `fullText` for comprehensive text matching, and apply `fuzzy` selectively to user-input fields to improve search experience without sacrificing performance. Required fields: - `field`: String - [Searchable field](/api/search-query-language.md#searchable-fields). - `fieldType` : String - [SearchFieldType](/api/search-query-language.md#searchfieldtype). Must be provided when `field` is a non-standard field on a resource, like a Product [Attribute](/search.md?urn=ctp:api:type:Attribute). - `language`: [Locale](/api/types.md#locale) - Language of the localized value. Must be provided when `field` is of [type](/api/search-query-language.md#types-of-fields) `localizedTextField`. The provided Locale must be one of the `languages` of your [Project](/api/projects/project.md#project). Otherwise, the search request does not return any result. - `value`: String - The search term you want to find fuzzy matches for. - `level`: Number - The maximum [fuzziness level](/api/search-query-language.md#fuzziness-level) desired for the search term provided with the `value`. Allowed values are `0`, `1`, and `2`, but the API will adjust the fuzziness level per search term if it exceeds the maximum allowed for the given string length according to the following rules: - Terms with 1–2 characters: `0` (exact match). - Terms with 3–5 characters: `1` (up to one difference is allowed). - Terms with more than 5 characters: `2` (up to two differences are allowed). Example: If you search for the term "shert" (5 characters) and set `level` to `2`, the system will automatically adjust the level to `1`, which is the maximum allowed for a 5-character string. The search will then match terms with only one substitution, for example, "shirt." ```json title="Fuzziness level higher than allowed is automatically adjusted to maximum" { "query": { "fuzzy": { "field": "name", "language": "en", "value": "shert", // 5 characters "level": 2 // --> 1 } } } ``` Optional fields: - `mustMatch`: String - Controls whether all of the provided terms must match or any of those. - `all` (default): Returns only those resources for which all the provided search terms match. - `any`: Returns resources for which at least one of the provided search terms match. If `value` contains multiple search terms, the fuzziness level is applied to each term individually. Example: Consider the following query, which searches for products with a name similar to `grean handbg` with a desired fuzziness level of `2`. The API will adjust the fuzziness level for `grean` to `1` because that is the maximum level for terms with a length of 5 characters. The fuzziness level for `handbg` stays at `2` because the term has more than 5 characters. The query will return Products for which `green handbag` matches successfully. ```json title="Example query with fuzziness level of 2 for multiple search terms" { "query": { "fuzzy": { "field": "name", "language": "en", "value": "grean handbg", "level": 2, "mustMatch": "all" } } } ``` The fuzziness level defines the maximum allowable [Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) between the search term and the results. It is the number of single-character edits (insertions, deletions, or substitutions) required to change one word into the other. ### Compound expressions Compound expressions let you compose higher-order queries out of [simple expressions](/api/search-query-language.md#simple-expressions) (or other compound expressions), combined according to logical rules such as AND, OR, and NOT. Each sub-expression is evaluated on its own, and the compound expression's logical rule determines how the individual results are combined to produce the final match. When using a compound expression, its sub-expressions — simple or compound — are specified as an array, given as the value of the field naming the logical operator. The following compound expressions are currently supported: | Expression type | Operator | Behavior | | --- | --- | --- | | [AND](/api/search-query-language.md#and-expression) | `and` | Only matches resources that match all sub-expressions. | | [OR](/api/search-query-language.md#or-expression) | `or` | Only matches resources where at least one of the sub-expressions is matched. | | [NOT](/api/search-query-language.md#not-expression) | `not` | Only matches resources that do not match any of its sub-expressions. Can be used to express "all array elements match" logic. | | [Filter](/api/search-query-language.md#filter-expression) | `filter` | Use filter expressions if you don't need to [sort](/api/search-query-language.md#searchsorting) your results by relevance score. | #### AND expression All sub-expressions of an `and` compound expression must match for the overall expression to match. The relevance score is calculated based on the combined relevance of all sub-expressions. The following example shows an `and` compound expression query to find Product Variants that are blue **and** size L. ```json title="Example query with an AND compound expression" { "query": { "and": [ { "exact": { "field": "variants.attributes.color.key", "fieldType": "enum", "value": "blue" } }, { "exact": { "field": "variants.attributes.size.key", "fieldType": "enum", "value": "l" } } ] } } ``` #### OR expression An `or` compound expression matches if at least one of its sub-expressions matches. Each matching sub-expression contributes to the relevance score. For example, a resource matching two sub-expressions will be more relevant than one matching only one sub-expression. Do not wrap a single sub-expression in an `or` expression, such an expression is rejected with a `400 MalformedQuery` error. The following example shows an `or` compound expression query to find Product Variants that are either UK size 4 **or** Euro size 37. ```json title="Example query with an OR compound expression" { "query": { "or": [ { "exact": { "field": "variants.attributes.uk-shoesize.key", "fieldType": "enum", "value": "4" } }, { "exact": { "field": "variants.attributes.euro-shoesize.key", "fieldType": "enum", "value": "37" } } ] } } ``` If you want to search for multiple OR-combined values for the same `field`, you can specify them in the `values` of an [exact](/api/search-query-language.md#exact) simple expression instead. This reduces the number of expressions that count toward the 50 expressions limit in a query. The following example shows a query for Product Variants that are either blue, red, or green. ```json title="Example query for multiple allowed values on the same field with a simple expression" { "query": { "exact": { "field": "variants.attributes.color.key", "fieldType": "enum", "values": ["blue", "red", "green"] } } } ``` #### NOT expression Matches resources that do not match any of its sub-expressions. In other words, all sub-expressions must be `false` to match the `not` expression. All sub-expressions are evaluated on the **same entity** on the **same nesting level**, for example, for the same Product Variant, or the same Embedded Price. The following example shows a `not` compound expression that excludes specific results in Order Search. The query returns Orders that do not have any Line Item in the `cancelled` State. The single sub-expression is an [exact](/api/search-query-language.md#exact) expression on the `lineItems.state.state.key` searchable field directly placed inside the `not` compound expression. ```json title="Example query with a NOT compound expression" { "query": { "not": [ { "exact": { "field": "lineItems.state.state.key", "value": "cancelled" } } ] } } ``` If you want to express that **all elements of a collection** match a certain condition, you can use `not` to exclude the complement, meaning any resource that has at least one element that does not match the condition. For example, to find Orders where every Line Item is in the `shipped` State, exclude Orders that have any Line Item in any other State key used in your Project (for example, `picking`, `backorder`, or `cancelled`). To make this logic complete, list all other possible State keys in the `values` field of an [exact](/api/search-query-language.md#exact) expression and negate it with a `not` operator: ```json title="Example query for all elements of a collection matching a certain condition" { "query": { "not": [ { "exact": { "field": "lineItems.state.state.key", "values": ["picking", "backorder", "cancelled"] } } ] } } ``` This approach only works when the field has a closed set of possible values, like `lineItems.state.state.key` in the example above. It does not work on open-ended fields like `lineItems.name`, where you cannot know all possible values in advance. #### Filter expression Filter expressions perform faster since no relevance score is calculated, they are evaluated to match or no-match only. If a filter expression has more than one sub-expression, they are logically evaluated like an `and` expression. The following example shows a `filter` compound expression query to find Product Variants that are blue **and** size L. ```json title="Example query with a filter compound expression" { "query": { "filter": [ { "exact": { "field": "variants.attributes.color.key", "fieldType": "enum", "value": "blue" } }, { "exact": { "field": "variants.attributes.size.key", "fieldType": "enum", "value": "l" } } ] } } ``` ### Searchable fields Each [simple expression](/api/search-query-language.md#simple-expressions) 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 simple expressions for each of those fields. Find the searchable fields specific to the resource on the respective Search API documentation: - [Product](/api/projects/product-search.md#searchable-product-fields) - [Customer Search](/api/projects/customer-search.md#searchable-customer-fields) - [Order Search](/api/projects/order-search.md#searchable-order-fields) - [Business Unit Search](/api/projects/business-unit-search.md#searchable-business-unit-fields) #### SearchFieldType [type definition](/search.md?urn=ctp:api:type: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](/api/types.md#date) fields. - **dateTime**: for [DateTime](/api/types.md#datetime) fields. - **keyword**: for fields holding unique [identifiers](/api/general-concepts.md#identifier). - **text**: for string fields. - **localizedText**: for [LocalizedString](/api/types.md#localizedstring) fields. - **phone**: for phone numbers containing non-numerical characters for formatting. #### Simple expression supported for which type of field A checkmark indicates which [simple expression](/api/search-query-language.md#simple-expressions) you can use for which [type of field](/api/search-query-language.md#types-of-fields). | Types | [fullText](/api/search-query-language.md#fulltext) | [exact](/api/search-query-language.md#exact) | [prefix](/api/search-query-language.md#prefix) | [range](/api/search-query-language.md#range) | [wildcard](/api/search-query-language.md#wildcard) | [fuzzy](/api/search-query-language.md#fuzzy) | [exists](/api/search-query-language.md#exists) | | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | **boolean** | | ✓ | | | | | ✓ | | **long**, **double**, **date**, **dateTime** | | ✓ | | ✓ | | | ✓ | | **keyword** | | ✓ | ✓ | | ✓ | ✓ | ✓ | | **text** and **localizedText** | ✓ | ✓ | ✓ | | ✓ | ✓ | ✓ | | **phone** | ✓ | ✓ | ✓ | | | | ✓ | ### Boost query results If you include multiple simple 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 simple 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`. ```json { "query": { "or": [ { "fullText": { "field": "name", "language": "en", "value": "butter", "boost": 2 } }, { "fullText": { "field": "description", "language": "en", "value": "butter" } } ] } } ``` ## SearchSorting [type definition](/search.md?urn=ctp:api:type:SearchSorting). The following example sorts the results ascending by `createdAt`: ```json { "sort": [ { "field": "createdAt", "order": "asc" } ] } ``` ### Sort order [type definition](/search.md?urn=ctp:api:type:SearchSortOrder). ### 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: ```json { "sort": [ { "field": "variants.prices.centAmount", "language": "en", "order": "desc", "mode": "min" } ] } ``` ### Sort filter The `sort.filter` field filters which resources should be sorted, without removing them from the search results. Resources that don't match the `sort.filter` criteria appear at the bottom of the list in an undetermined order if no subsequent sort definitions determine their order. The following example uses a sort filter to prioritize sorting Products in the Category whose `id` is `4054a159-7f3e-4fe9-a30c-8db80ca7d665`. ```json title="Example sort filter for particular Category" { "sort": [ { "field": "name", "language": "en", "order": "asc", "filter": { "exact": { "field": "categories", "value": "4054a159-7f3e-4fe9-a30c-8db80ca7d665" } } } ] } ``` Compound expressions can be used to express complex sorting conditions. The following example uses a `filter` to sort on prices scoped to Channel whose `id` is `fb16244b-3963-4b9e-9cb0-69a1f563a854` and to currency `EUR`. ```json { "sort": [ { "field": "variants.prices.centAmount", "filter": { "and": [ { "exact": { "field": "variants.prices.channel", "value": "fb16244b-3963-4b9e-9cb0-69a1f563a854" } }, { "exact": { "field": "variants.prices.currencyCode", "value": "EUR" } } ] }, "order": "asc" } ] } ``` Results that do not match the filter condition will be positioned at the tail of the result with an undefined order. It's advisable to only use sort filters for criteria that are already present in the query or postFilter, thus guaranteeing a matching sort value is found. In case this is not feasible, subsequent sort definitions may be used to define the order of products that did not match the previous sort filters. ## Pagination A response to the search request contains the first 20 results by default. Pagination allows you to retrieve the first 10000 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 With the `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 The `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. The maximum allowed `offset` is `9900`. When combined with the maximum `limit` of `100`, this allows you to retrieve the first 10000 results in total. Setting pagination parameters exceeding this limit will result in an [InvalidInput](/search.md?urn=ctp:api:type:InvalidInputError) error with the message "Pagination cannot be used to fetch more than the first 10000 results." ## Related pages - [Area overview page with navigation](/api.md) - [Previous page: Query Predicates](/api/predicates/query.md) - [Next page: Errors](/api/errors.md) - [Search documentation and API specs](/search.md)