Advanced Product Search

Query objects

A query object consists of the following:

• 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, whereas the other fields are optional.

{

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

      ...

      ]
  }

 ...

}

Compound expressions

A compound expression is the outermost layer of a query and indicates how the query expressions inside the query are 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 with a price of 222.20 Euro. Hence, the currencyCode 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

A query expression wraps the actual data of a query and defines how a search is conducted.

{
  "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

A fullText query performs full-text searches of fields. Full-text searches use the fields specified in the Query body and have the option of using the mustMatch field.

For example, the following query searches for Products that have either green or handbag in their name. Hence, Products with the name yellow handbag and green shoes match.

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

exact

Anexact query searches for exact values only. Exact searches use the fields specified in the Query body and have the option of using the caseInsensitive field.

For example, the following query returns any SKU that exactly matches the value field. Hence, Chiquita_yellow_123 and chiquita_YELLOW_123 match, but not chiquita_yellow_1234.

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

prefix

A prefix query searches for values of fields that begin with the specified prefix. Prefix searches use the fields specified in the Query body and have the option of using the caseInsensitive field.

For example, the following search returns Products that begin with commerceto. Hence, Products that begin with commerce do not match.

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

range

A range query only matches values between specified boundaries and 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 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 query searches for values of fields that match the specified wildcard expression. Wildcard searches use the fields specified in the 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

A exists query 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, see Searchable fields.

• value - String - Required
  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
  Use with fullText searches only. It can either be any or all.

  • If you use all, and search with a value of yellow car, the full text search matches Products that have both yellow and car anywhere in the searched field.
  • If you use any, the full text search matches Products that have yellow or car in the searched field.

• caseInsensitive - Boolean - Optional
  Use with exact, prefix and wildcard searches only. If true, the search is treated as case insensitive. For example, a case insensitive search for Yellow Car matches a field with yellow car.

Searchable fields

You can access any direct field of a Product Projection, Product Type or Attribute definition, or a sub-field of a referenced or nested object in some cases.

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

You can access any field on a ProductProjection, 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 be searched 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.

You can access any field on a ProductType, 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 AttributeDefinition, accessed using attributes.name or attributes.label, where name and label are the fields being accessed.

boost field

When you provide more than one query expression to a query, the boost field adds more importance to a query result than the others.

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

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

Filters

A query can 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: uses the minimum of all available values.
  • max: uses the maximum of all available values.
  • avg: uses the average of all available values.
  • sum: uses 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

A query can have the optional pagination information that includes 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"
    }
  }
}