Fredhopper Query Language
The following section provides detailed background information on the Fredhopper Query Language and how the query strings should be constructed.
Last updated
Fredhopper Integration Guide
The following section provides detailed background information on the Fredhopper Query Language and how the query strings should be constructed.
Last updated
Most of the Fredhopper query string arguments are prefixed with 'fh_' and the current list can be found in the following article -
Please find some examples below:
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
fh_abtests
string
fh_cluster_id
integer
0..1
The fh_secondid can either be product_id values or variant_id values.
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.
Please find some examples below:
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.
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.
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.
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:
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: @ ! \ " # £ $ % & ' ( ) * + , - . / : ; < = > [ ] ^ { } | ` ~
space
\u0020
!
\u0021
"
\u0022
#
\u0023
/
\u002f
@
\u0040
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.
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}
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
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}
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
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
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}
Only return items x,y and z if they are cheaper than 50 EUR
//catalog01/en_GB/price_eur<50|secondid<{x,y,z}
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:
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)
Combine this with the other filters, e.g. colour preference, to form the fh_location parameter value
Encode each parameter value using URL encoding
Join each parameter=encodedValue pair using an ampersand character (&)
For example, to search for red coloured products matching on the term 'nike shoes':
Encode the search term: nike\u0020shoes
Combine this with the location and attribute filters: fh_location=//catalog01/en_GB/$s=nike\u0020shoes/colour=red
URL encode the new string: fh_location%3D%2F%2Fcatalog01%2Fen_GB%2F%24s%3Dnike%5Cu0020shoes%2Fcolour%3Dred
Join this with other parameters in the query: fh_location%3D%2F%2Fcatalog01%2Fen_GB%2F%24s%3Dnike%5Cu0020shoes%2Fcolour%3Dred%26date_time%3D20200122T144530
A/B testing - To request a variant of a given FHR page for a non-caching solution -
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;... -
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 -
We recommend using this feature wherever possible to ensure the integration is optimised - the current list can be found in the following article: