FactFinder search parameters

When sending a search request to FactFinder Search server (via REST API), a number of parameters can be specified to control what results are returned and how. Some of these parameters are required, while others are optional or context-specific.

Whenever data is passed to FactFinder, it is important that the encoding is set correctly. UTF-8s the default and required encoding for FactFinder to handle special characters properly

The available search parameters are also documented in the Swagger-UI under the method search.

Basic Parameters

These are the fundamental parameters that are commonly used in nearly every search request:

• query (string, required) – The search term or phrase to look up in the FactFinder database. This parameter, together with channel, is mandatory for every search request. It represents what the user is searching for.

• channel (string, required, path) – The identifier of the channel to search in. If Search environment contains multiple channels (e.g., one per language or category of products), this parameter specifies which channel to use for the query. If no channel is specified, the system will default to the first channel configured on the server.

• page (integer) – The page number of results to retrieve. Search results are paginated when there are more items than the default page size. This parameter allows to request a specific page of the total results. Page numbering starts at 1 (page=1 is the first page of results).

• hitsPerPage (integer) – The number of results to return per page. The FactFinder management interface defines a default number of hits (results) per page for the search. By using hitsPerPage this default will be overwritten for a given query. For example, hitsPerPage=20 will request 20 results in the response. If not specified, the default configured value is used.

• sort (array of string) – Specifies sorting criteria for the results, other than the default relevance sort. One or multiple sort criteria can be specified. Each criterion is usually given as FieldName:order. The order can be asc (ascending) or desc (descending). If multiple sort criteria are provided, they are applied in sequence. For example, sort=Manufacturer:asc would sort results by the "Manufacturer" field in ascending order.

• filter (array of string) – Filters the results by specified field values. A filter restricts the result set to records that have certain values in a given field (often used for category filters, attribute filters, etc.). The format typically is filter=FieldName:Value

A filter can have multiple values, the values can be separated with the following characters (configurable in the config.xml)":

• ‘and’ = ___

• ‘or’ = ~~~

A filter value can be excluded with the prefix ! format: filter=color:Red~~~!Green could be interpreted as color is Red OR color is NOT Green. In this example, ~~~ is used as an OR separator between "Red" and "!Green". The ! prefix before "Green" indicates exclusion of that value.

Numeric filters use the standard mathematical interval notation, but only intervals that are closed on the left side and open on the right side are allowed as input. Thus, only intervals of the form [a,b), [a,), or [a,] are allowed. Square brackets [ ] denote inclusive boundaries and parentheses ( ) denote exclusive boundaries.

For values of type date, the same notation as for numeric filters can be used. For example, to include all items with a start date within the 1990s, a filter could be: filter=startdate1: [1990-01-01T00:00:00+00:00,2000-01-01T00:00:00+00:00). The format of the date can be either ISO-8601 with timezone (yyyy-MM-dd'T'HH:mm:ssZZ), a Unix timestamp in milliseconds, or the format that is defined for the specific field.

• substringFilter (array of string) - Filter for a sub string of the field value. A filter can have multiple values, the values can be separated with the following characters (configurable in the config.xml)

  ‘and’ = ___

  ‘or’ = ~~~

A filter value can be excluded with the prefix ! format

• searchField (string) - While FactFinder normally searches all fields that have been defined as searchable, it is also possible to restrict the search to only one specific field using this parameter.

• articleNumberSearch (string) - Specifies whether the query should be interpreted as an article number. The default value is DETECT

• sid (string) - Represents the Session-ID associated with the search request.

• userInput (string) - This parameter is used to transmit the characters entered by the shop user until the search query was triggered.

• queryFromSuggest (boolean) - Indicates that the query was initiated through a selection made from the suggestion list. In this scenario, the parameter should be sent with the value true.

Parameters used to control the search process

• useSearch (boolean) - If set to true, the search will be executed for the provided query. The default value for this parameter is true.

• useAsn (boolean) - If set to true, filters should be generated for the search results. The default value for this parameter is true.

• useFoundWords (boolean) - Controls whether the words that were used to locate the data records are returned for the found results. Determining these words requires CPU time, and for this reason, this function is disabled by default (false). Set the parameter to true to enable the generation of search words or false if search words are not required. The default value is false.

• useCampaigns (boolean) - Controls whether the Campaign Manager evaluates if the search query matches a configured campaign. If set to true, campaigns are evaluated and returned as appropriate. If set to false, campaigns are ignored.

• idsOnly (boolean) - By default, the search result includes all field information about the found products. If only the IDs of the products are needed, this parameter can be set to true to prevent the field content from being returned, thereby saving bandwidth. The default value is false, meaning field content is passed.

• useCache (boolean) - If set to true, the search result will be returned from the cache memory if a possible matching result already exists in the cache. The default value for this parameter is true.

• cacheIrrelevant (array of string) - Used to flag specific parameters as irrelevant for caching purposes.

• usePersonalization (boolean) - Allows for the activation or deactivation of query personalization. If set to true, the search result will be personalized, provided the personalization module is activated and all other relevant requirements are met. If set to false, the search result will not be personalized. The default value for this parameter is true.

• useSemanticEnhancer (boolean) - Allows for the activation or deactivation of the semantic enhancement of queries. If set to true, the search result will be semantically enhanced, provided the enhancer module is activated and all other relevant requirements are met. If set to false, semantic enhancement is not applied. The default value for this parameter is true.

• useAso (boolean) - Allows for the activation or deactivation of automatic search optimization. If set to true, the search result will be optimized automatically. If set to false, the search result will not be optimized. The default value for this parameter is true.

• maxCountVariants (integer) - If product variants are used in the data (for example, a product that has multiple variants like different sizes or colors), this parameter defines the maximum number of variant items to return for each main product record in the results. This can be used to limit how many variants are returned to avoid an overly large response.

• advisorStatus (string) - Used in conjunction with Advisor (a guided selling or campaign feature). This parameter can carry the current campaign ID and the user's answer path in a guided selling scenario. The format expected is typically campaignId-answerPath. It helps FactFinder know the state of a dialog or advisor campaign when processing the query.

• useDeduplication (boolean) - If set to true, the configured deduplication of variants will be applied to the search results. The default value for this parameter is true.

• deduplicationField (string) - Specifies the field upon which variants should be deduplicated.

Additional parameters

• format - The response format of the search results. Since the XML and JSON interfaces are invoked via a URL, a parameter is needed to specify the format in which the search result should be delivered. If no value is assigned to this parameter, the result is returned in HTML format by default. Possible values that can be used are xml, json, and jsonp.

• version - To facilitate migration to newer versions, FactFinder provides versioned APIs. This allows updates to a newer FactFinder version to be performed without requiring immediate changes to the integration code. If necessary, the integration code can be adjusted subsequently to utilize new functions introduced in the newer version. In FactFinder 7.2, the values 6.11, 7.0, 7.1, and 7.2 can be used for this parameter. Please note that a default version is configured in the application settings, making the explicit use of this parameter unnecessary by default.

• omitContextName- If the value true is passed for this parameter, the returned search parameter URLs will commence with the action name instead of the name of the FactFinder server application. This functionality can be beneficial in load-balanced installations where different FactFinder applications may have distinct names, or it can be used in standard deployment scenarios to potentially reduce the volume of data being transmitted.

• log - An optional parameter that allows attaching a custom description string to the search request for logging purposes. Has to be passed in addition to the search query. The value of the parameter is the description of the log file. In certain situations, it is useful to include a description within a log file, for example, when only specific search requests are to be evaluated. The provided description will then be visible during the analysis of the log file. The value assigned to this parameter should only contain letters and numbers.