Fredhopper Query Language

The following section provides detailed background information on the Fredhopper Query Language and how the query strings should be constructed.

URL query string arguments

Most of the Fredhopper query string arguments are prefixed with 'fh_' and the current list can be found in the following article - https://support.crownpeak.com/hc/en-us/articles/11135737406237-Fredhopper-Query-Language

Please find some examples below:

Parameter Name	Values	Appearance	Description
fh_location	URL encoded location query //....	0..1	Location query (see subsequent section below).
fh_session		0..1	Session-ID in which the current request was triggered. Fredhopper does not use this information for its response but requires it for reporting purposes.
fh_secondid	valid secondid	0..N	Specifies the secondid (the Fredhopper internal unique identifier) of an item to be displayed in the detail or compare page. For compare pages, the secondids of all products are provided by multiple fh_secondid parameters.
fh_secondid2	valid secondid	0..1	Specifies the secondid of a secondary item to be shown in combination with the primary item (specified using fh_secondid) on a detail page. This parameter overrides any (default) selection that would be done otherwise to determine the secondary item.
fh_view	"home", "summary", "lister", "detail", "compare", "search"	0..1	Specifies the page template if given, otherwise it will be automatically calculated based on the other query parameters. It is possible to create additional custom page templates to these for your specific requirements within the Merchandising Studio and these would have a different parameter name value.
fh_refview	previous view	0..1	The view of the page the user came from (for reporting).
fh_reftheme	previous theme	0..1	Previous promotion clicked by user (for reporting).
fh_reffacet	previous facet	0..1	Previous facet clicked by user (for reporting).
fh_refsearch	previous search term	0..1	In case of redirect, this is the search term that caused the redirect.
fh_oneslice	no value	0..1	Fredhopper appends this to facet links in case they lead to a single result and the business.xml has the setting for this redirect switched on.
fh_start_index	Integer	0..1	Start item position in lister.
fh_view_size	Integer	0..1	Number of items to show in lister.
fh_sort_by	attribute_type or $function_attribute_type	0..1	Sort items by attribute_type or function_attribute_type. Example: Sort descending by price fh_sort_by=-price. Multiple sort keys need to be separated by comma.
fh_log	0 or absent	0..1	If you do not want a request to show up in the biz.log. Use this for example for the startupcrawler or in a publish script to check if the application started. Use fh_log=0 to not log requests.
fh_facets	comma-separated list of facet IDs	0..1	Force the facets with the specified ids to be shown on top of the facet map regardless the rules set from the Merchandising Studio. If the number of facets specified is less than the max number of facets configured, the list will be filled with the next facets from the normal facet list.
fh_maxdisplaynrvalues_'facetName'	Integer	0..1	If present and equal to '-1', Fredhopper will return all possible values of the facet with name 'facetName'.
fh_context_location			If present, Fredhopper will keep facets value after selection. The facet should be configured to be "multiselect". You should then add the following parameter in your FH calls (or directly in the preview URL): fh_context_location=%PATH_OF_THE_CONTEXT%. The path of the context should correspond to the path from where you want to keep the facet values. Usually, this is the root catalog, but this could be a parent category in case you display facets only starting from this point.
fh_displayfields_mode	preview live secondid all	0..1	preview (only valid and set by default on a prepublished environment) - render preview display fields live (by default on a live environment) - render live display fields secondid - for each item render secondid field only all (only valid on a detail page) - render all display fields available in the system
fh_session_id	string		A/B testing - To request a variant of a given FHR page for a non-caching solution - View more information
fh_abtests	string		A/B testing - To request a variant of a given FHR page for a caching solution. Should follow the format test-1:variant-for-test-1;test-2:variant-for-test-2;test-3:variant-for-test-3;... - View more information
fh_cluster_id	integer	0..1	When using the Fredhopper AI Scores user segmentation module, this parameter is used to provide the user's cluster group that is returned by the front-end tracker - View more information

The fh_secondid can either be product_id values or variant_id values.

Suppressing response elements

There can be occasions when the default query response contains more information than is needed by the web application. For example, a user might be navigating to the next page of items on a lister page, so all that he/she requires is the next batch of products only. In this situation, FAS will calculate and render all components in the response (facets, campaigns, etc.) by default. The fh_suppress parameter can be used in these situations to instruct FAS to ignore certain parts of the response. This ensures that the query is processed faster and the response is smaller in size as well.

We recommend using this feature wherever possible to ensure the integration is optimised - the current list can be found in the following article: https://support.crownpeak.com/hc/en-us/articles/11135737406237-Fredhopper-Query-Language

