Working with filters¶

A filter is a logical expression used in many Voyado Elevate 3 functions to restrict the set of products that are to be operated on. Filters can go from easy, such as to only include a product of a certain color or items that are in stock, to more complex expressions with multiple attributes for products and categories at the same time. Filters are generally set up during the configuration of panels. Product and category attributes must be configured to be used as filter attributes to work with filter arguments. Configuration is done in the Voyado Elevate manager.

If no filter (or an empty filter) is provided in an argument, the entire data set from the query will be used. This is generally not recommended since a data set may contain products that are out of stock or for future release and should not be publicly displayed.

The JavaScript libraries for both Web API v1 and Web API v2 includes a utility for creating filter strings. It is recommended to use the Filter builder utility when creating filters for panel queries.

Filter attributes¶

Before a product or category attribute can be used with a filter it must be defined as a filter attribute. Product attributes have more filter attribute properties than category attributes.

Filter basics¶

A single term is the most basic filter possible including one filter attribute and one value. The format is filter attribute:'value'. The value is enclosed in single quotes and there is no space between the filter attribute and the value.

Single quotes should always be used to enclose values, regardless of the data type of the filter attribute. If a value includes single quotes or a backslashes, they can be escaped with a preceding backslash, \' and \\.

The following example will return products that have the value green in the filter attribute color.

color:'green'

How the value green will be interpreted here is dependent on filter attribute refinement which is set up during configuration. The default value is (no refinement). This will only match data where the exact value is present. A product with the value blue-green would not be matched in this case.

If we would like to include products with the value blue-green in the filter, the Text (word stems) refinement can be used. This will include results where the value green appear somewhere in the data attribute, and not necessarily in all lowercase.

A filter value can include multiple words, as the following example.

author:'Samuel Taylor Coleridge'

The refinement Text (words) allows for filtering on multiple words. Here the value Samuel Taylor Coleridge will match products where all the words appear in the author attribute. The words are not required to be in the exact order given, but products where they are in that order will be given a higher relevance by Elevate.

For more information about refinement configuration options and how they work, see Refinements.

Truncation¶

A truncated filtering can be used to match words that begin in a certain way. This is noted by an asterisk, *, after the filter attribute.

The following example show a filter attribute ,text, that is a string where the value should begin with app. This will filter all products where the attribute value begins with app.

text*:'app'

Range terms¶

Numeric ranges and times can be filtered with brackets. This is useful for sizes, prices, release dates, and similar ranged attribute values. A square bracket indicate a border value that will be included. A round bracket indicated a border value that will be excluded.

The following examples show the ranges of the attribute size as values between 92 and 98, from and including 92 up to and excluding 98, and from and excluding 92 up to and including 98.

size:['92','98']
size:['92','98')
size:('92','98']

The following example will filter out all products created between 2018-01-01 and 2020-12-01 using the created attribute. The created attribute is an ISO 8601 time point.

created:['2018-01-01T00:00:00Z','2020-12-01T23:59:59Z']

Whether a value is in a certain range depend on the data type of the filter attribute and its normalisation rules.

Logical filter expressions¶

A logical filter expression enables matching of several attribute filter terms using the operators AND, OR, and NOT. The operators must be typed in uppercase.

The AND operator combines terms where all values must be matched to be included in the data set. The following example will return all products where the value of the attribute color is green and the value of the attribute item_type is pants.

color:'green' AND item_type:'pants'

The OR operator matches either one or all of the terms. The following example will return all products where the value of the attribute item_type is either pants or shorts or both.

item_type:'pants' OR item_type:'shorts'

The NOT operator excludes matches from the data set. The following example will return all products except those where the value of the attribute item_type is shorts.

NOT item_type:'shorts'

Expressions can include multiple operators and terms that can be used together. To clarify how far each operator goes, round brackets are used. This enables the creation of long and detailed filter expressions. The following example will return all products where the value of the attribute color is either green or blue, the value of the attribute item_type is pants, but excluding products where the value of the attribute price is between 0 and 100.

