This section describes search interfaces, the underlying configurable mechanism through which record searches are executed in response to a storefront shopper's query. It also describes the components of search interfaces and the JSON syntax for configuring these components.
Record searches must be performed through search interfaces, which specify the index fields (properties or dimension values) that are to be examined as possible matches with search strings entered by shoppers. Search interfaces also specify the criteria for matches between index fields and search strings. A search interface thus limits which records can be returned by a search.
A record search returns:
A search interface configures the behavior of record searches by:
Specifying which index fields (record properties or dimensions) are examined as possible matches with shoppers' search strings.
Specifying the criteria for matches between search strings and index fields.
Determining the order in which records appear in the search results (together with a relevance ranking strategy).
For information about how to create index fields based on your production data, see Running a record store merger.
The following diagram illustrates how a search interface selects the records that appear in the results list, given a particular search term ("boots") entered by the user:
As shown in the diagram, this sample search interface includes the following members, among others:
Note
A search interface does not in any way define or control the behavior of the user interface of your front end application.
A search interface is configured by a JSON document that includes the following components:
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.
an attribute array of fields, each of which corresponds to a dimension or record property that is to be examined as a possible match for the search string entered by the shopper.
The dimensions and properties in a search interface must be enabled for record searches.
Search interfaces can contain both wildcard-enabled and non-wildcard-enabled members. Only wildcard-enabled members return wildcard-expanded results, however.
Note
Wildcard search can also be enabled for particular dimensions and record properties; for information about how to do this, see Configuring dimensions and properties in JSON format.
When no other sorting or filtering applies, the order of records in a
results list returned by the search interface will correspond to the order of
the members in the
fields
array. The position of the
ecr:crossField
element in the
fields
array determines the position in the results
list of records that are added to the list because of cross-field matches. The
ecr:crossField
element is taken into account only when
the
crossFieldMatch
attribute is set to
always
.
The configuration of these components is stored in the Endeca Configuration Repository (ECR). You can import JSON documents into the ECR to create search interfaces, export search interfaces in JSON format for viewing, updating, and archiving, and re-import exported JSON after updating it.
A search interface is configured by a JSON document that comprises the parameters listed in the table below.
Parameter |
Possible values |
Description |
---|---|---|
|
(required)
|
Specifies that this JSON document configures a search interface. |
|
|
Specifies whether parts of a search term can be individually matched with different members; for example, given the search term "red shoes", can matches be made between "red" and one member, and between "shoes" and another member? Cross field matches can be made between dimensions, between properties, or between dimensions and properties. |
|
Causes the search engine always to look for
matches between members of the search interface and the parts of a search term.
ALWAYS is the recommended setting for most purposes. See below for an
illustration of the effect of setting
| |
|
Requires that the entire search term (that is, all words that the shopper entered to search for) be found within the same member in order to make a match. | |
|
Causes the search engine to look for matches between members of the search interface and parts of a search term only if it cannot match the entire search term to any single member of the search interface. | |
|
true, false |
true specifies that wildcard search is enabled on all members of the search interface.
Thus, an attribute that is a member of this search
interface is enabled for wildcard search. You can also enable an attribute for
wildcard search by setting its
|
|
|
Specifies whether partial query matches should be supported for the search interface that contains this element. |
|
A positive integer or zero. If the
original keyword search term includes
N words, then all results will match at least
N -
| |
|
A positive integer. All results will match at least this many words from the search query. The default is 2. | |
|
(required) array of attributes |
Each attribute in the array specifies a member of the search interface. |
|
A record property or a dimension. The property or dimension must be configured to be searchable. For information about how to configure a property or dimension to be searchable, see Configuring dimensions, dimension values, and Guided Search records. | |
|
Specifies the relevance rank value for
cross-field matches. The value depends on the position of
NoteInclude
| |
|
positive integer |
Specifies the maximum number of words that a snippet can contain. Omitting this attribute or setting its value to zero disables snippeting. For information about snippeting, refer to the MDEX Engine Developer's Guide. Note: Snippets are useful for document searches, but are not ordinarily used by eCommerce sites. |
|
user ID |
The user who last modified the search interface. Read-only; system-generated. |
|
time stamp |
The time when the search interface was last modified. Read-only; system-generated. |
|
time stamp |
The time when the search interface was created. Read-only; system-generated. |
The following JSON document illustrates the configuration of a search interface:
{ "ecr:type":"search-interface", "crossFieldMatch":"always", "partialMatch": { "maxWordsOmmitted":0, "minWordsIncluded": 1 }, "fields": [ { "attribute":"product.displayName" }, { "attribute":"product.brand" }, { "attribute":"ecr:crossField" }, { "attribute":"product.category" }, { "attribute":"product.long_desc" } ] }
The Discover application provides a default search interface named All which you can modify to meet your requirements.
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 members of 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.
You can specify which index fields are included as members in All using the Search and Navigation REST API endpoints to modify the configuration of the search interface.
By default, the search interface All is configured as follows:
{ "ecr:type": "search-interface", "crossFieldMatch": "always", "fields": [ { "attribute": "product.displayName " }, { "attribute": "product.brand" }, { "attribute": "ecr:crossField" }, { "attribute": "product.category" } ] }
The search interface All is stored in a collection folder named
searchInterfaces
. If either this search interface or
this folder has been deleted, you must re-create them before shoppers can
perform record searches.
You can modify the default search interface All using the endpoints described in this chapter.
For information about how to use a search interface other than the one named All, see Specifying the search interface that your application uses.
This section describes how to view, replace, modify, create, and delete search interface configuration, locally and remotely.
You can export the
configuration of a search interface for viewing, editing, or archiving using
the IFCR command
exportContent
. You can create a search interface, or
modify an existing one, using the IFCR command
importContent
. The
importContent
and
exportContent
commands are run locally on the machine
where Guided Search is hosted.
To execute these commands, use the
runcommand[.bat|.sh]
script, which is installed by
default in the
/Endeca/Apps/application/control
directory. For
example:
/Endeca/Apps/Discover/control/runcommand.bat IFCR exportContent searchInterfaces/All D:\Export\Temp\
You typically use these commands in the following sequence:
The IFCR
exportContent
command enables you to export a single
search interface or a list of the currently configured search interfaces from
the ECR to a specified location on your file system.
To
export a search interface locally, use an
exportContent
command of the following form:
runcommand.bat IFCR exportContent searchInterfaces/searchInterfaceName directory
where:
searchInterfaces
is collection folder for search interfaces. You must specifysearchInterfaces
.searchInterfaceName is the name of the folder that contains the search interface to export. The search interface is exported in a zip file that has the same name as this folder.
directory is the pathname of the directory in your local file system into which the zip file containing the search interface configuration is downloaded.
For example, the following command exports the search interface
All
in a zip file named
All.zip
to the directory
D:\Export\Test
on your local machine:
runcommand.bat IFCR exportContent searchInterfaces/All D:\Export\Test
When this command is executed, a file named
All.zip
is exported to the directory
D:\Export\Test
.
All.zip
. It contains a file named
_.json
, which contains the JSON configuration of the
search interface
All
; for example:
{ "ecr:lastModifiedBy": "admin", "ecr:lastModified": "2017-01-25T16:38:14.904-05:00", "ecr:createDate": "2017-01-25T16:38:14.904-05:00", "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"}, { "snippetSize": 25, "attribute": "product.short_desc" }, {"attribute": "product.long_desc"}, {"attribute": "ecr:crossField"} ] }
Note: The name of the search interface is not specified in its JSON configuration.
To export the currently configured search interfaces locally, use a command of the following form:
runcommand.bat IFCR exportContent searchInterfaces directory
where:
searchInterfaces
is the ECR root folder for search interfaces. This folder contains all currently configured search interfaces. You must specifysearchInterfaces
.directory
is the pathname of the directory in your local file system into which a zip file containing all configured search interfaces will be downloaded. The zip file is namedSearchInterfaces.zip
.
For example, the following command exports the zip file
SearchInterfaces.zip
to the directory
D:\Export\Temp
on your local machine:
runcommand.bat IFCR exportContent searchInterfaces D:\Export\Temp
The file
SearchInterfaces.zip
contains the following files:
A file containing the JSON configuration of the currently configured search interface; for example:
{ "ecr:lastModifiedBy": "admin", "ecr:lastModified": "2016-01-13T09:28:03.310+05:30", "ecr:createDate": "2016-01-13T09:28:03.310+05:30", "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"} ] }
A file containing JSON configuration of the
searchInterfaces
folder; for example:
"ecr:lastModifiedBy": "admin", "ecr:lastModified": "2016-01-27T11:53:38.649+05:30", "ecr:createDate": "2016-01-27T11:53:38.649+05:30", "ecr:type": "search-interface-folder"
The IFCR
importContent
command enables you to create or update a
search interface by importing into the ECR a JSON document stored on your file
system. The JSON document must be contained in a ZIP file. An imported search
interface replaces any existing search interface with the same name.
Search interfaces must be created within the
searchInterfaces
collection folder. If the
searchInterfaces
folder does not exist, you must
re-create it -- and also create the search interface named
All
within
searchInterfaces
-- before shoppers can search the
catalog.
To create a
searchInterfaces
folder, use the following
importContent
command:
runcommand.bat IFCR importContent searchInterfaces pathname\filename.zip
where:
searchInterfaces
is the collection folder for search interfaces. You must specifysearchInterfaces
pathname is the pathname of the directory containing the ZIP file that contains the JSON file that configures the
searchInterfaces
folder. The JSON file must be named_.JSON
, and must contain the following JSON configuration:
{ "ecr:type": "search-interface-folder" }
For example:
runcommand.bat IFCR importContent searchInterfaces D:import\config\search_interfaces.zip
For most purposes, it is convenient to configure a search interface
through the same command that configures the
searchInterfaces
folder; for example, the following
configuration can be submitted to the
importContent
command above to configure both the
searchInterfaces
folder and the search interface
All
:
{ "ecr:type": "searchInterfaces", "All" : { "ecr:type":"search-interface", "crossFieldMatch":"always", "partialMatch":{ "maxWordsOmmitted": 0, "minWordsIncluded": 1 }, "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
Be sure to specify a name for any search interface that you create. If you do not specify a name, a long unwieldy name is generated by the system.
To create or update a search interface, use an
importContent
command of the following form:
runcommand.bat IFCR importContent searchInterfaces/searchInterfaceName pathname\filename.zip
where:
searchInterfaces
is the collection folder for search interfaces. You must specifysearchInterfaces
.searchInterfaceName
is the name of a folder created to hold the search interface imported by this command. The name of this folder will be used as the name of the search interface.pathname
is the pathname of the directory containing the ZIP file that contains JSON configuration of the search interface specified bysearchInterfaceName
. The JSON configuration must be in a file named_.JSON
.
For example, the following command creates a search interface in the
ECR folder named
All
:
runcommand.bat IFCR importContent searchInterfaces/All pathname\All.zip
The following example illustrates JSON configuration that can be
contained in the
_.JSON
file in
All.zip
:
{ "ecr:type":"search-interface", "crossFieldMatch":"always", "partialMatch":{ "maxWordsOmmitted": 0, "minWordsIncluded": 1 }, "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
This
importContent
command with this input entirely
overwrites the existing configuration of the search interface named All.
You can export the configuration of a specified search interface or a list of all currently configured search interfaces, using the Search and Navigation REST API. You can export search interface configuration in order to view it or modify it.
To export search interface configuration in ZIP format, use the following endpoint:
GET /gsadmin/v1/Discover/searchInterfaces/searchInterfaceName.zip
To export search interface configuration in JSON format, use the following endpoint:
GET /gsadmin/v1/Discover/searchInterfaces/searchInterfaceName.json
or
GET /gsadmin/v1/Discover/searchInterfaces/searchInterfaceName
where:
For example, the following GET request exports a search interface named All:
GET http://host:port/ifcr/gsadmin/v1/Discover/searchInterfaces/All
The following JSON document illustrates the default configuration of
the search interface named
All
, as returned in the GET response:
{ "ecr:lastModifiedBy": "admin", "ecr:lastModified": "2016-01-27T11:53:38.652+05:30", "ecr:createDate": "2016-01-27T11:53:38.652+05:30", "ecr:type": "search-interface", "crossFieldMatch": "always", "fields": [ {"attribute": "product.displayName"}, {"attribute": "product.brand"}, {"attribute": "ecr:crossField"}, {"attribute": "product.category"} ] }
To export search interface configuration in ZIP format, use the following endpoint:
GET /gsadmin/v1/Discover/searchInterfaces.zip
To export search interface configuration in JSON format, use the following endpoint:
GET /gsadmin/v1/Discover/searchInterfaces.json
or
GET /gsadmin/v1/Discover/searchInterfaces
where:
The following JSON document illustrates a list that might be returned
in the GET response; the list includes the search interface named
All
:
{ "ecr:lastModifiedBy": "admin", "ecr:lastModified": "2016-01-27T11:53:38.649+05:30", "ecr:createDate": "2016-01-27T11:53:38.649+05:30", "ecr:type": "search-interface-folder", "All": { "ecr:lastModifiedBy": "admin", "ecr:lastModified": "2016-01-27T11:53:38.652+05:30", "ecr:createDate": "2016-01-27T11:53:38.652+05:30", "ecr:type": "search-interface", "crossFieldMatch": "always" } }
Note
The list of search interfaces does not include the members of the individual search interfaces in the list.
This section describes how to create search interfaces remotely, using the Search Interface API.
Search interfaces are stored in a collection folder named
searchInterfaces
. If this folder does not exist on
your system, you must create it, and also create within it a search interface
named
All
. For most purposes, it is convenient to configure
a search interface through the same command that configures the
searchInterfaces
folder.
To create a
searchInterfaces
folder, execute the following POST
request:
POST http://host:port/ifcr/gsadmin/v1/Discover/searchInterfaces
Use the following request body with the POST request above to create
the
searchInterfaces
folder:
{ "ecr:type": "search-interface-folder" }
Using the above POST request, you can also import configuration the All search interface, using input such as the following:
{ "ecr:type": "search-interface-folder", "All": { "ecr:type": "search-interface", "crossFieldMatch": "always", "fields": [ { "attribute": "product.id" }, { "attribute": "product.sku" }, { "attribute": "product.code" }, { "attribute": "product.brand" }, { "attribute": "product.category" }, { "attribute": "product.name" }, { "attribute": "ecr:crossField" }, { "attribute": "product.long_desc" } ] } }
To create a search interface, execute a POST request of the following form:
POST http://host:port/ifcr/gsadmin/v1/Discover/searchInterfaces/interface-name
where
interface-name is used as the name of the search interface. For
example, the following POST request creates the search interface
All
:
POST http://host:port/ifcr/gsadmin/v1/Discover/searchInterfaces/All
For example, the following JSON can be used with the POST request above to configure the search interface named All:
{ "ecr:type": "search-interface", "crossFieldMatch": "always", "fields": [ { "attribute": "product.displayName" }, { "attribute": "product.brand" }, { "attribute": "ecr:crossField" , "attribute": "product.category" } ] }
Note
The request body above does not specify the name of the search
interface that it represents. Instead, the name of the search interface is
assumed to be the same as the name of the subfolder (in the example above,
All
) where the search interface is created.
You can replace or modify the configuration of a search interface over a remote connection, using the PUT and PATCH methods.
To replace a search interface in its entirety, use the PUT method. An error results if you attempt to PUT a search interface with a given name when no search interface with that name currently exists.
To modify an existing search interface by adding attributes or modifying existing attributes, use the PATCH method. To change the order of members in the fields array, use the POST method to overwrite the existing configuration with a new configuration that specifies the order of members that you want.
Note
The PUT and PATCH methods can be used only with JSON format. For information, see Understand ZIP format and JSON format (remote access only).
To replace a search interface remotely, execute a PUT request of the following form:
PUT
http://host:port/ifcr/gsadmin/v1/application/searchInterfaces/searchInterfaceName
where:
For example, the following endpoint replaces the current configuration of the search interface named All:
PUT
http://host:port/ifcr/gsadmin/v1/Discover/searchInterfaces/All
The body of the request to import a search interface must contain a JSON representation of the search interface that will replace the existing search interface; for example:
{ "ecr:type": "search-interface", "crossFieldMatch": "always", "fields": [ { "attribute": "product.id" }, { "attribute": "product.sku" }, { "attribute": "product.code" }, { "attribute": "product.brand" }, { "attribute": "product.category" }, { "attribute": "product.name" }, { "attribute": "ecr:crossField" }, { "attribute": "product.long_desc" } ] }
To modify a search interface remotely, execute a PATCH request of the following form:
PATCH
http://host:port/ifcr/gsadmin/v1/application/searchInterfaces/searchInterfaceName
where:
Note
When used to modify a search interface, the PATCH method can only add members to the fields array. It cannot delete members or change their order in the fields array.
To specify the
search interface that your application uses, specify the name of the search
interface as the value of the
defaultSearchKey
property of the
navigationStateBuilder
component in
assembler-context.xml
; for example:
<property name="defaultSearchKey" value="All" />
where:
value
must be set to the name of the search
interface. Currently, only use of the search interface
All
is supported.
You can also specify that keyword searches be made against a specific
record property, rather than through a search interface. To do this, specify
the record property as the value of the
value
attribute of the
defaultSearchKey
property of the
navigationStateBuilder
component in
assembler-context.xml
; for example:
<property name="defaultSearchKey" value="product.code" />
where:
value
is set to the record property
product.code
. All keyword searches will be against
this record property alone.
Note
Searching on a single record property is useful primarily for debugging a system. In this case, set the search key through the URL, using the Ntk parameter. This feature is not typically used in server-side configuration.