Commerce search scopes

Abstract

Overview of the Commerce search scopes that are included with the SXA Storefront site template.

A scope is an SXA concept and is used with search renderings. It consists of a query specifying the start location and the extent of the search and gives you the ability to narrow down search results to make them more meaningful. You can define scope queries that target site pages, promoted products, related products, products in the current category or the entire site including both pages and catalog items. And, using query tokens in the search scope, you can create dynamic queries where tokens are evaluated at time of execution and in the context of the given item. Furthermore, when using a search scope, you can configure boosting rules.

Note

Search scopes are stored per site in the /sitecore/Content/<tenant>/<site>/Settings/Scopes folder.

The Storefront site template includes the following default Commerce search scopes:

Important

If you are using the storefront site template but are not using the Habitat catalog, you must update the default scopes to refer to your own catalog.

Using the search syntax, you can create your own Commerce search scopes. To create a new scope, you build a search query that enables you to add several query tokens.

Note

In the following tables, the parameters for the query tokens are specified after the token name and separated with pipes (‘|’).

There is a specific syntax to use when you use Commerce query tokens in the Commerce search scope:

  • A vertical slash (pipe) is used when defining a value for a condition. For example: ItemsWithTheSameValueInField|Field Name displays as ItemsWithTheSameValueInField: Field Name and indicates that search results must all have the same value in the field with the provided name, for example, the index field value must match the value of the same field on the current item.

  • Leading underscores indicate a system condition. For example, _workflow_state whereby you can create a query that include products that are in a particular workflow state such as Approved.

  • For the ItemsWithTheSameValueInParentChildFields|ItemFieldName|IndexFieldName query token, any parent field name that starts with a double underscore __ translates to an attribute on the item instead of a field. For example, it can accept the field name "__id" and translate it to ContextItem.ID instead of ContextItem.Fields["__id"], which is useful because Item.ID is a property/attribute on an item and not a regular field. This is the case with category navigation, where the condition sxa:ItemsWithTheSameValueInParentChildFields|__id|_parent, specifies that the_value of index field _parent must match the value of the ID property of the current item. This makes sense, knowing that values of index field _parent reference content item IDs.

The following table lists all the conditions available.

Condition

Description

_LatestVersion

This condition is used to ensure that only the latest version of a product is displayed in search results. Possible values are true and [blank].

Commercesearchitemtype

This condition limits the search to items of a given type. Possible values are: category, sellableitem, and catalog.

For the purpose of the Category scope, the value is set to sellableitem (products) and is used to ensure that other Sitecore items do not show up in search results.

Excludefromwebsitesearchresults

This is an optional condition that is used to ensure that a product is only shown once in search results.

In the Commerce Control Panel, you can configure the value of Exclude Duplicate Search Results that, if set to true, instructs the indexer to set the value of the index field to true for duplicate instances. By default, all instances have the value set to false.

For example, Excludefromwebsitesearchresults|false is used in customer searches to limit the result to only return the non-duplicate instances, for example. one instance of all unique products.

Parentcataloglist

This condition is used to specify the catalog to target. It is useful when there are multiple catalogs to ensure that only products in one catalog are returned.

For example, ParentCataloglist|{59DDADC1-9B88-727E-9E14-3F6CF321AE0F} is used for category navigation and search to only target the Habitat catalog.

ProductRelationship

This query token is used to read the related products of the current product from a specified relationship and inject the IDs of the products into the query, so that only the related products are returned.

For example, ProductRelationship|RelatedSellableItemToSellableItem is used on product detail pages to render the list of related products.

Sxa: UnderCurrentPage

This is a SXA search condition that limits search results to the current page or category.

In the Storefront site template, sxa:UnderCurrentPage is used for category navigation to limit results to catalog items under the current category. Results include sub-categories and products to any depth such that for the Audio category sub-categories such as Headphones are included as well.

Sxa: ItemsWithTheSameValueInParentChildField| ItemFIeldName|IndexFieldName

