HCL Commerce Version 9.1.7.0 or later

Search profiles

HCL Commerce Search uses search profiles to control the storefront search experience at a page-level. Search profiles group sets of search runtime parameters, such as search index name, search index fields, expression providers, paging, and sorting.

Loading search profiles

You can load one of the default search profiles, or your own custom profile, from the default location at ESQueryService/src/main/resources/profiles. You can load a default or custom profile in one of two ways:
  • You can manually add your own profiles inside the custom directory.

    The profiles directory contains a custom subdirectory where you can store your own profiles. The custom directory contains three predefined subdiredtories: ingest, nlp, and search. You can create additional subdirectories and place your own custom profiles in them.

    After adding a custom profile, restart both the data query container and the search query container. To view your newly added custom profile use the Query service API and call the following endpoint:
    /api/v2/documents/profiles/{profileName}
    Your custom profile appears under the userData section of the reply.

    For the full REST API specification, see the Query REST API.

  • You can add your custom profile through ZooKeeper.
    ZooKeeper stores named profiles in one of its nodes. You can create, update, delete the profiles, and get profiles using the profiles endpoint of the Query service. The endpoint for the profile is:
    https://data_environment_hostname:30921/search/resources/api/v2/documents/profiles/profileName
    No container needs to be restarted after you add a profile using this endpoint.

Search profile versions

Two search profile versions are associated with the Query Service REST API. The Version 2 search profiles are intended for use with the React storefronts, which require the V2 REST API. The Version 1 search profiles are used with the V1 REST API, and are designed for backward compatibility. They are partially compatible with the V2 REST API in versions 9.1-9.1.6. For more information, see the Query service API specifications.

HCL Commerce Version 9.1.7.0 or later

Version 2 Search profiles

ZooKeeper stores named profiles in one of its nodes. You can create, update, delete the profiles, and get profiles using the profiles endpoint of the Query service. The endpoint for the profile is:
https://data_environment_hostname:30921/search/resources/api/v2/documents/profiles/profileName
No container needs to be restarted after you add a profile using this endpoint.
Note: Do not override the following profiles. These are only for HCL internal use.
  • HCL_findCatalogEntryByIdForBrowse
  • HCL_findCatalogEntryById
