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 runtime

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

WebSphere Commerce search REST APIs

The WebSphere Commerce API contains classes that are specific to WebSphere Commerce search, such as the ProductViewHandler, CategoryViewHandler, and SiteContentHandler:

They have the following benefits over the BOD-based REST services:

The services are served by the search server and can be separately scaled from the WebSphere Commerce server. Instead, the WebSphere Commerce server is used for processing transactional requests.
The WebSphere Commerce search REST API is built to extract data from Solr queries, avoiding the need for the BOD mediation layer.

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, and search feature configurations such as text highlighting, facets, and spelling correction. It is therefore 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) (Search EAR) for more information.

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 perform. As these actions should 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. This operation 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 meta data 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 not remembered are keywords and category ID. They are passed in at all times for the purpose of invoking the marketing logic to generate 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-executed search context, such as facets that have been applied. This meta string is encoded using 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 should perform the search operation with the given 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 at all times 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 using this control parameter. However, this is typically not recommended since this 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 at all times during search or navigation. It is only used in SolrRESTSearchByCustomExpressionProvider to append the given 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 given in this parameter is a logic name defined in the search profile where 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.

Note: The maxRows property in the current request's search profile overrides this parameter. Search profiles and maxRows property are set in the wc-search.xml configuration file. For more information, see WebSphere Commerce search profiles.

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

The value of this parameter is passed in at all times 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 should 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

Stories the precalculated store path.

Mandatory control parameters

The following is a list of 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 that is 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: You can create a representation template (JSP file) per resource in the file system that is 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 this parameter to contain the boost query used to influence the relevancy score of the results. This parameter is used in conjunction 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'ed together to form the final expression for the search engine. That is, all expressions must match the searched documents. These expressions can be used in conjunction with the expressions from _wcf.search.internal.optional.query. Not all values specified should be remembered in the meta string.

Note: This is a multivalue parameter.

_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'ed 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 in conjunction with the expressions from _wcf.search.internal.mandatory.query. Not all values specified should 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 sending to the search engine. These values can resemble filters (also known as AND'ed - 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 performs 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 working with the optional clauses, the mm option enables the choice to select the minimum number of clauses that must match (mm).

The default value is 1. However, when using 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 will be.