Please find some examples below:

Parameter name	Values	Appearance	Description	Since FAS Version
fh_suppress	facets	0..1	If present, facets are not rendered.	8.2.0
fh_suppress	facets:url-params	0..1	If present, link tags of filter sections in a response will not have the <url-params/> sub-tag. It can be used if a customer generates URL parameters for facets and does not need ones provided by FAS. Using this parameter can significantly reduce the response size.	8.1.15
fh_suppress	items	0..1	If present, items are not rendered.	8.2.0
fh_suppress	items:url-params	0..1	If present items will be rendered without their link tag in the response. Using this parameter can significantly reduce the response size.	21.2.0
fh_suppress	campaigns	0..1	If present, campaigns are not rendered. Equivalent to fh_nothemes=1	8.2.0
fh_suppress	campaigns:url-params	0..1	If present all link tags of campaigns in the response will not be rendered. Using this parameter can significantly reduce the response size.	21.2.0
fh_suppress	redirect	0..1	If present, will suppress all redirects for the current query. Equivalent to fh_disable_redirect=true	8.2.0
fh_suppress	modifications:all	0..1	If present, no result modifications will be applied to a current query. Equivalent to fh_allowed_modification=	8.2.0
fh_suppress	modifications:block	0..1	If present, no blocking result modifications will be applied to a current query. Equivalent to fh_allowed_modification=REPLACING,MOVING	8.2.0
fh_suppress	modifications:move	0..1	If present, no moving result modifications will be applied to a current query. Equivalent to fh_allowed_modification=REPLACING,BLOCKING	8.2.0
fh_suppress	modifications:replace-location	0..1	If present, no location replacement result modifications will be applied to a current query. Equivalent to fh_allowed_modification=MOVING,BLOCKING	8.2.0

Examples: ...&fh_suppress=redirect,facets - FAS will not check if redirect is needed and will not render facets ...&fh_suppress=modifications:block,facets:url-params - FAS will render facets, but leave URL parameters in facet sections empty. It will also not apply any blocking result modifications.

It is recommended to use the fh_suppress parameter instead of the previous parameters fh_allowed_modification, fh_disable_redirect and fh_nothemes.

Location

A location query (or location string) is a constraint-based, textual representation of a selection of items and maps directly to a hyper-cube. As an additional filter, it may contain a search term. A location string typically contains the universe in which the hyper-cube is located and the locale of the user, which maps to an availability dimension: only items of the universe available in the user's locale are acceptable. Queries in the Fredhopper system are in the form of an X-path like notation. The query is equal to a point or shape in the FAS index.

Selection	Base-type(s)	Description
attribute=value	set,list,datetime,int,float,text	Where attribute is equal to value.
attribute<value	datetime,int,float,text	Where attribute is less than value.
attribute>value	datetime,int,float,text	Attribute is greater than or equal to value.
value1<attribute<value2	datetime,int,float,text	Where value1 <= attribute < value2.
value1>attribute>value2	datetime,int,float,text	Where value1 > attribute >= value2.
attribute={value1,value2,...}	set,list	attribute values are equal to value1 and value2
attribute<{value1,value2,...}	set,list,hierarchical	attribute may contain any of value, value2, ...
attribute>{value1,value2,...}	set	attribute contains all of value1, value2, ...
attribute>{value1;value2;...}	set,list	attribute contains at least one of value1, value2

A query can be negated (is not) by prefixing the selection with the '!' character, for example !attribute=value is used to request items that do not have the given attribute value.

Sending a search query

The method to send a query that includes a search term to be processed by FAS is very simple. The required character sequence that should be included in the query string before the required search term is: /$s=

Full syntax criterion for a search query, where ;p= and ;t= are optional parameters that can be included to have a specific search pass or profile process the search:

/$s=search_term[;p=pass_id][;t=template_profile_id]

It is very important that any non-alphanumeric characters in the search term, such as punctuation characters, control characters, UTF8 characters and delimiters, must be converted to their Unicode character values in the format: \uXXXX (where XXXX is the Unicode encoding of the required character). Some example characters include: @ ! \ " # £ $ % & ' ( ) * + , - . / : ; < = > [ ] ^ { } | ` ~

Character	Encoding
space	\u0020
!	\u0021
"	\u0022
#	\u0023
/	\u002f
@	\u0040

Example location query strings

Please some typical scenarios below with the resulting query string values. It is important to note that you should always prefix location queries with 'fh_location' in order to make them valid, e.g. fh_location=//catalog01/en_GB/colour=red.

