Commerce search scopes

Current version: 10.1

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:

Category scope - to display products within a specific category.
Habitat catalog scope - to search for products within the entire Habitat catalog.
Recommended products - (used on the SXA Storefront site template Home page) to search for a list of recommended products based on the last order placed.
Mira laptops scope - (used on the SXA Storefront site template Home page) to display only Mira brand laptops from the sample Habitat catalog as promoted products.
On sale televisions scope - (used on the SXA Storefront site template Home page) to display only those televisions that are on sale from the sample Habitat catalog as promoted products.
Related products on PDP scope - (used on the SXA Storefront site template Product Details Page) to display related products as defined in the catalog.

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.

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`

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.

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

Recommended products scope

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.

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.

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

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.

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.

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,