This library provides an interface for creating filters to be passed as parameters to Analytics and GlobalAnalytics functions.
Filter types
There are five different Filter
types that are created with Filter Constructors:
NumericFilter
StringFilter
DateFilter
BooleanFilter
GeoFilter
These filters can then be passed as parameters to relevant Analytics and GlobalAnalytics functions directly or after the application of Filter Operators.
For each type of filter, if an operating condition is not specified, they are treated as key existence filters, specific to that type of tag data type.
In addition, multiple filters can be combined through the '&' operator to further constrain the Analytics queries.
Filter operators
Below is a table of the available Filter Operators:
Type | Available Operators |
---|---|
All Filter types |
equal_to not_equal_to & (logical AND operation) |
NumericFilter and DateFilter |
greater_than greater_than_or_equal less_than less_than_or_equal |
StringFilter |
contains starts_with ends_with |
GeoFilter |
within |
Import
To use this library and its functions, you must use the import line at the beginning of your Base Python code.
import Filter
Construct a NumericFilter
Filter.numeric_tag(name)
Represents a tag with numeric values.
Credit cost: 0
Parameters
- name:
str|unicode
Name of tag, including stream name (eg. "raw.score")
Return Value
NumericFilter
Example
-
import Filter # asserts 'raw.bpm' tag exists, if used in Analytics/GlobalAnalytics query, only events containing this tag would be returned Filter.numeric_tag('raw.bpm')
Exceptions
None
Construct a StringFilter
Filter.string_tag(name)
Represents a tag with string values.
Credit cost: 0
Parameters
- name:
str|unicode
Name of tag, including stream name (eg. "raw.city")
Return Value
StringFilter
Example
-
import Filter # asserts 'raw.name' tag exists, if used in Analytics/GlobalAnalytics query, only events containing this tag would be returned Filter.string_tag('raw.name')
Exceptions
None
Construct a DateFilter
Filter.date_tag(name)
Represents a tag with date values.
Credit cost: 0
Parameters
- name:
str|unicode
Name of tag, including stream name (eg. "raw.birthday")
Return Value
DateFilter
Example
-
import Filter # asserts 'raw.birthday' tag exists, if used in Analytics/GlobalAnalytics query, only events containing this tag would be returned Filter.date_tag('raw.birthday')
Exceptions
None
Construct a BooleanFilter
Filter.boolean_tag(name)
Represents a tag with a boolean value.
Credit cost: 0
Parameters
- name:
str|unicode
Name of tag, including stream name (eg. "raw.allowed_to_do_that")
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.friendly tag exists, if used in Analytics/GlobalAnalytics query, only events containing this tag would be returned Filter.boolean_tag('raw.friendly')
Exceptions
None
Construct a GeoFilter
Filter.geo_tag(name)
Represents a tag with GeoPoint values.
Credit cost: 0
Parameters
- name:
str|unicode
Name of tag, including stream name (eg. "raw.location")
Return Value
GeoFilter
Example
-
import Filter # asserts 'raw.home' tag exists, if used in Analytics/GlobalAnalytics query, only events containing this tag would be returned Filter.geo_tag('raw.home')
Exceptions
None
Assert equal to value
filter.equal_to(value)
Specifies that a tag (or boolean expression of tags) is equal to another value.
Credit cost: 0
Parameters
- filter:
NumericFilter
,StringFilter
,BooleanFilter
,DateFilter
, orGeoFilter
- value: value to match, must be same type as Filter instance. e.g.
DateTime
for DateFilter,true|false
for BooleanFilter
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.bpm' == 120
Filter.numeric_tag('raw.bpm').equal_to(120)
Exceptions
None
Assert not equal to value
filter.not_equal_to(value)
Opposite of Filter.equal_to
Credit cost: 0
Parameters
- filter:
NumericFilter
,StringFilter
,BooleanFilter
,DateFilter
, orGeoFilter
- value: value to not match, must be same type as Filter instance. e.g.
DateTime
for DateFilter,true|false
for BooleanFilter
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.name' != "Joe"
Filter.string_tag('raw.name').not_equal_to("Joe")
Exceptions
None
Combine filters
filter1 & filter2
Represents a boolean AND operation
Credit cost: 0
Parameters
- filter1:
BooleanFilter
- filter2:
BooleanFilter
Return Value
BooleanFilter
Example
-
import Filter
# asserts 'age' > 20 and 'bpm' > 80 age_filter = Filter.numeric_tag('age').greater_than(20) bpm_filter = Filter.numeric_tag('bpm').greater_than(80) comb_filter = age_filter & bpm_filter
Exceptions
None
Assert greater than value
filter.greater_than(value)
Asserts that a numeric tag is greater than the given value.
Credit cost: 0
Parameters
- filter:
NumericFilter
orDateFilter
- value:
int|float|datetime
value to be greater than
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.bpm' > 120
Filter.numeric_tag('raw.bpm').greater_than(12)
Exceptions
None
Assert greater than or equal to value
filter.greater_than_or_equal(value)
Asserts that a numeric tag is greater than or equal to the given value.
Credit cost: 0
Parameters
- filter:
NumericFilter
orDateFilter
- value:
int|float|datetime
value to be greater than or equal to
Return Value
BooleanFilter
Example
-
import Filter
from datetime import datetime, timedelta
# asserts 'reservation_data.check_out' is at or later than 4 days ago now = datetime.utcnow()
min_check_out = now - timedelta(days = 4)
Filter.date_tag("reservation_data.check_out").greater_than_or_equal(min_check_out)
Exceptions
None
Assert less than value
filter.less_than(value)
Asserts that a numeric tag is less than the given value.
Credit cost: 0
Parameters
- filter:
NumericFilter
orDateFilter
- value:
int|float|datetime
value to be less than
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.bpm' < 200
Filter.numeric_tag('raw.bpm').less_than(200)
Exceptions
None
Assert less than or equal to value
filter.less_than_or_equal(value)
Asserts that a numeric tag is less than or equal to the given value.
Credit cost: 0
Parameters
- filter:
NumericFilter
orDateFilter
- value:
int|float|datetime
value to be less than or equal to
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.bpm' <= 200
Filter.numeric_tag('raw.bpm').less_than_or_equal(200)
Exceptions
None
Assert within radius of location
filter.within(radius,location)
Asserts that a GeoPoint tag is within the radius of the given location.
Credit cost: 0
Parameters
- filter:
GeoFilter
- radius:
int|float
radius in meters - location:
str|arr
GeoPoint string of type 'latitude longitude altitude' or an array of numeric values [latitude, longitude, altitude]
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.home' within 10 meters of
"-48.8577 002.295 1"
Filter.geo_tag('raw.home').within(10,
"-48.8577 002.295 1"
)
Exceptions
- Exception
- GeoPoint improperly formatted
Assert contains value
filter.contains(value)
Asserts that a string tag contains the given value.
Credit cost: 0
Parameters
- filter:
StringFilter
- value:
str
value that should be contained within string
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.name' contains "Dr."
Filter.string_tag('raw.name').contains("Dr.")
Exceptions
None
Assert starts with value
filter.starts_with(value)
Asserts that a string tag starts with the given value.
Credit cost: 0
Parameters
- filter:
StringFilter
- value:
str
value that should be start of string
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.name' starts with "Dr."
Filter.string_tag('raw.name').starts_with("Dr.")
Exceptions
None
Assert ends with value
filter.ends_with(value)
Asserts that a string tag ends with the given value.
Credit cost: 0
Parameters
- filter:
StringFilter
- value:
str
value that should be end of string
Return Value
BooleanFilter
Example
-
import Filter # asserts 'raw.name' ends with e
Filter.string_tag('raw.name').ends_with("e")
Exceptions
None