WebSphere Commerce Search interface

The search interface on the WebSphere Commerce Search server is made up of a set of search-related control parameters. These parameters are represented as an internal Java representation called the SearchCriteria object.

Search run time

The search runtime programming consists of REST services, a search runtime framework , and a set of WebSphere Commerce foundation services that also provide access to the WebSphere Commerce database. The search framework reuses the current search programming model. Instead of using BOD and doing object-based mediation, the search programming model does not rely on any SDO. Instead, it uses POJO and raw data that is returned from the search server to do simple name-value pair mapping.

WebSphere Commerce Search REST APIs

The WebSphere Commerce API contains handler classes specific to WebSphere Commerce search, such as the following resources:

• search_product

• search_category

• search_site_content

Control parameters

Search profile (_wcf.search.profile)

Defines a collection that groups a set of search runtime parameters such as search index name, search index fields, expression providers, paging and sorting. The profile also defines search feature configurations such as text highlights, facets, and spelling correction. Therefore, it is possible to control the storefront search experience at a page-level by using different search profiles.

See WebSphere Commerce Search configuration file (wc-search.xml).

Filters (_wcf.search.(exclude.)term, _wcf.search.category, _wcf.search.(exclude.)facet, _wcf.search.manufacturer, _wcf.search.price.minimum/maximum)

These parameters are search criteria that trigger a search operation to run. As these actions can be tracked for later reference, these parameters cannot be sticky or carried forward to future search requests. For example, performing faceted navigation after a keyword search is returned first involves a search by keyword. Then, the keyword is stored in the second facet search request's context.

Filters (_wcf.search.meta)

Contains the input metadata string, that is, the previous click history of the current sequence of requests. It remembers only parameters provided by the user through the storefront. Do not store internal meta information, such as store-path, that can be regenerated upon the next request. The exceptions are that the only user-specified parameters that are not remembered are keywords and category ID. They are always passed in to start the marketing logic that generates the proper e-Marketing Spots.

To achieve sticky behavior, a server-generated meta string is attached with all subsequent requests. This meta string contains all previously run search context, such as applied facets. This meta string is encoded with UTF8 base64 and is therefore URL-friendly.

Match type (_wcf.search.type)

The match type can be used to define more precise search instructions on how the search engine can run the search operation with the set of keywords.

For example, the following samples provide several usage combinations for two search terms, t1 and t2, against two fields, f1 and f2:

• Include EXACT +(f1:"t1 t2" f2:"t1 t2")

• Include NONE -(f1:(t1 t2) f2:(t1 t2))

• Include ALL +(f1:(+t1 +t2) f2:(+t1 +t2))

• Include ANY +(f1:(t1 t2) f2:(t1 t2))

• Exclude EXACT -f1:"t1 t2" -f2:"t1 t2"

• Exclude ANY or ALL -f1:(t1 t2) -f2:(t1 t2)

The following subexpression is appended, where the value of this parameter is used for identifying whether to include SKU as part of the search scope:

• Exclude SKU -catenttype_id_ntk_cs:ItemBean

• Only SKU +catenttype_id_ntk_cs:ItemBean

The possible values for assigning to _wcf.search.type are:

• 0: ANY (exclude SKU)

• 1: EXACT (exclude SKU)

• 2: ALL (exclude SKU)

• 3: NONE (exclude SKU)

• 10: ANY (include SKU)

• 11: EXACT (include SKU)

• 12: ALL (include SKU)

• 13: NONE (include SKU)

• 100: ANY (only SKU)

• 101: EXACT (only SKU)

• 102: ALL (only SKU)

• 103: NONE (only SKU)

• 1000: ANY (include products, kits, bundles, category level SKU) (exclude product level SKU)

• 1001: EXACT (include products, kits, bundles, category level SKU) (exclude product level SKU)

• 1002: ALL (include products, kits, bundles, category level SKU) (exclude product level SKU)

• 1003: NONE (include products, kits, bundles, category level SKU) (exclude product level SKU)

• 10000: ANY (include category level SKU) (exclude products, kits, bundles, product level SKU)

• 10001: EXACT (include category level SKU) (exclude products, kits, bundles, product level SKU)

• 10002: ALL (include category level SKU) (exclude products, kits, bundles, product level SKU)

• 10003: NONE (include category level SKU) (exclude products, kits, bundles, product level SKU)

The value of this parameter must be passed in always during search or navigation, since it is not remembered by the meta string.

Custom optional search expression (_wcf.search.expr)

Optional: The caller can include a search engine native expression in the request by using this control parameter. However, this usage is not recommended, since it turns the search expression into a search engine-specific instruction.

Custom mandatory search expression (_wcf.search.mandatory.expr)

The value of this parameter is passed in always during search or navigation. It is only used in SolrRESTSearchByCustomExpressionProvider to append the expression to the main search query with an AND operator.

Custom sorting (_wcf.search.sort)

Allows the caller to override the relevancy ranking order from the search engine. The value that is given in this parameter is a logic name that is defined in the search profile. It is then mapped into a physical index column name and sorting order.For example:

<_config:sort>
  <_config:field name="1" value="mfName_ntk_cs asc" />
  <_config:field name="2" value="name_ntk_cs asc" />
  <_config:field name="3" value="price_* asc" /> 
  <_config:field name="4" value="price_* desc" /> 
</_config:sort>

_wcf.search.category.limitSubCategories

This comma-separated list of numbers controls the depth of subcategories and limit the number of items returned under each category level.

The first number in the list determines the maximum number of categories to be shown under the requested category.

The second number in the list determines the maximum number of categories to be shown under the first-level categories.

A value of -1 implies no limit.

Custom search expression for exclusion (_wcf.search.filter.expr)

