Specify which index fields are included in searches

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 in All 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 which typeahead functionality is enabled. Removing an index field from TypeAhead disables typeahead functionality for searches on that index field. Note that because wildcarding is required by the typeahead feature, wildcarding is enabled by default for all members of the TypeAhead 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 whose product.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 dimension product.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. `always` is the recommended setting for most purposes. See below for a description of the effect of setting `crossFieldMatch` to `always`. Note: If `crossFieldMatch` is not specified, always is used as a default.
`crossFieldMatch`	`never`	Requires that the entire search string be found within the same member in order to make a match. You can set `crossFieldMatch` to never only when the `ecr:crossField` attribute is not a member of the fields array.
`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 `crossFieldMatch` to `onFailure` only when the `ecr:crossField` attribute is not a member of the fields array.
`partialMatch`	`maxWordsOmitted` or `minWordsIncluded` (See below.)	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 `fields` array specifies a member of the search interface. An attribute can represent a property or a dimension. The position of the attribute `ecr:crossFields` in the `fields` array specifies the position in the search results of any records that are added to the search results because of cross field matches. Note: Include `ecr:crossfield` only if the value of `crossFieldMatch` is `Always`. Note also that `ecr:crossfield` is used only if the `Fields` module is included in your relevance ranking strategy. For information about relevance ranking strategies, see Configure the ranking of records in search results.
`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 to Always, as follows:
"crossFieldMatch": "always"

The members of the search interface include a dimension named product.category and a property named product.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 named product.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 named product.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.