AFS filter expressions

Table of Contents

• Introduction
• Simple filter expressions
  • Filter identifier
  • Filter operators
  • Filter value
• Advanced filter expressions
  • Combine simple filter expressions
  • Group filter expressions
• Special notes
  • Date format
  • Example of filter builder

Introduction

This page introduces filter expressions. They are usefull to define AFS search engine queries.

Simple filter expressions

To filter on specific facet value, one must define following elements:

• facet identifier to use as filter,
• operator used to compare facet value of each document/product to the specified one,
• and, finally, facet value to be compared with the one defined in each document/product.

These elements must be defined in this order and none can be omitted.

Filter identifier

Filter identifier is created using the helper function filter(). It is also possible to create it using other method which is detailled later (see Combine simple filter expressions).

For example, you can define a filter on the categorie identified by MATERIAL as following:

filter('MATERIAL') 

Filter operators

Operators must be used on filter identifiers. One operator, and only one, can be applied to one defined filter identifier.

Operators define the way provided facet values are compared with values defined by each document/product.

Standard operators are available. Here is the list of all available operators:

• equal: equal to comparison,
• not_equal: not equal to comparison,
• less: less than comparison,
• less_equal: less than or equal to comparison,
• greater: greater than comparison,
• greater_equal: greater than or equal to comparison.

Here are examples for some of the operators:

filter('MATERIAL')->equal 

filter('PRICE')->less_equal 

Filter value

Values must be defined on filter operators. One value, and only one, can be applied to one filter operator.

Allowed value types are:

• string: it may be a string value surrounded by double quotes (") or a string representation of an integer, float, boolean or date value,
• integer,
• float,
• boolean.

Note

Date values must be defined as string value with appropriate format. See Date format for more details.

Here are examples of AFS search engine filter definitions along with their corresponding expressions:

• MATERIAL="copper"

  filter('MATERIAL')->equal->('"copper"'); 

• PRICE=42.666

  filter('PRICE')->less_equal(42.666); 

Advanced filter expressions

Filter expressions, like the ones defined earlier (ID->operator->value), can be combined or grouped in order to build complex filter expressions.

Combine simple filter expressions

Combination should be defined on simple filter expressions or groups (for details on groups, see below Group filter expressions).

Simple filter expressions can be combined in order to make a new filter expression. Two combination types are available:

• and: Filter expressions on both sides of the and operator must be verified for a document/product to make it appears in AFS search engine reply.
• or: At least one filter expression on whichever side of the or operator must be verified for a document/product to make it appears in AFS search engine reply.

This is really usefull when you want to filter on multiple values for specific facet. This is also true when you want to build intervals. Here are examples of such conditions:

• MATERIAL="copper" or MATERIAL="gold"

  filter('MATERIAL')->equal->('"copper"')->or->filter('MATERIAL')->equal->value('"gold"') 

• PRICE<=42.666 or PRICE>12.3

  filter('PRICE')->less_equal->(42.666)->or->filter('PRICE')->greater->value(12.3) 

Group filter expressions

Grouping filter expressions defines priority for combined expressions.

Group expression is created with group() function. Usage example follows:

• (MATERIAL="copper" and PRICE<42.666) or (MATERIAL="gold" and PRICE<=123.456)

  group(filter('MATERIAL')->equal->('"copper"')->and->filter('PRICE')->less_equal->(42.666))->or->group(filter('MATERIAL')->equal->value('"gold"')->and->filter('PRICE')->less_equal->(123.456)); 

• MATERIAL="platinium" or (MATERIAL="gold" and PRICE>345)

  filter(MATERIAL)->equal->value('"platinium"')->or->group(filter('MATERIAL')->equal->value('"gold"')->and->filter('PRICE')->cwgreaterless_equal->(345)); 

Special notes

Date format

Date value should match one of the following formats:

• yyyy-MM-dd HH:mm
• yyyy-MM-dd HH
• yyyy-MM-dd
• yyyy-MM
• yyyy

with:

• yyyy: represents years,
• MM: represents months (with leading 0 when necessary),
• dd: represents days (with leading 0 when necessary),
• HH: represents hours (with leading 0 when necessary),
• mm: represents minutes (with leading 0 when necessary),

For more details on date format and their usage, please refer to AFS search engine documentation.

Example of filter builder

It can happen that one wants to create several filters of the same type. In such case, it may be tedious to write appropriate filter expressions for each filter. So you are encouraged to make your own function to create appropriate filter expressions.

For example, let's suppose you often want to combine multiple values for specific facet identifier. List of facet values can be transfered as array to your specific function. Here is an example of such function:

function myExpressionBuilder($id, array $values)
{
    if (empty($values))
        return null;

    $value = array_shift($values);
    $result = filter($id)->equal->value($value);
    while (! empty($values))
        $result = $result->or->filter($id)->equal->value(array_shift($values));

    return $result;
}

Previous function definition will help you build following filter expressions:

• MATERIAL="copper"

  myExpressionBuilder('MATERIAL', array('"copper"')); 

• MATERIAL="copper" or MATERIAL="silver" or MATERIAL="gold"

  myExpressionBuilder('MATERIAL', array('"copper"', '"silver"', '"gold"'));