Advanced Product Search - beta

Advanced searching using the product list. This feature is marked as beta and may be affected by changes.

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, but there are other optional fields.
{

  "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 relationship 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, like lastModifiedAt
  • 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 an gte specified and searches from the gte date forwards.

For example, the following query searches for products last modified between August 25, 2019 and August 26, 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

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

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

  • field - String - Required
    The name of the field to search for. For more information, see Searchable fields.
  • value - String(?) - Required //TODO: String?
    The value to search for.
  • language - String - Optional
    An IETF 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.
    If true, 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 //TODO: 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"
    }
  }
}