Table 1. Search profiles: Product view
Rest API Search Profile Name Description
/api/v2/products?searchTerm HCL_V2_findProductsBySearchTerm This profile retrieves entitled products' details by using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties such as the indexed price, attributes dictionary attributes, facets, and spell check suggestion.
/api/v2/products?searchTerm HCL_V2_findProductsByNameOnly This profile limits the search scope to the catalog entry name and retrieves entitled products' details by using a search term from the CatalogEntry index and retrieves entitled products' details using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties include the indexed price attributes, dictionary attributes, facets, and spell-check suggestions.
/api/v2/products?searchTerm HCL_V2_findProductsByNameAndShortDescriptionOnly This profile limits the search scope to the catalog entry name and short description fields and retrieves entitled products' details by using a search term from the CatalogEntry index and retrieves entitled products' details by using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties such as the indexed price, attributes dictionary attributes, facets, and spell check suggestion.
/api/v2/products?searchTerm HCL_V2_findProductsByUnstructureOnly This profile limits the search scope to the catalog entry unstructured field and retrieves entitled products' details by using a search term from the CatalogEntry index and retrieves entitled products' details by using a search term from the CatalogEntry index.
/api/v2/products?searchTerm HCL_V2_findProductsBySearchTerm_Summary This profile retrieves entitled products details by using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description, and extended properties such as the indexed price, facets, and spell check suggestion.
/api/v2/products?searchTerm HCL_V2_findProductsBySearchTermRanking This profile retrieves entitled products' details by using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties such as the indexed price, attributes dictionary attributes, and spell check suggestion.
/api/v2/products?categoryId HCL_V2_findProductsByCategory This profile retrieves entitled products' details by using the catalog entry parent category unique identifier from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties such as the indexed price, attributes dictionary attributes, facets, and breadcrumb trail.
/api/v2/products?categoryId HCL_V2_findProductsByCategory_Summary This profile retrieves entitled products details by using the catalog entry parent category unique identifier from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description, and extended properties such as the indexed price.
/api/v2/products?categoryId HCL_V2_ComposeFacetListByCategoryId This profile is used to retrieve entitled products facet list.
/api/v2/products?categoryId HCL_V2_BreadCrumbByCategoryUniqueId This profile is used to retrieve the breadcrumb trails of the entitled products category.
/api/v2/products?partNumber HCL_V2_findProductByPartNumber_Details This profile retrieves entitled products' details by using the catalog entry code from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties such as the indexed price, attributes dictionary attributes, underlying SKUs, associated assets, merchandising associations, and components.
/api/v2/products?partNumber HCL_V2_findProductByPartNumber_Summary This profile retrieves entitled products' summary by using the catalog entry code from the CatalogEntry index. Catalog entry summaries include the basic catalog entry properties such as name and description. The extended properties such as the indexed price and attributes dictionary attributes.
/api/v2/products?id HCL_V2_findProductByIds_Details This profile retrieves entitled products' details by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry details include the indexed price, attributes dictionary attributes, underlying SKUs, associated assets, merchandising associations, and components.
/api/v2/products?id HCL_V2_findProductByIdsWithAttributesAndAttachments This profile retrieves entitled products' summary by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry summaries include the indexed price, attributes dictionary attributes, underlying SKUs, and associated assets.
/api/v2/products?id HCL_V2_findProductByIds_Summary This profile retrieves entitled products' summary by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry summaries include the indexed price and attributes dictionary attributes.
/api/v2/products?id HCL_V2_findProductByIds_Summary_WithNoEntitlementCheck This profile retrieves products' summary without doing entitlement check by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry summaries include the indexed price and attributes dictionary attributes.
/api/v2/products?id HCL_V2_findProductByIds_Basic_Summary This profile retrieves basic summaries of products by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry details include the name, partNumber, and catentryId.
/api/v2/products?id HCL_V2_findProductsBySearchTermWithPrice This profile retrieves entitled products' details using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties include the indexed price, grouping price details, attributes dictionary attributes, facets, and spell-check suggestions.
/api/v2/products?categoryId HCL_V2_findProductsByCategory_Summary This profile limits the search scope to the catalog entry name and retrieves entitled product details using the catalog entry parent category unique identifier from the CatalogEntry index. Catalog entry details include the basic catalog entry properties, such as name and description, and extended properties, such as the indexed price.
/api/v2/products?categoryId HCL_V2_findProductsByCategoryWithPriceRange This profile retrieves entitled product details using the catalog entry parent category unique identifier from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties include the indexed price, grouping price details, attributes dictionary attributes, facets, and spell-check suggestions.
V1

store/{storeId}/productview/byId/{productId} andstore/{storeId}/productview/byIds

IBM_Admin_findProductByIds This profile retrieves name, partNumber, and catentryId of product/s by using the catalog entry unique identifier from the CatalogEntry index.
Note: IBM_Admin_findProductByIds and HCL_Admin_findProductByIds profiles are same. This profile is used with V1 API so the prefix is IBM.
V1

store/{storeId}/productview/byId/{productId} andstore/{storeId}/productview/byIds

IBM_findProductByIds_Basic_Summary This profile retrieves basic summaries of products by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry details include the name, partNumber, and catentryId.
V1

store/{storeId}/productview/byCategory/{categoryId}

IBM_findProductsByCategory_Summary This profile limits the search scope to the catalog entry name and retrieves entitled product details using the catalog entry parent category unique identifier from the CatalogEntry index. Catalog entry details include the basic catalog entry properties, such as name and description, and extended properties, such as the indexed price.
V1

store/{storeId}/productview/bySearchTerm/{searchTerm}

