Product Search

ProductSearchRequest

{
  "query": {
    "and": [
      {
        "fullText": {
          "field": "name",
          "language": "en",
          "value": "banana"
        }
      },
      {
        "filter": [
          {
            "exact": {
              "field": "variants.attributes.farming",
              "fieldType": "text",
              "value": "organic"
            }
          }
        ]
      }
    ]
  },
  "sort": [
    {
      "field": "name",
      "language": "en",
      "order": "desc"
    }
  ],
  "limit": 10,
  "offset": 0
}

ProductPagedSearchResponse

ProductSearchResult

ProductSearchFacetResult

Query template

The following generic query template ensures compliance with the query validation:

  "query": {
    "and" | "or": [
      <store criterion>,
      <product-selection criterion>,
      <product/variant criterion>,
      <price criterion>
    ]
  }

If your use case requires mixing field levels in compound expressions, you can still formulate valid queries if they follow the validation rules explained in the next section.

Validation logic details

The validation logic checks if all expressions in a compound expression can be combined successfully. When validating a compound expression, the verification is performed iteratively level by level in following order:

Consider following example compound expression in simplified syntax, highlighting the searchable fields and omitting the values.

and(
  exact("stores", ...),
  exact("productSelections", ...),
  or(exact("variants.attributes.color", ...), fullText("description", ...)),
  or(exact("variants.prices.country", ...), exact("variants.prices.channel", ...)),
  exact("variants.prices.currencyCode", ...)
)

Valid compound expressions

• If both expressions are simple expressions on the same field level, the compound result is on single-level with the same rank as the simple expressions.

• If the expressions are simple expressions on different field levels, the compound result is marked as multi-level inheriting the rank of the lowest field level among its constituents.

• If one expression is multi-level and the other expression is single-level on the same level, the compound result is on the same multi-level.

• If one expression is multi-level and the other expression is single-level with a lower rank, the compound result is multi-level with the lowest rank among its constituents.

Invalid compound expressions

• If one expression is multi-level and the other expression is single-level with a higher rank, the query is invalid and the API responds with an InvalidInput error.

• If both expressions are multi-level the query is invalid, regardless of the ranks, and the API responds with an InvalidInput error.

The error message lists the query expressions that failed the query validation. From the searchable fields listed in the error message, you can determine the level for each expression and analyze where it invalidates the query validation.

Expressions nesting level are incompatible:
expr1=
[ and(
      exact("variants.prices.currencyCode", ...),
      exact("variants.prices.channel", ...)
  )
],
expr2=[
  or(
    and(
      fullText("variants.parentProduct.name", ...),
      exact("variants.parentProduct.productType", ...)
    ),
    exact("variants.prices.country", ...)
  )
]

ProductSearchFacetDistinctExpression

ProductSearchFacetDistinctValue

Example:

{
  "facets": [
    {
      "distinct": {
        "name": "sizes",
        "field": "variants.attributes.size",
        "fieldType": "number",
        "limit": 50
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "sizes",
        "buckets": [
          {
            "key": "43",
            "count": 112
          },
          {
            "key": "44",
            "count": 63
          },
          {
            "key": "45",
            "count": 34
          }
        ]
      }
    ]
  }
}

ProductSearchFacetRangesExpression

ProductSearchFacetRangesValue

ProductSearchFacetRangesFacetRange

Example:

{
  "facets": [
    {
      "ranges": {
        "name": "screenDiagonalRanges",
        "field": "variants.attributes.screenDiagonal",
        "fieldType": "number",
        "ranges": [
          {
            "to": 40
          },
          {
            "from": 40,
            "to": 55
          },
          {
            "from": 55
          }
        ]
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "screenDiagonalRanges",
        "buckets": [
          {
            "key": "*-40",
            "count": 33
          },
          {
            "key": "40-55",
            "count": 165
          },
          {
            "key": "55-*",
            "count": 82
          }
        ]
      }
    ]
  }
}

{
  "facets": [
    {
      "ranges": {
        "name": "screenDiagonalRanges",
        "field": "variants.attributes.screenDiagonal",
        "fieldType": "number",
        "ranges": [
          {
            "key": "small",
            "to": 40
          },
          {
            "key": "medium",
            "from": 40,
            "to": 55
          },
          {
            "key": "large",
            "from": 55
          }
        ]
      }
    }
  ]
}

ProductSearchFacetCountExpression

ProductSearchFacetCountValue

ProductSearchFacetCountLevelEnum

Example:

{
  "facets": [
    {
      "count": {
        "name": "all-products"
      }
    },
    {
      "count": {
        "name": "all-variants",
        "level": "variants"
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "all-products",
        "value": 200
      },
      {
        "name": "all-variants",
        "value": 1000
      }
    ]
  }
}

Select specific buckets key

Example:

{
  "facets": [
    {
      "distinct": {
        "name": "categories",
        "field": "categories",
        "includes": [
          "53992aac-cbbf-4b97-bb-09142435e1ea",
          "344c8ceb-01ac-4d76-8f93-bbbc3d0edd5d"
        ]
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "categories",
        "buckets": [
          {
            "key": "53992aac-cbbf-4b97-bb-09142435e1ea",
            "count": 243
          },
          {
            "key": "344c8ceb-01ac-4d76-8f93-bbbc3d0edd5d",
            "count": 12
          }
        ]
      }
    ]
  }
}

Missing values

Example:

{
  "facets": [
    {
      "distinct": {
        "name": "states",
        "field": "state",
        "missing": "N/A",
        "limit": 50
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "states",
        "buckets": [
          {
            "key": "N/A",
            "count": 112
          },
          {
            "key": "995c735c-ad07-4d22-a35b-34e8f5238fd74",
            "count": 63
          },
          {
            "key": "fb77d7dc-94c5-45df-95bc-b8499286e4d55",
            "count": 34
          }
        ]
      }
    ]
  }
}

Sort buckets in the facets results

Count entity for distinct and ranges facet

Example:

 "facets": [
    {
      "distinct": {
        "name": "sizesByProducts",
        "fieldType": "number",
        "field": "variants.attributes.size",
        "count": "products"
      }
    },
    {
      "distinct": {
        "name": "sizesByVariants",
        "fieldType": "number",
        "field": "variants.attributes.size",
        "count": "variants"
      }
    }
  ]

Scope of facets

By default, all facets run in the scope of a query. That means if you query, for example, for Products that have been last modified before a certain date and in that same query you have a facet, this facet will only count Products that match the query.

Large number of Standalone Prices

For each Product in the Project:

1. Calculate variant limit by dividing 10 000 by the number of Variants on the Product.
2. fetch Prices for all Variants.
3. for each Variant:

• sort Prices by

  • currency (alphabetically by the value.currencyCode)
  • country (alphabetically, missing field is sorted as first)
  • channel (alphabetically by key, missing field is sorted as first)
  • Customer Group (alphabetically by key, missing field is sorted as first)
• truncate Prices that are beyond the variant limit

Prices with validity dates

By default, prices with validity dates are not supported. This means that prices are not automatically updated in the search index upon reaching a validity date.

Language settings

Supported languages