Basic queries
Get all red products	//catalog01/en_GB/colour=red
Get all red products in the category Women (products_women)	//catalog01/en_GB/colour=red/categories<{products_women}
Get all red products in the category Women → Shirts (products_women_shirts)	//catalog01/en_GB/colour=red/categories<{products_women}/categories<{products_women_shirts}

Numerical queries
Get all which are cheaper than 50 EUR	//catalog01/en_GB/price_eur<50
Get all which are costs between 20 EUR (inclusive) and 49 EUR (inclusive)	//catalog01/en_GB/20<price_eur<50

Set selections
Get all products that are red AND green (among others)	//catalog01/en_GB/colour>{red,green}
Get all products that have no other value than red or green. This query matches on items that are either: red AND green, only red, only green or have no colour at all	//catalog01/en_GB/colour<{red,green}
Get all products that are exactly red AND green (and no other colours)	//catalog01/en_GB/colour={red;green}
Get all products that red OR green	//catalog01/en_GB/colour>{red;green}

Geo queries
Find all red products that are 50km around my current position (x=200, y=56). Fredhopper uses its attribute functions to perform geo searches. Attribute functions generate output based on one or more inputs. The following example uses the attribute function GeoFunction to launch a geo search. The Distance parameter is obligatory.	//catalog01/en_GB/colour=red/geo(200,56)<50

Search queries
Get all products that match on "ring"	//catalog01/en_GB/$s=ring
Get all products that match on "säge" (German umlaut)	//catalog01/en_GB/$s=s\u00E4ge
Get all products that match on "dvd player" (note the space)	//catalog01/en_GB/$s=dvd\u0020player
Get all products that match on "ring" and are red (after search refinement)	//catalog01/en_GB/$s=ring/colour=red
Get all womens products that match on "ring" (scoped search). Make sure to include the precise location that defines the constrain.	//catalog01/en_GB/categories<{products_women}/$s=ring
Get all products that match on "ring" using the "title" profile	//catalog01/en_GB/$s=ring;t=title
Get all products that match on "ring" with "literal" search pass	//catalog01/en_GB/$s=ring;p=literal
Get all products that match on "ring" using the "title" profile with literal search pass	//catalog01/en_GB/$s=ring;p=literal;t=title

Category queries
It is possible to show the items that are assigned or not assigned to a hierarchical attribute. A clearer wording would be show/not show the items 'under' a given category value. The query string /cat<{A} means 'give me the items that are under category A' and this will include all items that are in the child/subcategories of category A. Note: for hierarchical attributes, you can't specify "I want the items from exactly this category".
Contains A and B will give you all items that are under both A and B	/cat<{A}/cat<{B}
Contains A or B will give you all items that are under A or under B (note that the comma character , means OR)	/cat<{A,B}
Contains not A and B will give you all items that not under both A and B	/!cat<{A}/!cat<{B}
Contains not A or B will give you all items that are not under A or under B. This syntax is valid but produces the same result as the one above	/!cat<{A,B}

Item queries
Only return items x,y and z if they are cheaper than 50 EUR	//catalog01/en_GB/price_eur<50|secondid<{x,y,z}

Encoding of the query strings

If you use one of the SOAP-based Fredhopper Query Language Libraries that are available, this will automatically encode the requests that are sent to FAS in the correct format. For all other connection types, the Fredhopper requests must be correctly encoded before they are sent for processing. The required steps to achieve this are as follows:

1. Ensure that the given searchterm has been encoded with any Unicode character replacements (see the explanation above - or the Java source code on the Fredhopper Learning Center)

2. Combine this with the other filters, e.g. colour preference, to form the fh_location parameter value

3. Encode each parameter value using URL encoding

4. Join each parameter=encodedValue pair using an ampersand character (&)

For example, to search for red coloured products matching on the term 'nike shoes':

1. Encode the search term: nike\u0020shoes

2. Combine this with the location and attribute filters: fh_location=//catalog01/en_GB/$s=nike\u0020shoes/colour=red

3. URL encode the new string: fh_location%3D%2F%2Fcatalog01%2Fen_GB%2F%24​s%3Dnike%5Cu0020shoes%2Fcolour%3Dred

4. Join this with other parameters in the query: fh_location%3D%2F%2Fcatalog01%2Fen_GB%2F%24​s%3Dnike%5Cu0020shoes%2Fcolour%3Dred%26date_time%3D20200122T144530

The query response that you receive back from FAS is always UTF-8 plain encoded.