Analytics Library

This library includes functions that provide access to historical events. By default, events are queried for the API Basic User that triggered the workflow, but some functions provide an optional "user" parameter which can be used to query events from any user.

 

Import

To use this library and its functions, you must use the import line at the beginning of your Base Python code.

import Analytics

 

Get events from stream

Analytics.events(stream_namefilters=None, date_range=None, limit=1000, sort=None, user=None)

Returns the events in the specified stream, subject to filters, date_range, limit, and sort.

Credit cost: 1

Parameters

  • stream_namestr name of stream from which to retrieve data
  • filtersFilter to limit events by tag (Filter Library)
  • date_rangeDateRange to query events between specific dates (DateRange Library)
  • limitint maximum number of events to return
  • sortlist|tuple pair of strings defining one tag to sort by and sort order ('ASC' or 'DESC')
    • Example 1: ['observed_at', 'DESC']
    • Example 2: ('age', 'ASC')
  • userstr name of user from which to retrieve data. If not specified, default is the user that triggered the function.

Return Value

list dictionaries containing each event's user, observed_at time, stream_idevent_data, and event_id.

 

Example

  • Sample Code:

    import Analytics
    
    events = Analytics.events('raw', limit=1, sort=['observed_at', 'ASC'])
  • Return Value:
    [
    {
        "observed_at": "2015-04-11T21:36:53.832111+00:00",
        "stream_id": 4041905582898064089,
        "event_id": 4123154489749871,
    "user": "user1", "event_data": { "action": "Help Request", "sensor_id": "Kiosk_3", "type": "Kiosk" } } ]

Exceptions

Exception

  • Any Analytics error, such as invalid tags, streams, etc.

Get last value for tags

Analytics.last_values(tag_names = None, user=None)

Returns the last value and observed_at time for each of the tags specified in tag_names. If tag_names is not specified, then it will return for all tags for this user.

Credit cost: 1

Parameters

  • tag_nameslist, optional parameter containing the tags to get the last value in format "<stream>.<tag>", ie "raw.test". Tags that do not exist will be ignored. If this is not specified, all tags are returned.
  • userstr name of user from which to retrieve data. If not specified, default is the user that triggered the function.

Return Value

list dictionaries with the observed_at time and the tag with its value.

Example

  • Sample Code:

    import Analytics
    
    last_values = Analytics.last_values(tag_names = ['raw.test','raw.test2'], user=None)
  • Return Value:
    [{'observed_at': <time>, 'raw.test': <value>}, {'observed_at': <time>, 'raw.test2': <value>}]

Exceptions

Exception

  • Any Analytics error, such as invalid tags, streams, etc.

Get last n values for tag

Analytics.last_n_values(tag_namenfilters=None, date_range=None, user=None)

Returns up to the last n values of tag tag_name.

NOTE: When using this query in debug mode, values + timestamps from debug events will be included.

Credit cost: 1

Parameters

  • tag_namestr tag name, including stream name (eg. "raw.score")
  • nint number of values to return
    • n = 1 will have much faster performance than n > 1, so try to use n = 1 when possible. n = 1 looks up the value from a specific last values table while any other limit extracts the values from the entire events table.
  • filtersFilter if provided, will apply to data before finding last n values (Filter Library)
  • date_rangeDateRange if provided, will only return the last n values between the dates (DateRange Library)
  • userstr name of user from which to retrieve data. If not specified, default is the user that triggered the function.

Return Value

 list List of objects, sorted by observed_at field (most recent first) containing the tag and value.

Example

  • Sample Code:

    import Analytics
    
    last_n_values = Analytics.last_n_values('raw.my_tag', 4, user='test_user')
  • Return Value:
    [
       {
            "raw.my_tag": 20
        }, 
        {
            "raw.my_tag": 40
        }, 
        {
            "raw.my_tag": 40
        }, 
        {
            "raw.my_tag": 60
        }
    ]

Exceptions

Exception

  • Any Analytics error, such as invalid tags, streams, etc.

