Specify which index fields are included in searches
This section describes search interfaces, the underlying configurable mechanism through which a storefront shopper’s search for product data records is executed.
A search interface performs the following actions:
- Specifies which index fields (property values or dimension values) are examined as possible matches with shoppers’ search terms.
- Specifies how search terms are matched to index fields.
- Together with a relevance ranking strategy, it determines the order in which records appear in the search results. For information about relevance ranking strategies, see Configure the ranking of records in search results.
Search interface configuration can be exported and imported in either ZIP format or JSON format. For information about these formats, see Understand ZIP format and JSON format.
Note: A search interface can be partially configured in Oracle Commerce administration interface, where it is known as a searchable field ranking. For information, see Search Results.
This section includes the following topics:
-
Know how the Search and Navigation REST API can configure search interfaces
-
Know when changes that affect the search interface take effect
Configure a single search interface for multiple sites
If your instance of Oracle Commerce is running multiple sites, all sites must share the same search interface configuration. You cannot configure the search interface differently for the different sites.
Understand what a search interface does
A search interface does not define or control the user interface through which shoppers search for product data in the storefront.
Understand the All and TypeAhead search interfaces
The Oracle Commerce provides two search interfaces, which perform different functions as follows:
- The search interface
All
determines which index fields are examined for possible matches with the shopper’s search terms, how search terms are matched to index fields, and, together with the relevance ranking strategy, how records are sorted in results lists. Only the index fields that are included inAll
are examined for possible matches with shoppers’ search terms.Modify the default version of
All
as needed to enable shoppers to find product information easily and efficiently. - The search interface
TypeAhead
specifies the index fields for whichtypeahead
functionality is enabled. Removing an index field fromTypeAhead
disablestypeahead
functionality for searches on that index field. Note that because wildcarding is required by thetypeahead
feature, wildcarding is enabled by default for all members of theTypeAhead
search interface.
You can specify which index fields are included as members in All
and TypeAhead
using the Search tab of Oracle Commerce, or the Search and Navigation REST API endpoints to modify the configuration of the
search interface.
Important: Use of search interfaces other than All
and Typeahead
is not supported.
Understand how searches are narrowed
A search interface narrows the scope of shoppers’ searches to specified index fields in your published product data. A search interface does this by specifying the following:
- The dimensions whose dimension values will be examined as possible matches with the shopper’s search term.
- The properties whose values will be examined as possible matches with the shopper’s search term.
Note: The dimensions and properties contained by a search interface are known as its members. Searches ignore dimensions and properties that are not members of a search interface.
The dimensions and properties correspond to catalog fields. When catalog content is published the following occurs:
- Product fields that the merchandiser marked as Facet become dimensions.
- Product fields that the merchandiser did not mark as Facet become properties.
- Product category fields such as “Shirts”, “Dresses”, “Skirts” become dimension values.
- Product records (SKUs) grouped under a product category are tagged to the corresponding dimension value.
When a storefront shopper searches on a particular term, the search results include the following product data records:
- Contains a property whose value matches the shopper’s search term, and/or
- Are tagged to dimension values that match the shopper’s search term. The dimension values must be in dimensions that are members of the search interface.
Example: the search interface All
Suppose that the search interface All
includes:
- A property named
product.short_desc
- A dimension named
product.category
If a storefront shopper performs a search on the term “backpacks”, the search results contain the following:
- Records with a
product.short_desc
property whose value matches the search term (“backpacks”); for example, a record whoseproduct.short_desc
property is set to “SLR Camera/Laptop Backpack
”.and/or
- Records tagged to dimension values in the dimension
product.category
that match the search term (“backpacks”); for example, a record tagged to the dimension value “camera backpacks and cases” in the dimensionproduct.category
.
Note: See the following section for information about how search terms are matched to properties and dimensions.
Understand how search strings are matched to index fields
You can configure how search strings are matched to index fields by specifying the following:
- Whether parts of a search string can be individually matched with different members.
- Whether partial query matches are supported.
For detailed information, see Search interface attributes below.
Understand how the fields array affects the sorting of search results
The order of records in search results is determined by your relevance ranking strategy. A relevance ranking strategy is composed of different modules, each of which sorts records according to its own criteria.
Some modules take into account the order of the members in the fields array of your search interface. For information about how they do this, see Understand how relevance ranking modules sort results.
The position of the member ecr:crossField
in the fields
array determines the position in the search results of records that are added to the list because of cross-field matches. The member ecr:crossField
is taken into account only when the crossFieldMatch
attribute is set to always
.
Know how the Search and Navigation REST API can configure search interfaces
The following tasks can be performed only through the Search and Navigation REST API:
- Create and delete search interfaces
- Enable and disable cross-field matching
- Enable different types of partial matching
- Specify snippet sizes
In addition, the Search and Navigation REST API can perform a number of tasks that can also be performed through the Search tab of Oracle Commerce:
- Add fields to and delete them from a search interface
- Specify the position in search results of records that are selected because of cross-field matches
Dimensions and properties can be marked as searchable in the Catalog tab of Oracle Commerce.
Note: The Search and Navigation REST API cannot create or modify dimensions or properties.
Understand search interface elements
A search interface is configured by a JSON document that includes the following elements:
- attributes: which configure the behavior of the search interface as a whole. See the following section for information about the attributes of a search interface.
- fields: an attribute array containing the members of the search interface. Each member is a dimension or property that is examined for matches with the shopper’s search term. The order of members in the fields array can affect the order of records in search results; see Understand how the fields array affects the sorting of search results.
Search interface attributes
A search interface is configured by JSON attributes. The following table summarizes these attributes. The use of these attributes is discussed in the sections following this table.
Attribute | Supported values | Description |
---|---|---|
ecr:type |
(required) search-interface |
Specifies that this JSON document configures a search interface. |
isAutoWildcardEnabled |
true , false |
True enables wildcarding for all members of this search interface.
|
crossFieldMatch |
always , never , or onFailure (See below.)
|
Specifies whether parts of a search string can be individually matched with different members. For example, given the search string “red shoes”, can matches be made between “red” and one member, and between “shoes” and another member? See Examples: Cross-field matching and partial matching. Cross field matches can be made between dimensions, between properties, or between dimensions and properties. The possible values of this attribute have the following meanings: |
crossFieldMatch
|
always |
Causes the search always to look for matches between members of the search interface and the parts of a search string. Note: If |
crossFieldMatch |
never |
Requires that the entire search string be found within the same member in order to make a match. You can set |
crossFieldMatch |
onFailure |
Causes the search to look for matches between members of the search interface and parts of a search string only if it cannot match the entire search string to any single member of the search interface. You can set |
partialMatch |
|
Specifies whether partial query matches should be supported for the search interface that contains this element. See Examples: Cross-field matching and partial matching. The possible values of this attribute have the following meanings: |
partialMatch |
maxWordsOmitted |
A positive integer or zero. If the original keyword search string includes N words, then all results will match at least N – maxWordsOmitted words. The default is 2.
|
partialMatch |
minWordsIncluded |
A positive integer. All results will match at least this many words from the search query. The default is 2. |
fields |
(required) array of attributes |
Each attribute in the The position of the attribute Note: Include |
snippetSize |
positive integer |
Specifies the maximum number of words that this member can contain. Omitting this attribute or setting its value to zero disables the ability to create snippets. Note: Snippets are useful for document searches, but are not ordinarily used by eCommerce Web sites. |
The following sample JSON illustrates the configuration of a search interface that includes four members, product.displayName
, product.brand
, ecr:crossField
, and product.category:
{
"ecr:type": "search-interface",
"crossFieldMatch": "always",
"fields": [
{
"attribute": "product.displayName "
},
{
"attribute": "product.brand"
},
{
"attribute": "ecr:crossField"
},
{
"attribute": "product.category"
}
]
}
Examples: cross-field matching and partial matching
The following examples illustrate the effects on the search results of the crossfieldMatch
and partialMatch
attributes.
Cross-field matching example
Suppose that a shopper searches for matches on the string “men’s shoes” through a search interface that is configured as follows:
- The
crossFieldMatch
attribute of the search interface is set toAlways
, as follows:"crossFieldMatch": "always"
- The members of the search interface include a dimension named
product.category
and a property namedproduct.description
, as follows:"fields": [ { "attribute": "product.category " }, { "attribute": "product.description" } ]
The search results for a search on the string “men’s shoes” will include the following records:
- Records tagged to dimension values in the dimension
product.category
that match both “men’s” and “shoes”. - Records with a property named
product.description
that matches both “men’s” and “shoes”. - Records tagged to one or more dimension values in the dimension
product.category
that match “men’s” and that have a property namedproduct.description
whose value matches “shoes”. - Records tagged to one or more dimension values in the dimension
product.category
that match “shoes” and that have a property namedproduct.description
whose value matches “men’s”.
Partial match example
Suppose that a shopper searches for matches on the string “men’s large blue suede shoes” through a search interface that is configured with the following partialMatch
values:
"partialMatch":
{"maxWordsOmitted": 1,
"minWordsIncluded": 2
}
The value of maxWordsOmitted
specifies that a property or dimension value cannot match the shopper’s search string if it omits more than one word of the search string. Thus, only a property or dimension value that includes at least four of the five words in the search string “men’s large blue suede shoes” will match it.
The value of minWordsIncluded
specifies that a property or dimension value cannot match any search string if it includes fewer than two words of the search string.
Note: Setting minWordsIncluded
to a low value can increase the possibility of getting irrelevant results. Suppose, for example, that minWordsIncluded
is set to 1.
If the shopper enters the search string “purple jeans”, the search results include all records that match “purple jeans”. If it finds no records that match “purple jeans”, it returns any records that match “purple” or “jeans” – neither of which results is relevant to the shopper’s search.
To eliminate from the search results any records that match only the single words “purple “ or “jeans”, set minWordsIncluded
to 2. The search results now include only records that match “purple jeans”; if no records match “purple jeans” there will be no records in the search results.
Add a field to a search interface
You can add searchable fields to a search interface in any of the following ways:
- Using the Search tab of the Oracle Commerce administration interface.
- Using the Search and Navigation REST API to modify the configuration of the search interface.
Know how to make fields searchable
Index fields are examined for possible matches with the shopper’s search string only if the following conditions are met:
- They have been marked as searchable. Fields can be marked searchable by the merchandiser through the catalog view for editing product attributes, in the Oracle Commerce administration interface, and
- They have been added to the search interface as members, on the Search tab of the Oracle Commerce administration interface or through the Search and Navigation REST API, and
- They are members of the default search interface
All
.
Note: You can make a field not searchable by removing it from the search interface All
.
Know when changes that affect the search interface take effect
Changes that you make to a search interface through the Search and Navigation REST API take effect in the preview storefront immediately, without being published. Similarly, changes that you make to an existing search interface through the Search tab take effect in the preview storefront immediately.
However, none of these changes take effect in the live storefront until you have published changes in the catalog.
Toggling fields in the catalog to determine whether they are searchable, are facets, or are multi-select facets, does not take effect until the merchandiser publishes these changes.
For more information about when changes to search interface configuration take effect in your preview and live storefronts, see Apply configuration changes to your live storefront.
Export a search interface
You can export the search interfaces All
and TypeAhead
in ZIP format or JSON format in order to view them, edit them, or back them up.
After you export these search interfaces, you can modify them to meet your requirements.
To export search interface configuration in ZIP format, use the following endpoint:
GET /gsadmin/v1/cloud/searchInterfaces/searchInterfaceName.zip
To export search interface configuration in JSON format, use the following endpoint:
GET /gsadmin/v1/cloud/searchInterfaces/searchInterfaceName.json
or
GET /gsadmin/v1/cloud/searchInterfaces/searchInterfaceName
Note: The search interface’s name is not included in the JSON that configures the search interface.
The following example illustrates the JSON representation of a search interface named All
that can be exported by the endpoints above:
{
"ecr:lastModifiedBy": "admin",
"ecr:lastModified": "2016-03-27T13:39:15.486Z",
"ecr:createDate": "2016-03-27T13:39:15.486Z",
"ecr:type": "search-interface",
"crossFieldMatch": "always",
"fields": [
{
"attribute": "product.id"
},
{
"attribute": "product.sku"
},
{
"attribute": "product.code"
},
{
"attribute": "product.brand.name"
},
{
"attribute": "product.category"
},
{
"attribute": "product.name"
},
{
"attribute": "ecr:crossField"
},
{
"attribute": "product.long_desc"
}
]
}
Note: The endpoints GET/gsadmin/v1/cloud/searchInterfaces.zip
and GET/gsadmin/v1/cloud/searchInterfaces.json
return a list of search interfaces that does not include the full configurations of the individual search interfaces.
Create a folder object for search interfaces
If a folder object for search interfaces does not exist, you must re-create it. Do not attempt to create more than one searchInterfaces
folder.
The searchInterfaces
folder must contain a search interface named All; if All is missing, shoppers cannot search the catalog. It must also contain a search interface named TypeAhead if typeahead functionality is to be enabled for shoppers’ search strings.
Use the following endpoint to create the searchInterfaces
folder:
POST /gsadmin/v1/cloud/searchInterfaces
The POST endpoint must import the following JSON configuration:
{
"ecr:type": "search-interface-folder"
}
Note: For most purposes, it is convenient to create the search interface All
when you create the searchInterfaces
folder. In this case, the JSON configuration that you provide as input to the POST request includes the configuration of All
as well as the configuration of the searchInterfaces
folder.
Create a search interface
Note: Only two interfaces are supported: All
and TypeAhead
. Thus, you will need to create a search interface only if, for whatever reason, one of these search interfaces is missing. Do not attempt to create or use search interfaces other than All
and TypeAhead
.
In JSON format or ZIP format, use a POST endpoint to create the configuration of a search interface.
For example, the following endpoint imports configuration of a search interface named All
:
POST /gsadmin/v1/cloud/searchInterfaces/All
The endpoint must include JSON configuration of the search interface All
as its content; for example:
{
"ecr:type": "search-interface",
"crossFieldMatch": "always",
"fields": [
{
"attribute": "product.id"
},
{
"attribute": "product.sku"
},
{
"attribute": "product.code"
},
{
"attribute": "product.brand.name"
},
{
"attribute": "product.category"
},
{
"attribute": "product.name"
},
{
{
"attribute": "ecr:crossField"
},
"attribute": "product.long_desc"
}
]
}
Note: The JSON object that configures a search interface does not specify the name of the search interface. Instead, the name of the search interface is assumed to be the same as the name of the subfolder (for example, All
) where the search interface is created.
Replace configuration of a search interface
In ZIP format, you can use the following POST endpoint to replace the current configuration of a search interface in its entirety. For example, the following endpoint replaces configuration of the search interface ALL
:
POST /gsadmin/v1/cloud/searchInterfaces/All
In JSON format, you can use the following PUT endpoint to replace the current configuration of a search interface in its entirety. For example, the following endpoint replaces configuration of the search interface ALL
:
PUT /gsadmin/v1/cloud/searchInterfaces/All
The PUT method can only replace a search interface in its entirety; it cannot replace parts of a search interface. An error results if you attempt to PUT a search interface with a given name when no search interface with that name currently exists.
Modify configuration of a search interface
In JSON format, you can use a PATCH endpoint to modify the configuration of a search interface by adding attributes to it or changing the values of existing attributes. For example, the following endpoint modifies the configuration of the search interface All
:
PATCH /gsadmin/v1/cloud/searchInterfaces/All
For example, suppose that the search interface All
is currently configured as follows:
{
"ecr:lastModifiedBy": "admin",
"ecr:lastModified": "2016-07-07T17:17:07.474-04:00",
"ecr:createDate": "2016-05-06T17:15:06.414-04:00",
"ecr:type": "search-interface",
"crossFieldMatch": "always",
"fields": [
{ "attribute": "product.displayName" },
{ "attribute": "product.brand" },
{ "attribute": "ecr:crossField" },
{ "attribute": "product.category" }
]
}
You can add a snippet size attribute to this configuration of All
by executing the PATCH endpoint above with the following input:
{
"ecr:type": "search-interface",
"fields": [
{
"snippetSize": 20,
"attribute": "product.short_desc"
}
]
}
The search interface ALL
is now configured as follows:
{
"ecr:lastModifiedBy": "admin",
"ecr:lastModified": "2016-07-07T17:17:07.474-04:00",
"ecr:createDate": "2016-05-06T17:15:06.414-04:00",
"ecr:type": "search-interface",
"crossFieldMatch": "always",
"fields": [
{ "attribute": "product.displayName" },
{ "attribute": "product.brand" },
{ "attribute": "ecr:crossField" },
{ "attribute": "product.category" },
{
"snippetSize": 20,
"attribute": "product.short_desc"
}
]
}
You can also use PATCH to modify the values of existing attributes. For example, to change the snippet size from 20 to 25, you can execute the PATCH method with the following input:
{
"ecr:type": "search-interface",
"fields": [
{
"snippetSize": 25,
"attribute": "product.short_desc"
}
]
}
Note: You cannot re-order the field members in a search interface using PATCH.