Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Search architecture

️ Important

Optimizely Configured Commerce 4.4 upgraded to Elasticsearch 5.5, which also required updating Nest to version 5. Any code from previous versions will require updates. See upgrading to 4.4.

Elasticsearch index

The Elasticsearch Index objects provide access to the search index using the NEST IElasticClient interface. Elasticsearch uses the Search_Url application setting and if the Search_Url is blank it returns an empty search index. If the Server_Url has a valid location then the connection alias is used to then configure an IElasticClient that represents the index.

Elasticsearch index builder

The Elasticsearch Index Builder is used to build the search index. The build method of the search index uses an IndexType to identify whether it is a Category, Content, or Product build of the index.

New indices are built with the name of the Elasticsearch Index alias, typically the database name, and new GUID. This is important because whenever the index is built it creates the new alias and moves the old index to the new one and deletes the old index.

Elasticsearch query builder

The Elasticsearch Query Builder is a helper class for creating Elasticsearch NEST queries and filters. This helper class is ultimately responsible for building the queries for the search provider which interrogates the search index for the search result.


Analyzers are used to perform the analysis process on the specified text and returns the text result.

The following are the analyzers used by Configured Commerce:

  • Query analyzer
  • Index analyzer
  • Lowercase analyzer

Document types

Document Types in Elasticsearch are similar to that of a class definition in .NET. They are made up of a name and properties definition, called mapping. Configured Commerce uses three built in types for products, categories, and CMS content.

For more information on how Elasticsearch defines and uses types and mappings see the following article:

Each of the Configured Commerce Elasticsearch types have an associated search indexers and search providers. The search indexer is used to create the document type record in the Elasticsearch index. Whereas the search provider is used to query the documents within the Elasticsearch index. These types also have an associated class definition and .NET class that defines the Elasticsearch mapping.

Token filters

Configured Commerce uses three out of the box token filters for Elasticsearch. These include the stemmer, stop word, and synonym filters. Elasticsearch currently has over 30 token filters that could be implemented to extend the current out-of-the-box functionality. Those are listed here

The stemmer filter allows queries to interpret search results for words in their root form. For example, pay/paying/paid.

The stop word filter removes certain words from a query that should not impact the quality of the token stream.

The synonym filter allows alternate or paired words to effect the search result. For example, tubing and piping.

Reference Elasticsearch doc here:

Storefront functionality

It is important to understand how the website uses the providers and indexers. Many of the configuration and setting related values are stored in the web browser local storage. This includes:

  • searchHistory
  • productListSortType
  • productListViewName


The search history local storage object maintains a list of search queries that will be used to populate the search history within the search feature. The searchHistory is stored as JSON.

The following is an example JSON object stored for the search history.

[{"q":"washer","includeSuggestions":true},{"q":"he45doe","includeSuggestions":true},{"q": "cheap washers","includeSuggestions":true},{"q":"cheap washer","includeSuggestions":true},{"q":"cheap","includeSuggestions":true},{"q":"laundry ","includeSuggestions":true}]


The product list sort type local storage object stores the value of the current product sort type. Out of the box there are options to sort using the following sort types:

  • Product: A to Z
  • Product: Z to A
  • Price: Low to High
  • Price: High to Low

However this is an extension point of the platform. Developers can add new sort types by deriving a new product search provider and override the MakeCustomerSortOrder method.


The productListViewName local storage object stores two values by default: list and grid. This handles which display method to use for viewing the search results or products.