IBM_findProductsByNameOnly This profile limits the search scope to the catalog entry name and retrieves entitled products' details by using a search term from the CatalogEntry index and retrieves entitled products' details using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties include the indexed price, attributes dictionary attributes, facets, and spell-check suggestions.
V1

store/{storeId}/productview/bySearchTerm/{searchTerm}

IBM_findProductsByNameAndShortDescriptionOnly This profile limits the search scope to the catalog entry name and short description fields and retrieves entitled products' details by using a search term from the CatalogEntry index and retrieves entitled products' details using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties include the indexed price, attributes dictionary attributes, facets, and spell-check suggestions.
V1

store/{storeId}/productview/bySearchTerm/{searchTerm}

IBM_findProductsByUnstructureOnly This profile limits the search scope to the catalog entry unstructured field and retrieves entitled products' details by using a search term from the CatalogEntry index and retrieves entitled products' details by using a search term from the CatalogEntry index.
Table 2. Search profiles: Category view
Rest API Search Profile Name Description
/api/v2/categories?id HCL_V2_findCategoryByUniqueIds This profile retrieves the entitled catalog group details by using the catalog group unique identifier from the catalog group index.
/api/v2/categories?identifier HCL_V2_findCategoryByIdentifier This profile retrieves the entitled catalog group details by using the catalog group code from the catalog group index.
/api/v2/categories?parentCategoryId HCL_V2_findSubCategories This profile retrieves the entitled top and subcategories details by using the catalog group parent's unique identifier from the catalog group index.
V1

/api/v2/categories?parentCategoryId
HCL_V2_findSubCategories This profile retrieves the entitled top and subcategories details by using the catalog group parent's unique identifier from the catalog group index.

Version 2 search profile usage examples

For a product, map the field name in the ZooKeeper component node in the following manner:
{ 
    "valuemappingservice": { 
        "valuemapping": [{ 
                "externalName": "XPathToProductViewV2ResponseFieldNameMapping", 
                "internalName": "XPathToProductViewV2ResponseFieldNameMapping", 
                "valuemap": [{ 
                        "externalValue": "inventories.*.quantity", 
                        "internalValue": "inventories.*.quantity" 
                    } 
                ] 
            } 
        ] 
    } 
} 

Example of the custom profile for part number

For all center inventory: In the custom profile add response field like -- inventories.*
    { 
    "parentProfileName": "HCL_V2_findProductByPartNumber_Details", 
    "profileName": "test_findProductByPartNumber_Details", 
    "query": { 
    "responseFields": [ 
    "inventories.*" 
    ] 
    } 

  } 
