Generic search framework

Version: 10.3

Sitecore Experience Commerce (XC) release 10.0 introduces a generic, provider agnostic search framework that allows you to use the same search query syntax for search operations directed to any supported search provider. You can invoke search operations programmatically (using the Search plugin) or through an exposed API endpoint.

The generic search API provides capability for searching for catalog items, price cards, orders, customers, and promotions. The Commerce Engine also leverages the capability of the generic search framework in pipeline processes that require discovery of Commerce entities, such as price cards or promotions discovery, for example.

Note

XC Business Tools search functionality does not make use of the generic search framework.

Search query models

The generic search framework defines the following models to support search queries:

  • SearchQuery

  • EqualsSearchNode

  • MatchAllSearchNode

  • FieldNameSearchNode

  • FieldValueSearchNode

Filter query models

The generic search framework defines the following models to support filter queries:

  • FilterQuery

  • MatchAllFilterNode

  • ContainsFilterNode

  • AndFilterNode

  • EqualsFilterNode

  • OrFilterNode

  • FieldNameFilterNode

  • FieldValueFilterNode

  • NotFilterNode

  • GreaterThanFilterNode

  • LessThanFilterNode

FilterNodeValueTypes

The FieldValueFilterNode parameter in a filter query takes a FilterNodeValueTypes value that supports the following data types:

  • Text : a string (default in most of the cases)

  • Integer number

  • Float number

  • Date : in format "yyyy-MM-ddTHH:mm:ss.FFFZ"

  • Boolean ("true" or "false")

  • String in collection : the text inside the collection. For example: associated catalogs in Promotions index.

Generic search API endpoint

The generic search framework exposes the following GenericSearch API end-point {{ServiceHost}}/{{ShopsApi}}/GenericSearch().

You can use the GenericSearch sample request in Postman to exercise the API.

The GenericSearchCommand command

The generic search framework defines the GenericSearchCommand command. The GenericSearchCommand command calls the IGenericSearchPipeline pipeline.

GenericSearchCommand parameters

The following table lists the parameters of a GenericSearchCommand operation:

Parameter

Description

"searchScopeName"

The name of a SearchScopePolicy defined in Plugin.Search.PolicySet. Defines which index to search.

"searchQuery"

The query that consists of search criteria. The parsed version is passed as a search query to the search provider.

"filterQuery"

The query that consists of filter criteria. The parsed version is passed as a filter query to the search provider.

"options"

The options associated with the search operation:

  • "skip": determines how many documents to skip from the search results. Needed for pagination.

  • "top": determines how many documents to return from the search results. Needed for pagination.

  • "resultsOrderFields": allows to determine the order and the fields to use for sorting search results.

  • "fieldsToRetrieve": determines the fields to return from the search provider. If no fields provided, the result returns all fields.

Search and filter nodes

The generic search framework defines search nodes and filter nodes. A search node represents the primary match criteria in a search query. A filter node represents the match criteria in a filter query. You use a filter query to further refine a search and limit the number of returned results.

Search nodes

The following table lists and describes search nodes used in a search query:

Search node

Description

Match all

Matches all documents in the index.

Equals

Uses a specified FieldName and FieldValue to search only for documents that match the specified field name and value.

Filter nodes

The following table lists and describes filter node operators that you can use in a filter query to further refine search results and hone in on specific content:

Filter node

Description

Match all

Matches all documents in the index. This is the equivalent of a search that does not use a filter.

Contains

Matches only documents that contain a substring specified in the FieldName and FieldValue .

Note

In Azure Search, the Contains filter node does not support queries that specify multiple terms separated by spaces, or any special symbols. For example, with Azure Search, a filter query that contains the two keywords "video game" returns any documents that contain the substring video, without consideration for the second keyword game.

Equals

Uses the specified FieldName and FieldValue to search only for documents that match both the field name and the field value.

And

Allows to build complex queries, in conjunction with other nodes. Represents a logical AND operation to build complex queries such as: name = "bla" AND displayname contains "abc". Both clauses must but true for the search to return results.

Or

Allows to build more complex queries by combining two clauses with OR relationship. The results returns documents if any of the clauses is true.

Not

Allows to invert the logic of some nodes.

Greater than

In conjunction with FieldName and FieldValue, allows to return documents where the FieldValue is greater than the one provided. Used for numbers and dates only.

Less than

In conjunction with FieldName and FieldValue, allows to return documents where the FieldValue is less than the one provided. Used for numbers and dates only

Examples of search and filter queries

The following provides some examples of search and filter queries using C# programming language.

Example of a search query using the MatchAllSearchNode criteria

The following sample shows an example of a query that uses the MatchAllSearchNode criteria:

RequestResponse
 var sq = new SearchQuery(); -
   search query to match all documents. The same as:
 var sq = new SearchQuery(new MatchAllSearchNode())

Example of a search query using the EqualsSearchNode criteria

The following sample shows an example of a query that uses the EqualsSearchNode criteria:

RequestResponse
 var sq = new SearchQuery(
    new EqualsSearchNode(
    new FieldNameSearchNode("fieldName"),
    new FieldValueSearchNode("fieldValue")));

Example of a filter query using the MatchAllFilterNode criteria

The following sample shows an example of a query that uses the MatchAllFilterNode criteria:

RequestResponse
var fq = new FilterQuery() -
  applies no filtering on search results. The same as
var fq = new FilterQuery(new MatchAllFilterNode())

Example of a filter query using the GreaterThanFilterNode criteria

The following sample shows an example of a complex query that uses the GreaterThanFilterNode criteria:

RequestResponse
var fq = new FilterQuery(
  new AndFilterNode(
    new ContainsFilterNode(
      new FieldNameFilterNode("fieldName"),
      new FieldValueFilterNode("fieldValue")),
    new GreaterThanFilterNode(
      new FieldNameFilterNode("dateFieldName"),
      new FieldValueFilterNode("dateValue", FilterNodeValueType.Date)))); - filter query to return only those documents that contain text "fieldValue" within "fieldName" field and "dateFieldName" is greater than "dateValue".
Note

The "dateValue" must be stated in this format: "yyyy-MM-ddTHH:mm:ss.FFFZ", for example: "2000-01-01T12:00:00.000Z" where:

  • yyyy is the year.

  • MM is the month.

  • dd is the day of the month.

  • T is the time delimiter.

  • HH is the time in hours.

  • mm represents minutes.

  • ss represents seconds.

  • FFF represents fractions of a second (without zeroes).

  • Z is a time zone designator for the zero UTC offset.

Example of a complex filter query

The following sample shows an example of a complex filter query:

RequestResponse
var fq = new FilterQuery(
   new OrFilterNode(
     new EqualsFilterNode(
       new FieldNameFilterNode("fieldName"),
       new FieldValueFilterNode("booleanValue", FilterNodeValueType.Boolean)),
     new NotFilterNode(
       new EqualsFilterNode(
         new FieldNameFilterNode("floatFieldName"),
         new FieldValueFilterNode("1.0",FilterNodeValueType.FloatNumber))))); -
filter query to return only those documents where "fieldName" equals
Boolean value "booleanValue" or "floatFieldName" not equals
1.0 float number.

Do you have some feedback for us?

If you have suggestions for improving this article,