Bucketed functions

The bucketed functions (Analytics.bin_by...) produce statistics where dates are grouped into "buckets". Buckets are automatically selected depending on the DateRange size:

  • Less than a day: minute buckets
  • 1 day to 2 months: hour buckets
  • 2 months to 1 year: day buckets
  • 1 year to 10 years: week buckets
  • 10+ years: month buckets

Bin by time

Analytics.bin_by_time(tag_namedate_rangefilters=None)

Returns statistics for the current user for tag_name data. Tag name data is from the period specified by date_range and is bucketed based on the date_range window.

Credit cost: 1

Parameters

  • tag_namestr tag name, including stream name (eg. "raw.score")
  • date_rangeDateRange to limit statistics by date (DateRange Library)
  • filtersFilter to limit statistics by value (Filter Library)

Return Value

 list List of dicts containing the observed_at timestamp for the bucket as well as the average, min, max, and count for that bucket.

Example

  • Sample Code:

    import Analytics
    import DateRange
    
    week = DateRange.this_week()
    bin_by_time = Analytics.bin_by_time('raw.test', week)
  • Return Value:
    [
        {
            "observed_at": "2015-04-11T21:36:53.832111+00:00",
            "avg": 123,
            "min": 123,
            "max": 123,
            "count": 123
        },
        …
    ]

Exceptions

Exception

  • Any Analytics error, such as invalid tags, streams, etc.


Bin by value

Analytics.bin_by_value(tag_namedate_range)

Returns the distribution of all distinct values of a particular tag for all events for the current user in the specified time period.

For each distinct value, the number of occurrences, its percentage of the whole, and its rank are returned. Note that ranks can occur multiple times in the case of ties.

Credit cost: 1

Parameters

  • tag_namestr tag name, including stream name (eg. "raw.score")
  • date_rangeDateRange to limit the query(DateRange Library)

Return Value

 list List of dicts, one for each distinct value, containing the number of occurrences, its percentage of the whole, and its rank

Example

  • Sample Code:

    import Analytics
    import DateRange
    
    week = DateRange.this_week()
    bin_by_value = Analytics.bin_by_value('raw.test', week)
  • Example:
    [
        {
            "count": 30,
            "percent": 90.9090909090909,
            "rank": 1,
            "value": 5
        },
        ...
    ]

Exceptions

Exception

  • Any Analytics error, such as invalid tags, streams, etc.


Bin by time and value

Analytics.bin_by_time_and_value(tag_namedate_rangegroup_tag_nameperiodfilters=None)

Returns statistics for the current user for tag_name data filtered by filters, over the period specified by date_range, bucketed into a number of buckets based on the date_range window size. Each bucket has statistics for data in that bucket grouped by group_tag_name.

Credit cost: 1

Parameters

  • tag_namestr tag name, including stream name (eg. "raw.score")
  • date_rangeDateRange(DateRange Library)
  • group_tag_namestr tag name of tag to group by
  • periodstr bucketing window (i.e. "millisecond", "second", "minute", "hour", "day",...)
  • filtersFilter(Filter Library)

Return Value

 list List of dicts, one for each time bucket + value group combination, containing the observed_at timestamp and group number for the bucket as well as the average, min, max, and count for that bucket.

Example

  • Sample Code:

    import Analytics
    import DateRange
    
    week = DateRange.this_week()
    bin_by_time_and_value = Analytics.bin_by_time_and_value('raw.email', week, 'raw.test', 'hour', filters=None)
  • Return Value:
    [
        {
            "observed_at": "2015-04-11T21:35:53.832111+00:00",
            "group": 0,
            "avg": 123,
            "min": 123,
            "max": 123,
            "count": 123
        },
        {
            "observed_at": "2015-04-11T21:36:53.832111+00:00",
            "group": 1,
            "avg": 123,
            "min": 123,
            "max": 123,
            "count": 123
        },
        …
    ]

    Exceptions

    Exception

    • Any Analytics error, such as invalid tags, streams, etc.