Index and Query Popular Searches
Oracle Commerce offers a ready-to-use typeahead function, which searches against and returns product records. This can be used to display products, their prices, images, and so on
This section applies to Open Storefront Framework (OSF) and Storefront Classic.
Typeahead enables shoppers to also search against other popular search terms. It comes with pre-configured APIs and schema. You need to provide your own search terms and handle rendering the results from this endpoint.
To provide an alternative type-ahead experience for shoppers, you can configure Commerce to search against terms that it has automatically identified as popular with other shoppers. Additionally, Commerce can also search against your own custom or curated search terms.
You must implement this feature using the REST APIs. Commerce widgets do not support this feature by default. To use this feature, you must ensure that you are using the correct configuration, and handle rendering the results from this endpoint. Perform the following steps to use this feature:
- Index popular searches records
- Query the correct endpoint
Note: Popular searches are automatically generated only in production and live environments.
Index popular searches records
Each term that can appear in the results for a query against popular searches is a single record. If you have a list of 15,000 popular search terms, each term is a separate record and indexed separately.
For each record, there are four required fields:
record.id
keyword.terms
keyword.searchable
keyword.score
Shopper searches are normally matched against the keyword.searchable
field, which may contain synonym forms, common misspellings, or any other “alternative” forms of the term corresponding to a given record. The keyword.terms
field contains the canonical form of the term and is the one normally displayed in the results and searched for when the result is selected.
Ensure that all the fields above are properly configured by submitting the following POST
request:
POST /gsadmin/v1/cloud/attributes/keywords
{
"ecr:type": "attributes-owner-folder",
"keyword.terms": {
"ecr:type": "property",
"propertyDataType": "ALPHA",
"isRecordSearchEnabled": false,
"isWildcardEnabledInRecordSearch": false,
"context": [ "locale" ]
},
"keyword.searchable": {
"ecr:type": "property",
"propertyDataType": "ALPHA",
"isRecordSearchEnabled": true,
"isWildcardEnabledInRecordSearch": true,
"context": [ "locale" ]
},
"keyword.score": {
"ecr:type": "property",
"propertyDataType": "DOUBLE"
},
"keyword.searchCount": {
"ecr:type": "property",
"propertyDataType": "INTEGER"
}
}
Suppress product names as suggestions
In all environments, product names are included in the search suggestions to provide a "cold start" for newly launched sites. You may prefer to switch this off. To do so, call the API endpoint /gsadmin/v1/cloud/configuration/services/internal-keywords
and change the property gsdataCatalogLimit
to 1.
Automatic popular searches records
Commerce automatically identifies popular searches based on shoppers’ past behavior, and periodically uploads the corresponding records to the internal-keywords record collection. From there, they are processed for indexing. The contents of the internal-keywords record collection at any given time can be inspected by querying the following endpoint:
GET /gsdata/v1/cloud/data/internal-keywords
Important: Do not attempt to modify the internal-keywords record collection. Your changes will be overwritten.
Preview popular searches in non-live environments
- Issue a
DELETE
command to/gsdata/v1/cloud/data/internal-keywords
on the DEV / TEST environment to remove any existing data (if necessary). - Issue a
GET
command to/gsdata/v1/cloud/data/internal-keywords
on the LIVE environment to retrieve the production data. - Issue a
POST
command to/gsdata/v1/cloud/data/internal-keywords
on the DEV / TEST environment with the retrieved production data.
Add your own custom keyword records
To add custom keyword records to the system so they can be processed for indexing, you must upload them to the keywords record collection with the following endpoint:
POST /gsdata/v1/cloud/data/keywords
Multiple records can be submitted in each request. Multiple requests can be made to add data. That is, subsequent POST
calls to /gsdata
will not replace previously submitted records. If you need to submit a large number of records, it is recommended to submit then in a few sets, rather than one at a time.
The following is a sample POST
command that submits three records using the above schema:
POST /gsdata/v1/cloud/data/keywords
{
"items":[
{
"record.id": "kw-en:digital+cameras",
"keyword.terms@locale:en": "digital cameras",
"keyword.searchable@locale:en": [
"digital cameras", "digicams"
],
"keyword.score": "12234"
},
{
"record.id": "kw-en:film+cameras",
"keyword.terms@locale:en": "film cameras",
"keyword.searchable@locale:en": "film cameras",
"keyword.score": "3234"
},
{
"record.id":"kw-en:dslr+cameras",
"keyword.terms@locale:en": "dslr cameras",
"keyword.searchable@locale:en": [
"dslr cameras", "digital slr cameras", "slr digicams"
],
"keyword.score": "23421"
}
]
}
Localize the custom keyword records
The fields keyword.terms
and keyword.searchable
in the previous section are localized. When uploading records, you must specify the correct locale (for example, @locale:en
for English) that shoppers will search under.
Each keyword record can optionally contain translations for multiple locales. It is perfectly acceptable to create multiple, single-locale keyword records for multiple locales. For example:
POST /gsdata/v1/cloud/data/keywords
{
"items":[
{
"record.id": "kw-en:book",
"keyword.terms@locale:en": "book",
"keyword.searchable@locale:en": "book",
"keyword.score": "1"
},
{
"record.id": "kw-fr:livre",
"keyword.terms@locale:fr": "livre",
"keyword.searchable@locale:fr": "livre",
"keyword.score": "1"
},
{
"record.id": "kw:notebook",
"keyword.terms@locale:en": "notebook",
"keyword.searchable@locale:en": "notebook",
"keyword.terms@locale:fr": "cahier",
"keyword.searchable@locale:fr": "cahier",
"keyword.score": "1"
}
]
}
Index additional fields for custom keyword records
You may want to return additional information with your custom keyword records. In this case, you can add custom fields. There is no fixed schema for those additional fields, but it is recommended that you follow the naming convention of keyword.x
. For example, keyword.related_terms
, or keyword.related_product_id
. For more information, see Modify the configuration to return additional fields.
Perform indexing
If you added custom keyword records to the system and defined schema, you need to run the search indexing process. To do so, use the following API call. Keep in mind that indexing times will vary depending on the size of your catalog.
POST /ccadmin/v1/search/index {"op":"baseline" }
Query the keywords endpoint
At this point, your popular search records are available in the index.
Ensure that the search service definition is properly configured by using the following endpoints:
POST /gsadmin/v1/cloud/searchInterfaces/keywords
{
"isAutoWildcardEnabled": true,
"ecr:type": "search-interface",
"crossFieldMatch": "never",
"fields": [
{
"attribute": "keyword.searchable"
}
]
}
POST /gsadmin/v1/cloud/pages/Default/keywords/typeahead
{
"contentType": "Page",
"ecr:type": "page",
"contentItem": {
"@name": "Keyword Search Service",
"@type": "KeywordSearchService",
"@appFilterState": {
"@type": "FilterState",
"typeAhead": true,
"recordFilters": [
"OR(record.collection:keywords,record.collection:internal-keywords)"
]
},
"resultsList": {
"@type": "ResultsList",
"relRankStrategy": "static(keyword.score,descending)",
"fieldNames": [
"record.id",
"keyword.terms",
"keyword.score"
]
}
}
}
Run the following endpoint:
GET /ccstore/v1/assembler/pages/Default/keywords/typeahead
and specify the following two parameters to perform a search:
Ntt=
This is the user’s search terms. For instance, if the customer has typed “cam” as part of searching for “camera”, you would set it to &Ntt=camNtk=
This specifies the search key. A search interface named “keywords” has been defined
For example:
GET /ccstore/v1/assembler/pages/Default/keywords/typeahead?Ntt=cam&Ntk=keywords
Modify the configuration to return additional fields
In order to provide a responsive service that is also quite small in size, the default /keywords/typeahead service is configured only to return a minimal set of fields in the resultsList
.
If you want additional fields returned, you must modify the /keywords/typeahead
service:
- Run
GET /gsadmin/v1/cloud/pages/Default/keywords/typeahead
. - Add the custom fields to the list of
fieldNames
. PUT
the modifications back to/gsadmin/v1/cloud/pages/Default/keywords/typeahead
.
Configure typeahead query prefixes
By default, Commerce ignores typeahead and wildcard search terms of less than 2 characters.
If you want to change the default behavior, you can use the Search Interfaces endpoints in the Search Admin and Configuration API to change the value of the minWildcardWordLength
search configuration property. For example, if you set the property value to zero (0), the search begins as soon as the shopper types a character.
Keep in mind that setting the value of minWildcardWordLength
to less than the default value (2) might impact performance.
Note that the minWildcardWordLength
search configuration property does not apply to dimension search or compound dimension search, or to the Chinese, Japanese, or Korean languages.
The following sample shows how you can set the value of
minWildcardWordLength
to 0 for typeahead and wildcard searches.
PUT /gsadmin/v1/cloud/searchInterfaces/TypeAhead
{
"ecr:type": "search-interface",
"crossFieldMatch": "always",
"isAutoWildcardEnabled": true,
"minWildcardWordLength": 0,
"fields": [
{
"attribute": "product.displayName"
},
{
"attribute": "ecr:crossField"
},
{
"attribute": "product.category"
}
]
}