(color:'green' OR color:'blue') AND item_type:'pants' AND NOT price:['0','100']

Filter variables¶

A filter can be expressed with variables. The format of a variable is ${value}. A variable can change the name of the filter parameter based on the value, set a default value for the filter, or both. The value of a variable will substitute a part of a filter expression at the time of execution.

Variables can be used as placeholders for complete filter expressions or for values in a filter expression. Variables can also be combined with other variables or filter terms with logical expressions to split the filter in more parts.

It is recommended to not overuse filter variables as this may lead to overly complex and ambiguous filters.

Using filter variables as placeholders for complete filter expressions¶

The following example will change the name of the filter parameter from filter to a.

${a}

The following example will split the filter parameter into two parts named a and b that each can accept arguments.

${a} AND ${b}

The following example will set the default value of the filter parameter to UNIVERSE without changing the name of the parameter.

${filter=UNIVERSE}

The following example will set the default value of the filter parameter to the filter term color:'green' without changing the name of the parameter.

${filter=color:'green'}

The following example will set the default value of the filter parameter to the filter term color:'green' and changing the name of the parameter to a.

${a=color:'green'}

Using filter variables as placeholders for values in filter expressions¶

A variable for a value can be created. This allows a request to only specify the actual value, without having to include the filter attribute name.

The following example will create a variable c for the color attribute value.

color:'${c}'

A variable for a value with a default value added can be created. This allows a request to only specify the actual value, without having to include the filter attribute name. If no value is included in the filter, the default value will be used.

The following example will create a variable c for the color attribute value with a default value set to green.

color:'${c=green}'

Multiple attribute filter terms¶

Instead of using logical OR expressions with different attributes filtering on the same value, multiple filter attributes can be used together with a single value. The following example will return all products where the value Coleridge is found in at least one of the three specified filter attributes title, author, and translator.

title,author,translator:'Coleridge'

Multiple filter attributes may also be combined with values that has multiple words. This term will produce a match if every word in it is a match in at least one of the filter attributes. If a match for each word is found in the same attribute it will be given a higher relevance by Elevate.

The following example will return products where all the words in the value Stephen King Shining appear in the author or title attributes.

title,author:'Stephen King Shining'

Category filters¶

Products with specific category attributes can be filtered using the typed format available for search attributes. The following example will match all products where the value Books is found in at least of its categories' attribute display_names.

category[display_name]:'Books'

Using the logic for multiple attribute filter the category filter can be extended to more filter attributes. The following examples will return products if the value Books is found in at least one of the product attributes title and description, or in the category attribute display_name.

product[title,description],category[display_name]:'Books'

Refinements¶

How the filter values will be interpreted is based on how it is refined. Refinements can be set for filter attributes to enable normalisation of product attributes before filtering.

The following refinement settings are available:

• (no refinement) - No normalisation is performed
• Case insensitive - Normalisation to lower case
• Model designation (e.g. MB12a) - Removes all characters that are neither letters or digits, and splits the text between letter and digits using the regular expression (([^\d]+)|([\d\-\.\,]+))
• Text (words) - Text is split according to the tokenisation method. Not recommended for attributes that are planned to be used in a Facets panel.
• Text (word stems) - Text is split according to the tokenisation method followed by stemming using snowball stemming.

Tokenisation¶

The tokenisation method is used with text in the product attributes. The text is split into words with special rules for:

• Words combining letters and digits such as model designations, e.g. iPhone 8 256GB
• Words combined with hyphens, e.g. blue-green
• Words with camel case, e.g. MasterCard

The resulting set of words are normalised by making the text lower case and removing the following special characters:

`-=[];'\,./·~!@$%^&*()_+{}"|><?§´¨½¼¾¤£€©®’

Snowball stemming¶

Stemming is a process to produce the stem of a word. An extended version of the Snowball stemming algorithm is used on the set of words. This enables Elevate to match queries to conjugations and inflections of the words in the set.

Attribute types¶

The attribute type defines what type of data the attribute consists of. The setting is used to determine what values are accepted for that attribute, which values are considered equal, and how values are ordered.