HCL Commerce Version 9.1.15.0 or later

Navigating the search term with searchExecution

Search expression providers are designed process the input of the search term. To help you gain a deeper understanding of how these providers function, the details of the fields under the searchExecution are analyzed to show how they contribute to fetching results based on the input search term.

Search expression providers

The following examples use the searchExecution data under the metaData in the response JSON string. Within this metadata, each field holds a distinct purpose in enhancing the accuracy and relevance of your search results.

The examples use the HCL Commerce Search REST API. For more information, see REST API for Elasticsearch-based Search.

Spell Correct

The Spell Correct provider utilizes the Elasticsearch suggest API to correct search term spellings. By comparing search term with product index, it identifies potential spelling errors and suggests the most appropriate corrections. For example, if you search for "blck dress," the SpellCorrect provider recognizes your intent and suggests "black dress" as the corrected term.

GET http://hostname:port/search/resources/api/v2/products?storeId=11&searchTerm=blck dress

Response Metadata: 

"metaData": {
    ...
    "spellcheck": [
        "black",
        "blue",
        "blank"
    ],
    "searchExecution": [
        {
            "searchTerm": "blck dress",
            "spellCorrect": "blck dress --> black dress",
            "searchRule": {},
            "nlp": {
                "pos": "ADJECTIVE --> [black]",
                "ner": "CATEGORY --> [dress]",
                "color": "COLOR --> [black]"
            },
            "customFields": {}
        }
    ]
}
For more information on customizing the spell check function, see Customizing spell check correction suggestions.

Stopword

The Stopword provider takes on the responsibility of eliminating stopwords from your search terms. Stopwords are common words (for example, "the", "and", "by", "is") that do not contribute significantly to deducing the intent of the search. By removing them, this provider enhances the relevance of your results. The Stopword terms are contained in a list configured via Zookeeper. The provider also leverages the IGNORE_TERM Named Entity Recognition (NER) method to further identify and eliminate stopwords from your search query.

GET http://hostname:port/search/resources/api/v2/products?storeId=11&searchTerm=party dress by Albini

Response Metadata: 

"metaData": {
    ... 
    "searchExecution": [
        {
            "searchTerm": "party dress by Albini",
            "stopword": "[by] --> party dress albini",
            "searchRule": {},
            "nlp": {
                "pos": "NOUN --> [parti~party] | ADJECTIVE --> [albini]",
                "ner": "CATEGORY --> [dress]"
            },
            "customFields": {}
        }
    ]
}

Search Term Association (STA)

The SearchTermAssociation (STA) provider is responsible for parsing your search term and applying modifications based on the STA configuration in the Management Center. It plays a pivotal role in customizing your search query to enhance your search results. It operates in two primary ways:
Synonyms
When synonyms are identified in your search term, the STA provider adds additional terms to broaden the scope of your search. For example, if you search for "couch" the STA provider might expand your search to include "sofa" ensuring you don't miss relevant results.
GET http://hostname:port/search/resources/api/v2/products?storeId=11&searchTerm=couch

Response Metadata: 

"metaData": {
    ...
    "searchExecution": [
        {
            "searchTerm": "couch",
            "sta": "couch : [couch OR sofa]",
            "searchRule": {},
            "nlp": {},
            "customFields": {}
        }
    ]
}
For more information on managing STAs, see Improve storefront search results by using search term associations.
Replacements
In cases where specific terms are identified for replacement in your search term, the STA provider makes these substitutions. For instance, if you search for "desk" but there is a configuration to replace "desk" with "table," the STA provider ensures that your search reflects this replacement.
GET http://hostname:port/search/resources/api/v2/products?storeId=11&searchTerm=desk

Response Metadata: 

"metaData": {
    ...
    "searchExecution": [
        {
            "searchTerm": "desk",
            "sta": "desk =>  table",
            "searchRule": {},
            "nlp": {
                "ner": "CATEGORY --> [tabl~table]"
            },
            "customFields": {}
        }
    ]
}

Search Rule

