Fredhopper Query Language

This section provides you with detailed background information on the Fredhopper Query Language.

URL query string arguments

All Fredhopper query string arguments are prefixed with "fh_". In the table below, they are grouped by relevance, and a short explanation on each of them is provided.

Some times FAS response contains more information than needed. For example, a user might navigate to the next page, so everything he/she need is the next batch of items. Yet, FAS will calculate and render facets, campaigns, etc. fh_suppress parameter tells FAS to ignore certain parts of a response. It makes queries faster and responses smaller and sharper.

Currently there are following possible values:

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.

Note

It is recommended to use fh_suppress parameter instead of old arameters fh_allowed_modification, fh_disable_redirect and fh_nothemes when integrating with FAS 8.2 and onwards.

Location

A location query (or location string) is a constraint-based, textual representation of a selection of items and maps directly to a hypercube. As an additional filter it may contain a search term. A location string typically contains the universe in which the hypercube 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 index.

A query can be negated by prefixing the selection with the '!' character, for example
!attribute=value to request items that have an attribute attribute that has not the value value.

Syntax of a search query criterion

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

All special characters in the search term such as control characters, utf8 chars and delimiters must be criterion encoded: \uXXXX Where XXXX is the hexadecimal representation of the corresponding unicode code point. Delimiters are: @ !\"#$%&'()*+,-./:;<=>[]^{}|`~

See the source code of UnicodeEncoder.java in file FAS/client/java/fredhopper-query-lang-*.src.zip for how to build this encoding.

Example queries

All examples are for universe products and English locale. Note: always prefix location queries with fh_location to make them valid. For example: fh_location=//catalog01/en_US/color=red.

Using triggers as attribute value(s) (since FAS 21.4)

Attribute values can be replaced with a custom trigger url parameter. The value will be resolved the trigger parameter value supplied as part of the request. If the trigger is not supplied, the respective selection will be ignored

Example request:

http://<server>:<port>/preview?fh_location=catalog01/en_GB/attribute=[trigger_url_param;]&trigger_url_param=actual_value

Properly encoding a date criterion

As with a search query criterion, you need to encode certain utf8 characters: \uXXXX Where XXXX is the hexadecimal representation of the corresponding unicode code point. Delimiters are: @ !\"#$%&'()*+,-./:;<=>[]^{}|`~

The most important character you need to worry about is the colon ':' character, as it is used in the ISO 8601 date format, which FAS uses. Here's an example of a properly encoded date criterion:

/release_date>2021-10-08T13\u003A45\u003A00Z

You can alternatively convert the date to milliseconds since 00:00:00 UTC on 1 January 1970 and use that instead. The same example using milliseconds is

/release_date>1633700700000

See Guildeline for using filter in Fredhopper Query Language for more information about the filter operator '|'.

