Activity Filter Syntax

The Activity Filter Syntax is used in several places in the API and allows for narrowing the list of items returned from Get Activities by Accessory Id, or to limit which generate Notifications. The filter syntax is used in conjunction with the values for the Classifiers such as Object Type, Object Location, Object Color, Object Size, Relevance Level or Activity Set. It is also used with Zones in the Notification Events.

Definition

comparator ::=
    = 
  | <> 
  | < 
  | <= 
  | > 
  | >=

value ::= string | number
value_set ::= [ value, value, ... ]

operand ::= attribute_name | value

function ::=
    attribute_exists(attribute_name)
  | attribute_not_exists(attribute_name)
  | contains(attribute_name, value)
  | contains_any(attribute_name, value_set)
  | contains_all(attribute_name, value_set)
  | size(attribute_name)
 
condition ::=
    operand comparator operand
  | attribute_name BETWEEN value AND value
  | function 
  | condition AND condition 
  | condition OR condition
  | NOT condition 
  | ( condition )

contains() Function Family

These functions are normally used when filtering Classifiers such as Object Location, Object Color, or Object Size.

The contains() function can take a string or a set as the attribute_name. If you are looking for a singular value within a set, contains() is the right function. The contains_any() and contains_all() functions can only take sets for the attribute_name.

Other Functions

attribute_exists() can be used to test if a value_set has any items in it.

attribute_not_exists() can be used to test if a value_set didn't have any items in it. Typically used with sparse Classifiers.

size() is used if you want to test the count of the contents of a set based attribute_name. It can tell if you any of the Classifiers types such as Object Types were detected. size() can't be used to test for empty attributes, attribute_exists() must be used for that.

Limits and Notes

The maximum length for the final string is 4KB when expressed in UTF-8 encoding.
When filtering old activities with the Get Activities by Accessory Id call, don't use the Zone Id as the user may have changed the Zone definition since the Activity was created. Instead use Object Location or check the lastModified value in the result from Get Zones by Accessory Id to see if the zone date is newer.

Examples

// Movement in any of the locations specified
contains_any(objectLocations,[1,3,9,128,75,82,23])

// No movement in any of the locations specified
NOT contains_any(objectLocations,[1,3,9,128,75,82,23])

// Movement in all of the locations specified
contains_all(objectLocations,[1,3,9,128,75,82,23])

// Movement in any of the locations specified but NOT in any of the other specific locations
contains_any(objectLocations,[1,3,9]) AND (NOT contains_any(objectLocations,[128]))

// Movement in any of the locations and bubble color was grey or blue
contains_any(objectLocations,[1,3,9]) AND (relevanceLevel >= 0)

// Black and Yellow objects found and bubble color was grey or blue
contains_any(objectColors,["BK","YE"]) AND (relevanceLevel >= 0)

// Black or Yellow or Red and Blue colors found and medium sized object
( contains_any(objectColors,["BK","YE"]) or contains_all(objectColors,["RD","BU"]) ) AND contains(objectSizes, "m")

// Any Object Types were found
attribute_exists(objectTypes)

// More than one Object Types were found
size(objectTypes) > 1

// No known Object Types were found or a Person was found
attribute_not_exists(objectTypes) OR contains(objectTypes,"person")

// Person and Pink object found
contains(objectTypes,"person") AND contains(objectColors,"PK")

// Only High/Blue bubbles
relevanceLevel = 1