Advanced Product Search

Advanced searching using the product list.

You can use the search-toggle search toggle button to switch between basic search mode (magnifying glass) and advanced search mode.

Advanced search mode lets you construct a detailed query and gives you more control over what you can search for.

You can switch a basic search to an advanced search, but you cannot switch an advanced search to a basic search.

Queries consist of the following:

  • A query section, which describes the data to search for and what filters to apply to results.
  • An optional sort section, which describes how to sort search results.
  • An optional pagination section, which contains information about how to paginate search results.

Query objects

A query consists of:

  • A compound expression wrapper, in this example or.
  • A query expression, in this example fullText. You can use more than one query expression per query.
  • A set of query fields. The field and value fields are required, the other fields are optional.
{

  "query": {
      "or": [
        "fullText": {
          "field": "variants.name",
          "value": "DNKY"
        },

      ...

      ]
  }

 ...

}

Compound expressions

The outermost layer of the query is a compound expression. This keyword indicates how the query expressions inside the query will be evaluated in relation to each other.

{
  "query": {
    "and": [ // This is the compound expression

        ...

    ]
  }
}

You can use the following compound expressions:

  • and Only matches products that match all query expressions.
  • or Matches products that match at least one query expression.
  • not Matches products that do not match any query expressions

For example: the following query only matches product variants that have a price of 222.20 euro. The currency code must be EUR and the centAmount must be 2222.

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

Query expressions

The query expression defines exactly how a search is conducted, and always wraps the actual data of a query as follows:

{
  "query" {
    "or": [
      "exact": { //This is a query expression
        ...
      },
      "fullText": { //This is a query expression
        ...
      }
    ]
  }
}

You can use the following types:

  • fullText
  • exact
  • prefix
  • range
  • wildcard
  • exists

fullText

Performs a full text search of the field.

Full text searches use the fields specified in Query body, and have the option of using the mustMatch field.

For example, the following query searches for products which have either green or handbag in their name. A product with the name yellow handbag will match, as will green shoes.

{
  "query": {
    "fullText": {
      "field": "name",
      "language": "en",
      "value": "green handbag",
      "mustMatch": "any"
    }
  }
}

exact

Searches for exact values only. If you provide a value of yellow car, a field with yellow cars will not match.

Exact searches use the fields specified in Query body, and have the option of using the caseInsensitive field.

For example, the following search will return any SKU which exactly matches the value field. Chiquita_yellow_123 and chiquita_YELLOW_123 will match, but chiquita_yellow_1234 will not.

{
  "query": {
    "exact": {
      "field": "variants.sku",
      "value": "chiquita_yellow_123",
      "caseInsensitive": true
    }
  }
}

prefix

Searches the field specified for ones that begin with the prefix specified.

Prefix searches use the fields specified in Query body, and have the option of using the caseInsensitive field.

For example, the following search will only return products which begin with commerceto. Products that begin with commerce will not match.

{
  "query": {
    "prefix": {
      "field": "variants.attributes.brand",
      "attributeType": "text",
      "value": "commerceto",
      "caseInsensitive": true
    }
  }
}

range

A range query only matches values between the specified boundaries. This query type works with date and number values.

Range queries use the following fields:

  • field - String - Required Any DateTime field, likelastModifiedAt
  • gte - DateTime - Optional Lower bound of the range query. If omitted, the query body must have an lte specified and searches from the lte date backwards.
  • lte - DateTime - Optional Upper bound of the range query. If omitted, the query body must have a gte specified and searches from the gte date forwards.

For example, the following query searches for products last modified between 25 August 2019 and 26 August 2019.

{
  "query": {
    "range": {
      "field": "lastModifiedAt",
      "gte": "2019-08-25T12:00:00.000Z",
      "lte": "2019-08-26T12:00:00.000Z"
     }
  }
}

wildcard

A wildcard search matches products that have fields matching the specified wildcard expression.

Wildcard searches use the fields specified in Query body, and have the option of using the caseInsensitive field.

In wildcard searches, the following characters have a special meaning when used as a part of the value:

  • * for one or more characters
  • $ for exactly one character.
{
  "query": {
    "wildcard": {
      "field": "name",
      "value": "ki*y"
    }
  }
}
{
  "query": {
    "wildcard": {
      "field": "name",
      "value": "kit$y",
      "caseInsensitive": true
    }
  }
}

exists