The Search Rule provider is responsible for parsing search rules based on the matching search term. There are different types of search rules in the Management Center and current searchExecution metadata supports several SearchRule types, including Order, Filter, Boost, and Replace Term. Each type of rule leads to the addition of specific query sections in Elasticsearch to further customize the search.
Restriction: Currently, SearchRule metadata supports rules of the types Change Search Result Order and Add or Replace Search Criteria with the Property type only. Other rule types are not supported at this time.

For more information, see Managing search rules.

Filter
If a Search Rule with a filter is identified, it adds the filters to the query, refining the results to meet specific criteria such as Name, Manufacturer Name, Short Description, and so on. In this metadata, filters with exclusions are denoted with EXCL and filters with inclusions are denoted with INCL. For example, Name --> EXCL:[dinning, chair] denotes a filter where Name does not contain any of these values [dining, chair].
GET http://hostname:port/search/resources/api/v2/products?storeId=11&searchTerm=desk
Response Metadata: 

"metaData": {
    ...
    "searchExecution": [
        {
            "searchTerm": "desk",
            "searchRule": {
                "filter": "Short Description --> INCL:[table, desk, work desk] | Manufacturer Name --> EXCL:[style home, stonehenge] | Name --> EXCL:[dining, chair]"
            },
            "nlp": {
                "pos": "NOUN --> [desk] (boosted by 500.0)"
            },
            "customFields": {}
        }
    ]
}
Order
If a Search Rule pertaining to orders is identified as applying to the query, the provider adjusts the query to sort the search results in a particular order, such as by price, Manufacturer Name, or Name, and so on.
GET http://hostname:port/search/resources/api/v2/products?storeId=11&searchTerm=chair

Response Metadata: 

"metaData": {
    ... 
    "searchExecution": [
        {
            "searchTerm": "chair",
            "searchRule": {
                "order": "Manufacturer Name --> DESC | Offer Price --> ASC | Name --> ASC"
            },
            "nlp": {
                "ner": "CATEGORY --> [chair~chairs] (boosted by 100.0)"
            },
            "customFields": {}
        }
    ]
}
Boost
If a Search Rule with Promote or Demote is identified, the provider adjusts the query to enhance the relevance of specific results, such as Manufacturer Name, Name, etc.
GET http://hostname:port/search/resources/api/v2/products?storeId=11&searchTerm=mirror

Response Metadata: 

"metaData": {
    ...
    "searchExecution": [
        {
            "searchTerm": "mirror",
            "searchRule": {
                "boost": "PROMOTE --> Name: wall mirror (boosted by 999.0) | DEMOTE --> Short Description: makeup mirror (boosted by 500.0)"
            },
            "nlp": {
                "pos": "NOUN --> [mirror] (boosted by 500.0)"
            },
            "customFields": {}
        }
    ]
}
For additional information on boosting, see Tuning index field boost relevancy.
Replace Term
If a Search Rule with search term replacement is identified, the provider substitutes the matching term with a designated replacement term in the query.
GET http://hostname:port/search/resources/api/v2/products?storeId=11&searchTerm=mirror

Response Metadata: 

"metaData": {
    ...
    "searchExecution": [
        {
            "searchTerm": "makeup mirror",
            "searchRule": {
                "replaceTerm": "mirror --> makeup mirror"
            },
            "nlp": {
                "pos": "NOUN --> [makeup, mirror]"
            },
            "customFields": {}
        }
    ]
}

Part Number

The Part Number provider parses your search term and identifies part number patterns. If it detects a match, it initiates specific queries to the SKU and Manufacturer Part Number fields in the product index.

GET http://hostname:port/search/resources/api/v2/products?storeId=11&searchTerm=lr-fntr-0005

Response Metadata: 

"metaData": {
    ...
    "searchExecution": [
        {
            "searchTerm": "lr-fntr-0005",
            "partNumber": "lr-fntr-0005 --> [lr fntr 0005]",
            "searchRule": {},
            "nlp": {},
            "customFields": {}
        }
    ]
}