To exclude items based on their ID create a new attribute (e.g. hide=1 or hide=0), and extend the selection in fh_location (e.g. //catalog01/en_US/hide=0). Consider to not load items into Fredhopper that should be removed from every request.

EBNF

The location syntax is provided using EBNF

Location

location = "//", universe, "/", locale, {criterion}
universe = universe-id;
locale = language, "_", country;
language = lcletter, lcletter;
country = ucletter, ucletter;
criterion = range-separator, range | filter-separator, filter | target-separator, target;
range-separator = "/";
filter-separator = "|";
target-separator = ":";
range =	search-range | navigation-range;

Navigation step

navigation-range = [negation], [[value], operator] attribute [operator, [value]];
value = single-value | multi-value;
operator = element-operator | set-operator;
element-operator = below | equals | above
set-operator = contains | is-contained
below = "<";
equals = "=";
above = ">";
contains = "<";
is-contained = ">";
negation = "!";
attribute = attribute-id | attribute-function;
attribute-function = [ "$" ], attribute-id, "(", function-arguments, ")";
function-arguments = [ function-argument [{",", function-argument}]];
single-value = value-id | number;
multi-value = "{", single-value, {value-operator, single-value} "}";
value-operator = and-value-operator | or-value-operator;
and-value-operator = ",";
or-value-operator = ";";

Search step

search-range =	 "$s=", search-phrase, {search-predicate};
search-phrase = { unescaped-char | unicode-escaped-sequence };
unescaped-char = letter;
unicode-escaped-sequence = "\u", hex-letter, hex-letter, hex-letter, hex-letter;
search-predicate = search-profile-predicate | search-pass-predicate;
search-profile-predicate = ";t=", identifier;
search-pass-predicate = ";p=", identifier;

Relational item selection

target = special-attribute, order-operator, value [weight-operator, target-weight];
order-operator = closest-order-operator | farthest-order-operator;
closest-order-operator = "˜";
farthest-order-operator = "%";
weight-operator = "!";
target-weight = signed-float;

Hand picked item selection

filter = [negation] secondid-filter | itemid-filter;
secondid-filter = "secondid", contains, "{", item-id, {",", item-id}, "}";
itemid-filter = "itemid", contains, "{", nat-number, {",", nat-number}, "}";

Identifier and base values

item-id = { url-valid-char }
function-argument = { location-valid-char }
location-valid-char = letter | digit | location-valid-special-char;
location-valid-special-char = "!" | "#" | "$" | "*" | "+" | "-" | "." | ";" | "@" | "[" | "]" | "^" | "_" | "{" | "}" | "~";
url-valid-char = location-valid-char | "/" | ":" | "|" | "<" | ">" | "=" | "(" | ")" | ",";
universe-id = identifier
attribute-id = identifier
identifier = first-char-identifier, { nonfirst-char-identifier }
first-char-identifier = "_" | lcletter;
nonfirst-char-identifier = first-char-identifier | digit;
value-id = nonfirst-char-identifier, { nonfirst-char-identifier }
letter = lcletter | ucletter;
lcletter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" |
  "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
ucletter = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" |
  "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z";
hex-letter = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f";
number = nat-number | unsigned-float
integer = [sign], nat-number;
nat-number = digit, { digit };
float = signed-float;
signed-float = [sign], unsigned-float;
sign = "+" | "-";
unsigned-float = digit, {digit}, [".", {digit}];
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

Encoding

The Fredhopper Query Language library automatically encodes Fredhopper request in the right way.

To build manually the Fredhopper request:

1. Encode the searchterm with the criterion encoding (see sample queries above - or Java source code in reference implementation)
2. Combine it with other filters, e.g. brand selection to form the fh_location parameter value
3. Encode each parameter value using URL encoding (using UTF-8 as charset)
4. Join each parameter=encodedValue pair using &

For example to search for red products matching on "adidas shoes":

1. Encode search term: adidas\u0020shoes
2. Combine: //root/en_GB/$s=adidas\u0020shoes/color=red
3. Encode: //root/en_GB/$s=adidas\u0020shoes/color=red (which is equivalent to %2f%2froot%2fen_GB%2f$s%2dadidas%5cu0020shoes%2fcolor%3dred)
4. Join: fh_location=//root/en_GB/$s=adidas\u0020shoes/color=red&fh_view=lister (which is equivalent to fh_location=%2f%2froot%2fen_GB%2f$s%2dadidas%5cu0020shoes%2fcolor%3dred&fh_view=lister)

The Fredhopper output is alwaysUTF-8 plain encoded.

FAQ

This section provides solutions to common integration questions related to the integration of Fredhopper.

Q: How do I implement search redirects?

A: The search redirect functionality can redirect the user to a catalogue location, or to a non-Fredhopper URL, triggered by a search query. When Fredhopper executes a search re-direct, please refer to the <redirect> element to integrate the result.

<page>
 ...
 <redirect>
 <redirect-host>server-name</redirect-host>
 <redirect-port>port-number</redirect-port>
 <redirect-url>http://www.example.com</redirect-url>
 </redirect>
 ...
 </page>

Note that the <redirect> element is only returned for queries using the SOAP web service. For REST requests the response will use HTTP status code the request must include the 'User-Agent' HTTP request header field with exactly the value 'XML only client', otherwise the REST response will be a temporary redirect (HTTP response status code 302, redirect URL in the Location response header field.)

Q: How do I remove a search from the breadcrumb?

A: In order to remove a search from the breadcrumb, remove the search parameter from the location string.