For specific center inventory: In the custom profile add response field like inventories.10501.quantity
    { 
    { 
    "parentProfileName": "HCL_V2_findProductByPartNumber_Details", 
    "profileName": "test_findProductByPartNumber_Details", 
    "query": { 
    "responseFields": [ 
    "inventories.10501.quantity” 
    ] 
   } 
  } 
Example of the lookup profile
Note: If the Hero Product feature is enabled then it is necessary to create the custom lookup profile with all the changes. If the Hero Product feature is disabled then the lookup profile is not used. This profile cannot be overridden as a custom profile.
    { 
    "parentProfileName": "HCL_findCatalogEntryById", 
    "profileName": "X_findCatalogEntryById", 
    "query": { 
    "responseFields": [ 
    "inventories.10501.quantity" 
              ] 
            } 
        } 
For a category, map the field name in the ZooKeeper component node in the following manner:
{ 
    "valuemappingservice": { 
        "valuemapping": [{ 
            "externalName": "XPathToCategoryViewV2ResponseFieldNameMapping",	 
             "internalName":”XPathToCategoryViewV2ResponseFieldNameMapping", 
              "valuemap": [{ 
                   "externalValue": "keyword.text", 
                    "internalValue": "keyword.text" 
                    } 
                ] 
            } 
        ] 
    } 
} 

Example of the custom profile for category identifiers

For all center inventory: In the custom profile add response field like --keyword.text
{ 
    "profileName": "HCL_V2_findCategoryByIdentifier", 
    "parentProfileName": "Test_findCategoryByIdentifier", 
    "query": { 
    "responseFields": [ 
    "keyword.text" 
             ] 
   } 
} 
Note: If the Hero Product feature is enabled then it is necessary to create the custom lookup profile with all the changes. If the Hero Product feature is disabled then the lookup profile is not used. This profile cannot be overridden as a custom profile.

HCL Commerce Version 9.1.9.0 or laterExample of search highlighting

To enable search highlighting, edit the configuration file HCL_findProductsBySearchTerm.json. Add the parameter “name.text” to the "queryFields" section, and ensure that it is also added to the "highlight" section.
"queryFields" : ["default.search.text",
                 "default.search.normalized",
                 "default.search.text_*",
                 "name.text"],
...
"highlight" : {
		"fields" : ["name.text"],
		"simplePre" : "<strong><span class=font2>",
		"simplePost" : "</span></strong>"
},

Version 1 search profiles

Search profiles: Product view
REST API Search Profile Name Description
store/{storeId}/productview/{partNumber} IBM_findProductByPartNumber_Details This profile retrieves entitled products' details by using the catalog entry code from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties such as the indexed price, attributes dictionary attributes, underlying SKUs, associated assets, merchandising associations, and components.
store/{storeId}/productview/{partNumber} IBM_findProductByPartNumber_Summary This profile retrieves entitled products' summary by using the catalog entry code from the CatalogEntry index. Catalog entry summaries include the basic catalog entry properties such as name and description. The extended properties such as the indexed price and attributes dictionary attributes.
store/{storeId}/productview/byId/{productId}, store/{storeId}/productview/byIds IBM_findProductByIds_Details This profile retrieves entitled products' details by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry details include the indexed price, attributes dictionary attributes, underlying SKUs, associated assets, merchandising associations, and components.
store/{storeId}/productview/byId/{productId}, store/{storeId}/productview/byIds IBM_findProductByIds_Summary This profile retrieves entitled products' summary by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry summaries include the indexed price and attributes dictionary attributes.
store/{storeId}/productview/byId/{productId}, store/{storeId}/productview/byIds IBM_findProductByIdsWithAttributesAndAttachments This profile retrieves entitled products' summary by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry summaries include the indexed price, attributes dictionary attributes, underlying SKUs, and associated assets.
store/{storeId}/productview/byId/{productId}, store/{storeId}/productview/byIds IBM_findProductByIds_Summary_WithNoEntitlementCheck This profile retrieves products' summary without doing entitlement check by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry summaries include the indexed price and attributes dictionary attributes.
store/{storeId}/productview/byCategory/{categoryId} IBM_findProductsByCategory This profile retrieves entitled products' details by using the catalog entry parent category unique identifier from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties such as the indexed price, attributes dictionary attributes, facets, and breadcrumb trail.
store/{storeId}/productview/bySearchTerm/{searchTerm} IBM_findProductsBySearchTerm This profile retrieves entitled products' details by using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description. The extended properties such as the indexed price, attributes dictionary attributes, facets, and spell check suggestion.
store/{storeId}/productview/bySearchTerm/{searchTerm} IBM_findProductsByNameOnly This profile limits the search scope to the catalog entry name.
store/{storeId}/productview/bySearchTerm/{searchTerm} IBM_findProductsByNameAndShortDescriptionOnly This profile limits the search scope to the catalog entry name and short description fields.
store/{storeId}/productview/bySearchTerm/{searchTerm} IBM_findProductsByUnstructureOnly This profile limits the search scope to the catalog entry unstructured field.
store/{storeId}/productview/byIds IBM_findProductByIds_Basic_Summary This profile retrieves basic summaries of products by using the catalog entry unique identifier from the CatalogEntry index. Catalog entry details include the name, partNumber, and catentryId.
store/{storeId}/productview/byCategory/{categoryId} IBM_findProductsByCategory_Summary This profile retrieves entitled products details by using the catalog entry parent category unique identifier from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description, and extended properties such as the indexed price.
store/{storeId}/productview/byCategory/{categoryId} IBM_ComposeFacetListByCategoryId This profile is used to retrieve entitled products facet list.
store/{storeId}/productview/byCategory/{categoryId} IBM_BreadCrumbByCategoryUniqueId This profile is used to retrieve the breadcrumb trails of the entitled products category.
store/{storeId}/productview/byCategory/{categoryId} IBM_findProductsByCategory_grouping is deprecated by IBM_findProductsByCategory This profile defines configurations for product grouping by category.
store/{storeId}/productview/bySearchTerm/{searchTerm} IBM_findProductsBySearchTerm_Summary This profile retrieves entitled products details by using a search term from the CatalogEntry index. Catalog entry details include the basic catalog entry properties such as name and description, and extended properties such as the indexed price, facets, and spell check suggestion.
store/{storeId}/productview/bySearchTerm/{searchTerm} IBM_findProductsBySearchTerm_grouping is deprecated by IBM_findProductsBySearchTerm This profile defines configurations for product grouping by search term.
Search profiles: Category view
REST API Search Profile Name Description
store/{storeId}/categoryview/@top, store/{storeId}/categoryview/byParentCategory/{parentCategoryId} IBM_findSubCategories This profile retrieves the entitled top and subcategories details by using the catalog group parent's unique identifier from the catalog group index.
V1

store/{storeId}/categoryview/{categoryIdentifier}

IBM_findCategoryByIdentifier This profile retrieves the entitled catalog group details by using the catalog group code from the catalog group index.
V1

store/{storeId}/categoryview/byIdentifiers

IBM_findCategoryByIdentifier This profile retrieves the entitled catalog group details by using the catalog group code from the catalog group index.
store/{storeId}/categoryview/byId/{categoryId}, store/{storeId}/categoryview/byIds IBM_findCategoryByUniqueIds This profile retrieves the entitled catalog group details by using the catalog group unique identifier from the catalog group index.
store/{storeId}/categoryview/byIds store/{storeId}/categoryview/byId/{categoryId} IBM_Admin_findCategoryByIds This search profile retrieves the categories based on multiple unique IDs. It is Reserved for HCL internal use.
Search profiles: Site content
REST API Search Profile Name Description
store/{storeId}/sitecontent/webContentsBySearchTerm/{searchTerm} IBM_findWebContentsBySearchTerm This search profile is used to retrieve the site contents' articles and videos summary by using a search term from the Unstructured index.
Note: This profile and API endpoint is not part of in elastic query-service.
store/{storeId}/sitecontent/sellerSuggestions IBM_findNavigationSuggestion_Sellers When the marketplace feature is enabled, this search profile retrieves the catalog entry seller suggestions from the catalog entry index.
store/{storeId}/sitecontent/brandSuggestions IBM_findNavigationSuggestion_Brands This search profile is used to retrieve the catalog entry brand suggestions from the catalog entry index.
store/{storeId}/sitecontent/categorySuggestions IBM_findNavigationSuggestion_Categories This search profile is used to retrieve the catalog group suggestions from the catalog group index.
store/{storeId}/sitecontent/productSuggestionsBySearchTerm/{searchTerm} IBM_findNavigationSuggestion_Products This search profile is used to retrieve the catalog entry suggestions from the catalog entry index.
store/{storeId}/sitecontent/productSuggestionsBySearchTerm/{searchTerm} IBM_findNavigationSuggestion_PartNumber This search profile is used to retrieve the catalog entry's part number suggestions from the catalog entry index.
store/{storeId}/sitecontent/keywordSuggestionsByTerm/{term} IBM_findNavigationSuggestion_Keywords This search profile is used to retrieve the keywords suggestions from the catalog entry index.