The value of this parameter is passed in always during search or navigation. It is only used in SolrRESTSearchByCustomExpressionProvider.

Page size setting (_wcf.search.page.size_)

The value of this parameter is used for allowing the shopper to pass in the size of each page in the search result.

Page number setting (_wcf.search.page.number)

The value of this parameter is used for allowing the shopper to pass in the starting page in the search result.

_wcf.search.facet.field.limit

The maximum number of constraint counts that can be returned for all facets.

The format of the parameter value is facet_field_name:number_of_constraint_counts. For example, _wcf.search.facet.field.limit='mfName_ntk_cs:3'.

Use a negative number to request all constraint counts.

_wcf.search.partnumber

The catalog entry's part number.

_wcf.search.store.physical

The physical store identifier to be used for retrieving inventory count.

_wcf.search.internal.store.path

Stores the calculated store path.

Mandatory control parameters

The following list describes mandatory search and browsing context required for each search request:

_wcf.search.catalog

The catalog to be used for the current search request.

_wcf.search.currency

The currency to be used for the current search request.

_wcf.search.language

The language identifier to be used for the current search request.

_wcf.search.store.online

The online store identifier to be used for the current search request.

B2B entitlement control parameters

_wcf.search.contract

Control parameter used internally for representing contract entitlement information.

_wcf.search.hostcontract

Control parameters used internally for representing hosting contract identifier.

_wcf.search.eligible.contract

Control parameters used internally for representing a list of eligible contracts that belong to the current user.

_wcf.search.current.contract

Control parameters used internally for representing the contract set in session for the current user.

_wcf.search.internal.entitlement.expression

Control parameters used internally for the entitlement search expression.

REST services mapping control parameters

_wcf.search.internal.service.resource

Search service resource name for the current request.

_wcf.search.internal.service.resource.url

Search service resource URL for the current request.

_wcf.search.internal.response.format

Search service response format to be used for the current request. REST services support JSON and XML formats for input and output data by default. The default format is JSON.

_wcf.search.internal.response.template

We can create a representation template (JSP file) per resource in the file system used to generate the representation for specific media types, such as XHTML and Atom feeds.

_wcf.search.internal.response.fields

A list of return fields for the search response.

Internal use control parameters

_wcf.search.index

Defines the core name for the search request.

_wcf.search.internal.experiment

The value of this parameter is used to represent the experiment for AB testing. It consists of four part identifiers in the following sequence: marketing spot, activity, experiment, and test element.

_wcf.search.internal.filterquery

Defines a multivalue list of filter query criteria.

_wcf.search.internal.sort

Contains the value of this parameter to carry sorting for internal nested searches.

_wcf.search.internal.boostquery

Contains the value of the boost query used to influence the relevancy score of the results. This parameter is used with the _wcf.search.internal.query. The boost query affects the scoring of the items that already match the query in the _wcf.search.internal.query. If a matched item also matches the _wcf.search.internal.query, it is scored higher or lower, depending on whether the boost query increases or decreases the relevancy score.

_wcf.search.internal.mandatory.query

Contains partial search expressions to be used in the query section of the search expression. Each element in this array is treated as a separate term and is AND together to form the final expression for the search engine. That is, all expressions must match the searched documents. These expressions can be used with the expressions from _wcf.search.internal.optional.query. Not all values specified can be remembered in the meta string.

Note: This parameter is multivalue.

_wcf.search.internal.optional.query

Contains partial search expressions to be used in the query section of the search expression. Each element in this array is treated as a separate term is OR together to form the final expression for the search engine. That is, at least one of the expressions must match the searched documents. These expressions can be used with the expressions from _wcf.search.internal.mandatory.query. Not all values specified can be remembered in the meta string.

Note: This is a multivalue parameter.

_wcf.search.internal.filterquery

Contains expressions for a filtered query expression. Each element in this array is treated as a separate term and are assigned individually as separate fq parameters when it is sent to the search engine. These values can resemble filters (also known as AND - intersections) of all the result sets.

Note: This is a multivalue parameter.

_wcf.search.intent.term

The value of the parameter is the term that the user intends to search. The difference between _wcf.search.intent.term and _wcf.search.term is that _wcf.search.term has been escaped with Solr reserved characters.

_wcf.search.originalterm

The value of the parameter is the original term that initiates the second spell-corrected search request, _wcf.search.originalterm is not escaped with Solr reserved characters as _wcf.search.intent.term.

_wcf.search.source

Used as a notion for identifying the source nature of the keyword search request from the storefront.

The following are the acceptable values:

Q

Quick search.

A

Advanced search.

S

Spell correction.

N

Navigation.

O

Others.

_wcf.search.internal.synonyms

Used internally for synonym expansion.

_wcf.search.catalogfilter

_wcf.search.contract

Control parameters used internally for representing contract entitlement information.

_wcf.search.facet.field

_wcf.search.facet.properties

_wcf.search.facetquery.field

Used internally to represent facet operations.

_wcf.search.internal.workspace.schema

_wcf.search.internal.workspace.indexname

Used internally to represent current workspace-related information.

_wcf.search.internal.edismax.mm

Used internally to represent the minimum number of search criteria that must match.

By default, all words or phrases specified in the q parameter are treated as optional clauses unless they are preceded by + or - characters.

When it is used with the optional clauses, the mm option enables the choice to select the minimum number of clauses that must match (mm).

Default is 1. However, when the search uses the All match type, the default value is set to 100%.

_wcf.search.internal.edismax.queryfields

Used internally to represent the list of query fields and their corresponding boost factors.

_wcf.search.edismax.maxSlop

Used internally to represent the maximum phrase slop in the Solr Dismax query.

A sloppy phrase query specifies a maximum "slop", or the number of positions tokens need to be moved to get a match. The closer together the two terms appear in the document, the higher the score.