Understanding indexing for Search in Oracle Commerce Cloud
When it comes to searching your Oracle Commerce Cloud catalog, there are number of endpoints and options that can be tough to keep track of. In this article, I’m going to discuss all of the various ways indexing happens, and when to call various endpoints.
The system of record for your Products and SKUs is the Oracle Cloud Commerce catalog. At certain times during publishing, data is exported from the Catalog to the search indexes. There are a few types of export and indexing processes that can occur (in order from longest to shortest duration):
- Baseline full export — This completely re-exports the catalog to the search index. This typically needs to happen when a large “schema” change is made. This can include configuring new sites, languages, and secondary catalogs. After such an export, the search index is completely rebuilt. For customers who previously used Oracle Commerce for on-premise, this was the traditional baseline behavior. Baseline full exports should be the most rare type.
- Baseline export — This is similar to the above, except for one important change: Only product records that have changed are exported from the catalog. Following that, the search index is completely rebuilt. This typically occurs for certain types of search index schema changes that don’t require exporting the catalog. For instance, this can include adding new Product Types, price list groups, renaming collections, etc. For customers coming from Oracle Commerce on-premise, this is a change to improve indexing times. This feature is sometimes referred to as “Smart Export” because the catalog smartly exports only the actual changed data.
- Partial export — The most common scenario, this exports only the changed products, and only those changed products are updated in the search index. This includes adding new products, changing products, media, prices, etc.
In OCC Admin, when you invoke Publishing after making your product and catalog changes, it will pick a Baseline, Baseline full or Partial indexing based on the set of changes.
Configuration Changes and Indexing
There are a number of configuration changes that you can make involving search, and it’s important to understand how indexing works to promote those changes.
First, many changes you make are previewable: What this means is you can make a change, and then instantly view those changes in your preview Storefront (by clicking Preview from within OCC Admin).
These include:
- thesaurus
- keyword redirects
- changes to relevancy ranking strategies, or the use of the Dynamic Curation tool ( https://medium.com/oracledevs/dynamic-curation-of-product-listings-with-oracle-commerce-cloud-3a6de6f01450 )
- facet ordering
- updating your search interfaces using the Searchable Field Rankings tool
In the scenarios above, simply make your change and you can test it out in the Preview storefront. However, how do we get these changes to our live Storefronts?
Answer: When indexing occurs, the final step of the process is to promote this content to the live Storefronts. Therefore, to promote these changes we kick off indexing. (The endpoint calls are discussed in the section below)
One very common trick is this: Make a meaningless change to a product (such as adding a space to a product description field). Go to Publishing and publish that change, and indexing will occur which will promote our content changes.
Schema Changes and Indexing
Changes to schema are not previewable, and will require a baseline or baseline full export. This means that when indexing is completed, you will see the changes reflected in your Preview and Live storefronts at the same time.
Some examples of schema changes are:
- Defining new properties or dimensions using the /gsadmin/v1/cloud/attributes endpoints
- Defining manipulations of data using the /gsadmin/v1/cloud/attributes endpoints
- Defining precedence rules
- Indexing non-catalog content for the first time using the /gsdata endpoint
In situations like this, you will need to kick off a baseline update: This process will rebuild the search index. HOWEVER, you don’t necessarily need to kick off a baseline FULL export. Remember, that re-exports the whole catalog. Since we have that catalog data on the the search side, we just need to kick off a baseline update to rebuild the index.
The /ccadmin/v1/search/index endpoint
To kick off indexing outside of publishing, we can use the /ccadmin/v1/search/index endpoint, formally documented here:
https://docs.oracle.com/en/cloud/saas/commerce-cloud/cxocc/op-ccadmin-v1-search-index-post.html
POST /ccadmin/v1/search/index
As a payload, you would specify:
Baseline full: { “op” : “baseline-full-export” }
Baseline: { “op” : “baseline” }
Partial: { “op” : “partial” }
Executing a GET /ccadmin/v1/search/index will return detailed JSON on your indexing history.
Performing a Baseline Full Export when things seem wrong
Running a baseline export can sometimes clear up issues if the catalog and search index get out of sync. In the past, there have been issues where certain catalog changes (such as adding a new price list group) weren’t tracked correctly, and only by executing a baseline full export were things fully resolved.
If you find such a scenario, please contact support. As a general rule, however, you should NOT have to manually invoke baseline full exports regularly. These are the most time-consuming indexing scenarios.
Conclusions
Hopefully this article helps you understand how search indexing works, and how to (and when to) invoke the various indexing processes.
The views expressed in this article are my own and do not represent those of my employer. The development, release and timing of any features or functionality described for Oracle’s products remain at the sole discretion of Oracle.
