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
      }
    ]
  }
}

ProductSearchFacetStatsExpression

ProductSearchFacetStatsValue

Example:

{
  "facets": [
    {
      "stats": {
       "name": "pricesStatsVariants",
       "field": "variants.prices.centAmount"
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "pricesStatsVariants",
        "min": 100,
        "max": 300,
        "mean": 200,
        "sum": 600,
        "count": 3
      }
    ]
  }
}

Example:

{
  "facets": [
    {
      "stats": {
       "name": "pricesValidFromStats",
       "field": "variants.prices.validFrom"
      }
    }
  ]
}

{
  "facets": {
    "results": [
      {
        "name": "pricesValidFromStats",
        "min": "2001-09-11T14:00:00.0Z",
        "max": "2024-05-01T04:00:00.0Z",
        "count": 7
      }
    ]
  }
}

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 Attributes

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

The Price with the most exact data and price scope is indexed for a Product Variant. This means that a Price with a valid time range is given priority over a Price without a validity period. Prices that are not valid at the time of indexing are not considered for indexing. Product Search does not automatically update the search index when a Price reaches its validity date or becomes invalid.

Language settings

Supported languages

Incremental indexing

The following changes will cause an incremental indexing:

• A creation, update, or deletion of a Product, a Product Variant or a Price (Embedded or Standalone).
• An activation or deactivation of a Product Discount leading to changes on Prices.
• An addition of Products or Product Variants to a Product Selection (same for removal).

On average, an incremental index update is performed within a few minutes. Depending on the amount of Products to be updated, for example in a batched process, the actual delay—until all the Products are up-to-date—can be higher.

Full reindexing

The following changes will require a full reindexing:

• A creation, update, or deletion of a Product Type.
• A creation, update, or deletion of a Store.
• A deletion of a Product Selection.

On average, a full reindex is performed within 15 minutes. The actual delay—until the product data is up-to-date—can be higher and depends on the following factors:

• The number of Products in the catalog.
• The number and size of the Product Variants of the Products.
• The number of Standalone Prices used in the Project.
• The number of Product Selections and Stores used in the Project.