Configuring search interfaces

This section describes search interfaces, the underlying configurable mechanism through which a storefront shopper's search for product data records is executed. 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:

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:

The dimensions and properties in a search interface must be enabled for record searches. For more information, see Introduction: configuring dimensions and Endeca record properties .

Search interfaces can contain both wildcard-enabled and non-wildcard-enabled members. Only wildcard-enabled members return wildcard-expanded results, however. Wildcard search can be enabled for particular dimensions and 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

ecr:type

(required) search-interface

Specifies that this JSON document configures a search interface.

crossFieldMatch

always, never, or onFailure

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.

 

always

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 crossFieldMatch to always.

 

never

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.

 

onFailure

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.

partialMatch

maxWordsOmitted and minWordsIncluded

Specifies whether partial query matches should be supported for the search interface that contains this element.

 

maxWordsOmitted

A positive integer or zero. If the original keyword search term includes N words, then all results will match at least N - maxWordsOmitted words. The default is 2.

 

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 array specifies a member of the search interface.

 

attribute

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 Endeca records.

 

ecr:crossField

Specifies the relevance rank value for cross-field matches. The value depends on the position of ecr:crossfield in the fields array. The relevance rank values of members determine the position in the results list of records that match the members.

Note

Include ecr:crossfield only if the value of crossFieldMatch is Always.

snippetSize

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.

ecr:lastModifiedBy

user ID

The user who last modified the search interface. Read-only; system-generated.

ecr:lastModified

time stamp

The time when the search interface was last modified. Read-only; system-generated.

ecr:createDate

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 following diagram illustrates the effect of setting crossFieldMatch to Always:

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 figured 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:

  1. Export the All search interface, using exportContent, to determine whether it meets your requirements.

  2. Modify All to meet your requirements and it import them using importContent.

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:

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:

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: 

"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: 

{ 
  "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:

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.

Copyright © Legal Notices