Searches for fields that have a non-null value. The only field required is field.

{
  "query": {
    "exists": {
      "field": "name"
    }
  }
}

Query body

A query expression can use the following fields in its body:

  • field - String - Required The name of the field to search for. For more information, seeSearchable fields.
  • value - String - Required The value to search for.
  • language - String - Optional AnIETF language tag. Use only when searching for product data in a specific language.
  • attributeType - String - Optional The attribute type. Use only when the field specified is a product variant attribute (product.attribute.<attribute-name>). Allowed values are:
    • text, set_text
    • boolean, set_boolean
    • ltext, set_ltext
    • enum
    • lenum
    • number, set_number
    • money, set_money
    • date, set_date
    • time, set_time
    • datetime, set_datetime
    • reference, set_reference
  • boost - Number - Optional Makes a query expression count more towards the relevance score in relation to other query expressions.
  • mustMatch - String - Optional Default value: all Use with fullText searches only. Can either be any or all. If you use all, and search with a value of yellow car the full text search matches products which have both yellow and car anywhere in the searched field. If you use any, the full text search matches products which have yellow or car in the searched field.
  • caseInsensitive - Boolean - Optional Use with exact, prefix and wildcard searches only. Iftrue, treats the search as case insensitive. For example, a case insensitive search for Yellow Car will match a field with yellow car.

Searchable fields

You can access any direct field of a product projection, product type or attribute definition, or in some cases a sub-field of a referenced or nested object.

The field accessed must be a JSON data type. The only exception to this is LocalizedString fields, which is treated differently.

Any field on a Product Projection which is:

  • A simple JSON data type, such as id or key
  • A field on a referenced type or array of a type, such as variants.sku, or taxCategory.name.
  • A LocalizedString. If so, use the language field to specify the language to search in.
  • A field on a product variant price, accessed using the format variants.prices.currencyCode, where currencyCode is the field accessed.
  • A product variant attribute, accessed using variants.attributes.<attribute_name>. If so, use the attributeType field to specify the attribute type.

Any field on a Product Type which is:

  • A simple JSON data type, such as id or key.
  • A LocalizedString. If so, use the language field to specify the language to search in.
  • Any field on an Attribute Definition, accessed using attributes.name or attributes.label, where name and label are the fields being accessed.

Using the boost field

When you provide more than one query expression to a query, the boost field makes the results that match one query more important than the results that match the others.

For example: in this query, results that have butter in the name field are more important than those that have butter in their description.

{
  "query": {
    "or": [
      {
        "fullText": {
          "field": "name",
          "language": "en",
          "value": "butter",
          "boost": 2
        }
      },
      {
        "fullText": {
          "field": "description",
          "language": "en",
          "value": "butter"
        }
      }
    ]
  }
}

Filters

A query can optionally have a filter section. The filter contains fullText, exact or prefix query expressions as described above, and filters for the field described. All sub-expressions contained in a filter are connected with and logic. All sub-expressions of query count towards the score except for filter.

{
  "query": {
    "and": [
      {
        ... //query expressions here
      },
      {
        "filter": [
          {
            "exact": {
              "field": "categories.id",
              "value": "cd2c2b6b"
            }
          }
        ]
      }
    ]
  },

Sort

A query can have the optional sort object after it. The sort object defines how the query is sorted and displayed in the Product List.

The sort object contains the following:

  • field - String - Required The name of the field to sort by. For more information, see Searchable fields. You can also use the internal field score, in addition to the internal field set to true, to sort by the weighted score.
  • order - String - Required The sort order. Can either be asc (ascending) or desc (descending).
  • mode - String - Optional The sort mode to use. Allowed values are:
    • 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.
  • attributeType - String - Optional The attribute type. Use only when the field is a product attribute.
  • internal - Boolean - Optional Set this to true when field is set to score.
{
  "query": {
      ...
  },
  "sort": {
    "field": "name",
    "order": "desc"
  }
}

Pagination

The pagination information is optional and can include the following fields:

  • limit - Number - Required Set the upper limit of items to return
  • offset - Number - Required Set the offset from which the query is evaluated.

Query object examples

Find products with a specific price:

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

Find a product with a shirtColor attribute value of Green:

{
  "query": {
    "fullText": {
      "field": "variants.attributes.shirtColor",
      "value": "Green",
      "attributeType": "set_text"
    }
  }
}