Skip to content

Working with Filters

A filter is a logical expression used in many eSales 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 colour 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.

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 property Description
Name The name of the filter attribute.
Required property
Include Subcategories Only available for product attributes where Category reference is configured as Yes. Can be either Yes or No. If set to Yes, filter expressions with this attribute will include products in sub-categories of the matching category reference. If set to No, filter expressions with this attribute will only include products directly linked to the matching category reference. Defaults to Yes.
Type The type of data the attribute consists of. Used to determine what values are accepted for that attribute, which values are considered equal, and how values are ordered. Can be either boolean, byte, double, float, int, long, short, string, time point, or xml. Defaults to string.
Required property
Refinement Set how the filter values will be interpreted. Used for filter attributes to enable normalisation of product and category attributes before filtering. Can be either (no refinement), Case insensitive, Model designation (e.g. MB12a), Text (words), or Text (word stems). Defaults to (no refinement). For more information see Refinements.
Required property
Used in Facets Set if the filter attribute can be used as a facet. Can be either No, Values, or Range. Defaults to No.
Values Setting of Used in Facets. The actual value of the facet, including a product count, is used. Requires the filter Type property to be string. The recommended refinement to use with Values is Case insensitive.
Range Setting of Used in Facets. A numeric range result with a minimum and maximum value will be used. Requires the filter Type property to be numeric, e.g. byte, double, float, int, long, or short. The recommended refinement to use with Range is (no refinement).
Sort by Setting of Values. The sort order of facet values. Can be relevance, count, value, and selected. Defaults to relevance if not configured.
Number of values Setting of Values. The number of facet values to return. Must be larger than 0.
Include zeros Setting of Values. Include or exclude facet values that returns a product count of 0. Selecting a facet can cause another facet to return a product count of 0. Set Include zeros to true to include these facet values in the result. This setting should typically only be false when Sort by is set to value and a large number of facet values are returned. Defaults to false.
Keep order Setting of Values. Keep the sort order between facet values or let other facets change the sort order. The sort order of facet values can change depending on which values that are selected in other facets. Set Keep order to true in keep the facet sort order regardless of selected values in other facets. This setting should typically only be false when a large number of facet values are returned for specific product selection and relevant facets must be on top of the list. Defaults to false.

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 eSales.

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

Truncation

Performance risk

Usage of truncated filtering may noticeably affect performance of Apptus eSales.

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 can be filtered with brackets. This is useful for sizes, prices, 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']

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 eSales.

Possibility of unexpected results

Using multiple filter attributes with multiple word values may produce unexpected results. Refrain from using this filtering approach unless a very specific need for this construction exists. Do not use if the attribute filter refinement differs between attributes.

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

East asian languages

East asian languages requires special rules to split text. The following locales are supported in eSales:

th_TH, zh_CN, zh_HK, zh_TW, ja_JP, ko_KR, en_HK, en_CN, en_TW, en_KR, en_JP

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 eSales to match queries to conjugations and inflections of the words in the set.

Stemming availability

Stemming of data and queries is available for locales with the following language components:

da, de, en, es, fi, fr, it, nl, no, pt, ru, sv

×