This condition is similar to the SXA query token ItemsWithTheSameValueInField|FieldName that limits search results to items that have the same value in a specific index field. It accepts two field names and reads the parent field value from the current item to search for documents with that value in the index field.

For example, sxa:ItemsWithTheSameValueInParentChildFields|__id|_parent is used for category navigation to limit the result to only product items that are stored directly beneath the current category and not products stored in sub-categories. With the Habitat catalog, products are associated at both levels, so a product like Kickbuds Wireless Headphones appear both under Audio and Headphones.

The category scope restricts search results to a specific product category.

Build a search query.

Commerce search tokens include:

Condition

Description

Commercesearchitemtype

This condition limits the search to items of a given type. Possible values are: category, sellableitem, and catalog.

For the purpose of the Category scope, the value is set to sellableitem (products) and is used to ensure that other Sitecore items do not show up in search results.

_LatestVersion

This condition is used to ensure that only the latest version of a product is displayed in search results. Possible values are true and [blank].

Excludefromwebsitesearchresults

This is an optional condition that is used to ensure that a product is only shown once in search results.

Parentcataloglist

This condition is used when there are multiple catalogs to ensure that only products in one catalog are shown.

The expected value is the ID of the catalog item (the GUID).

SXA search tokens include:

Token

Description

Sxa: UnderCurrentPage

This is a SXA search condition that limits search results to the current page or category.

Sxa: ItemsWithTheSameValueInParentChildField| ItemFIeldName|IndexFieldName

This SXA search condition accepts two field names as input.

For example, sxa:ItemsWithTheSameValueInParentChildFields|__id|_parent

The Habitat catalog scope restricts the search to a specific catalog.

Habitat scope

Commerce conditions and tokens include:

Condition

Description

Commercesearchitemtype

This condition limits the search to items of a given type. Possible values are: category, sellableitem and catalog.

_LatestVersion

This condition is used to ensure that only the latest version of a product is displayed in search results. Possible values are true and [blank].

Excludefromwebsitesearchresults

This is an optional condition that is used to ensure that a product is only shown once in search results.

Parentcataloglist

This condition is used when there are multiple catalogs to ensure that only products in one catalog are shown.

The expected value is the ID of the catalog item (the GUID).

The Mira laptops scope restricts the search to the Mira brand of laptops.

Scope_Mira.png

In addition to two index filters (Brand and Location), the following Commerce tokens are used in this scope.

Tokens

Description

Commercesearchitemtype

This condition limits the search to products and is used to ensure that other Sitecore items do not show up in results.

Excludefromwebsitesearchresults

This is an optional condition that is used to ensure that a product is only shown once in search results.

The On sale televisions scope restricts the search to the defined product list for On Sale Televisions (/sitecore/Content/Sitecore/Storefront/Data/Commerce/Product Lists/Promoted Products List).

Scope_OnSaleTVs.png

In addition to one index filter (Location), the following Commerce tokens are used in this scope.

Field

Description

Commercesearchitemtype

This condition limits the search to products and is used to ensure that other Sitecore items do not show up in results.

Excludefromwebsitesearchresults

This is an optional condition that is used to ensure that a product is only shown once in search results.

The Related products on PDP scope restricts the search to products that are defined in the catalog as related.

Scope_RelatedProducts.png

In addition to one SXA condition Sxa: ProductRelationship|RelatedSellableItemtoSellableItem, the following Commerce tokens are used in this scope.

Token

Description

Excludefromwebsitesearchresults

This is an optional condition that is used to ensure that a product is only shown once in search results.

Commercesearchitemtype

This condition limits the search to products and is used to ensure that other Sitecore items do not show up in results.

ProductRelationship|RelationshipField

This query token is used to read the related products of the current product from a specified relationship and inject the IDs of the products into the query, so that only the related products are returned.

For example, ProductRelationship|RelatedSellableItemToSellableItem is used on product detail pages to render the list of related products.