Skip to content

Filter

The Filter object allows to build filters to narrow our queries. The basic construction of a Filter is like this:

1
2
3
4
const filter = cf.Filter('field_name')
                .operation('operation')
                .value(value)
                .label('Label') // Optional

Filters expect the name of the field to filter by (called filter path), the operation and the value, which usually takes an array of values. These can be strings if the field is an attribute or numbers if is a measurement field.

It also supports the label property which is useful when filters are applied across sources with different field names but common field labels. Refer to Interaction Manager for advanced interactions across visualizations.

Filter properties

The Filter object has several properties and we already know the main ones: path, label, operation and value. From these properties path, label and value should NEVER be accessed directly if we want to get their values. Instead, we should use the following accessors:

1
2
3
4
filter.getPath()
filter.getLabel()
filter.getValue()
filter.getOperation()

The reason is that these properties are calculated differently for example when the filter is created from a derived field.

Filter time properties

The Filter object offers two optional properties, granularity and oneTimeUnit, that are used only to present time units in a specific format.

granularity is a filter rendering property that applies only to time window filters. It informs the rendering widget to render this time window in a specific format using the specified granularity (possible values are 'SECOND', 'MINUTE', 'HOUR', 'DAY', 'WEEK', 'MONTH' and 'YEAR') oneTimeUnit is a filter rendering property that applies only to time window filters. It informs the rendering widget to render this time window using a single time unit according to the specified granularity. For example, “FEB, 2022” if the granularity is 'MONTH' and “FEB 1, 2023” if the granularity is 'DAY'. This is as opposed to rendering both the FROM and TO timestamps.

To set these properties we can use the functions granularity(g) and oneTimeUnit(o), and in the example below you can see how to use them:

1
2
3
4
5
6
7
8
9
const filter = cf.Filter('field_name')
    .operation('operation')
    .value(value)
    .label('Label')
    .granularity('MONTH')
    .oneTimeUnit(true);

const isOneTimeUnit = filter.getOneTimeUnit(); // true
const granularityValue = filter.getGranularity(); //MONTH

Filter operations

Filters support several types of operations which can be specified in different ways from the aql. If no operation property is used it will take IN by default. Let's take a look at them:

Operation Description Other symbol Shortcut
IN Filter matching values .in(value1, value2, ...)
NOT IN Exclude matching values .notin(value1, value2,...)
BETWEEN Range selection (only numbers and dates) .between(start, stop)
EQUAL Match one single value (equivalent to IN with one value) = .equal(value), .equals(value)
EQUALI Match one single value (equivalent to IN with one value) but case insensitive .equali(value)
LIKE Allows case-sensitive matching of one single value based on comparison with a pattern .like(value)
LIKEI Allows case-insensitive matching of one single value based on comparison with a pattern .likei(value)
GT Greater than the value > .gt(value)
GE Greater or equal the value >= .ge(value)
LT Lower than the value < .lt(value)
LE Lower or equal the value <= .le(value)

Let's see some examples

1
2
3
4
5
const filter = cf.Filter('event').value(['Event1', 'Event2'])
const filter1 = cf.Filter('event').in('Event1', 'Event2')
const filter2 = cf.Filter('event')
                    .operation('IN')
                    .value(['Event1', 'Event2'])

In the above example we can see three different ways to declare the same filter. The first option only applies for IN since it omits the operation, but the other two are the same for any other operation.

1
2
3
4
const date_range1 = cf.Filter('date_field').between('2008-05-21 00:00:00', '2008-06-12 00:00:00')
const date_range2= cf.Filter('price').operation('<').value(['2008-05-21 00:00:00'])
const price1 = cf.Filter('price').operation('GE').value([20])
const price2 = cf.Filter('price').le(34)

Shortcuts may take comma separated values or an array optionally.

The following example shows the use of LIKE and LIKEI operations.

1
2
3
4
5
const likeFilter = cf.Filter('venuename').operation('LIKE').value(['Paris MGM%'])
const likeFilter2 = cf.Filter('venuename').like('Paris MGM%')

const likeiFilter = cf.Filter('venuename').operation('LIKEI').value(['paRis MgM%'])
const likeiFilter = cf.Filter('venuename').likei('paRis MgM%')

Combining operations

From the table, the last four operations can be combined to create ranges with more flexibility. The operation BETWEEN is an inclusive range operation for both values and is the equivalent to use GE and LE:

1
2
const date_range1 = cf.Filter('date_field').ge('2008-05-21 00:00:00').le('2008-06-12 00:00:00')
const date_range2 = cf.Filter('date_field').operation('GE,LE').values(['2008-05-21 00:00:00', '2008-06-12 00:00:00'])
In the same fashion, we can create other exclusive or inclusive ranges:

1
2
3
4
5
// Left exclusive, right inclusive
const date_range1 = cf.Filter('date_field').gt('2008-05-21 00:00:00').le('2008-06-12 00:00:00')

// Left and right exclusive
const number1 = cf.Filter('price').gt(5).lt(10)

Server Filters

All filters set to a visualization or query by using .filters(), .filter() or .staticFilters() are server filters. This means that the visualization will query the server again to bring the new filtered data.

Client Filters

This type of filter are set with the use of .clientFilters(). Usually these filters match the same group or field used to aggregate the visualization or query. This way the visual knows how to exclude non-matching data without re-querying the server again.

Relative Filters

These filters are designed for time fields only. They don't use a fixed range of dates but a value that represents a relative time to the present, ie: Today, Yesterday, This hour...

These relative values are called presets and you can see more information about them here.

To use a relative filter add the isRelative() function and the preset as a value:

1
2
3
4
const filter = cf.Filter('saletime').value('Last 6 months').isRelative()

// Check the range used:
filter.getValue()

If the filter above is applied to a visualization, this one will always query data using a range corresponding to the last 6 months.

This type of filters is very useful when we are working with live data or data that is updated frequently.