Commerce search scopes

Current version: 10.3

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 (‘|’).

Tokens

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.

Conditions

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.

Category scope

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

Habitat catalog scope

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 Recommended products scope returns a list of products based on the order ID of the last order placed and uses the related product relationship defined in the catalog.

Recommended products 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.

Excludefromwebsitesearchresults

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

Sxa: RecommendedProducts|NumberOfProducts| RelationshipField|Scope

This SXA search condition retrieves the related products based on the last order placed and injects the product IDs into the query so that the defined number of related products are returned. The Number of products field is the maximum number of returned products and the RelationshipField is the relationship definition defined in the catalog.

The Scope is the fallback scope. If there is no last order placed information, the fallback scope is used. In the following example, 64817E77-2253-48D8-8838-E44EBBB601C7 is the Item id for the On sale television scope, which is the fallback scope.

For example sxa:RecommendedProducts|12|RelatedSellableItemToSellableItem|{64817E77-2253-48D8-8838-E44EBBB601C7} 64817E77-2253-48D8-8838-E44EBBB601C7

Mira laptops scope

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

The Mira laptops scope.

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.

On sale televisions scope

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).

The On sale televisions scope.

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.

The Related products on PDP scope.

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.

Do you have some feedback for us?

If you have suggestions for improving this article,