Querying Joola is done using a simple JSON object describing what information should be retrieved/displayed. Rather than describing how to obtain the data from the different sources, we need to describe what it is that we wish to view as a result, Joola builds a query plan for you that maps the different metrics/dimensions into a single result set.

Query options

When describing a query the following options are available:

  • timeframe - timeframe for the query, can be either a shorthand timeframe or an object with:
    • start - start date for the query.
    • end - end date for the query.
  • interval - a string specifying the interval for the query.
  • dimensions - an array of string/object containing definitions for dimensions requested. You can specify the dimension name as string literal or use a JSON object with:
    • key - the dimension name as passed in the document. Nesting is supported, for example: user.username.
    • name - a display name for the dimension that can be used by visualizations.
    • datatype - date type of the dimension, currently supported: date, string and ip.
  • metrics - an array of string/object containing definitions for metrics requested. You can specify the metric name as string literal or use a JSON object with:
    • key - the metric name as passed in the document. Nesting is supported, for example: visits.count.
    • name - a display name for the metric that can be used by visualizations.
    • aggregation - aggregation type for the metric, currently supported: sum, avg, ucount, min, max.
    • prefix - string to add before the value, for example '$'.
    • suffix - string to add after the value, for example 'MB'.
    • decimals - number of decimal points to return, for example: 4 will yield 1.1234.
    • dependsOn - if this is a calculated metric, then specify here what is the base metric for the calculation.
    • filter - a filter object.
    • formula - an object containing the formula defintions:
    • dependsOn - an array of metric names/objects
    • run - a string containing the javascript function to run on the values. See calculated metrics for additional information.
    • collection - a string specifying the collection to take the metric from.
  • filter - An array of filters.
  • realtime - Specify that this is a realtime query and results are expected back from the server every 1 second.

Timeframes

Timeframes provide a shorthand for specifying the query from/to dates. The full representation of a timeframe is:

{
    start: new Date(2014, 1, 14),
    end: new Date(2014, 1, 14, 23, 59, 59, 999)
}

We took the more common timeframes and created a shorthand string for them. There are three main groups of timeframes: this, last and previous:

  • this_n_seconds - creates a timeframe with all of the current second and the previous completed n-1 seconds.
  • this_n_minutes - creates a timeframe with all of the current minute and the previous completed n-1 minutes.
  • this_n_hours - creates a timeframe with all of the current hour and the previous completed n-1 hours.
  • this_n_days - creates a timeframe with all of the current day and the previous completed n-1 days.
  • this_n_months - creates a timeframe with all of the current month and the previous completed n-1 months.
  • this_n_years - creates a timeframe with all of the current year and the previous completed n-1 years.
  • last_n_second - creates a timeframe with the start of n seconds before the most recent second and an end at the most recent second. Example: if right now it is 08:30:43.555 and we use “last_3_seconds”, this will result in a timeframe of 08:30:40 until 08:30:43.
  • last_n_minute - creates a timeframe with the start of n minutes before the most recent second and an end at the most recent second. Example: if right now it is 08:30:43 and we use “last_3_minutes”, this will result in a timeframe of 08:27:43 until 08:30:43.
  • last_n_hour- creates a timeframe with the start of n hours before the most recent second and an end at the most recent second. Example: if right now it is 08:30:43 and we use “last_3_hours”, this will result in a timeframe of 05:30:43 until 08:30:43.
  • last_n_day - creates a timeframe with the start of n days before the most recent second and an end at the most recent second. Example: if right now it is 2014-02-14 08:30:43 and we use “last_3_days”, this will result in a timeframe of 2014-02-11 08:30:43 until 201-02-14 08:30:43.
  • last_n_month - creates a timeframe with the start of n months before the most recent second and an end at the most recent second. Example: if right now it is 2014-02-14 08:30:43 and we use “last_3_months”, this will result in a timeframe of 2013-11-14 08:30:43 until 201-02-14 08:30:43.
  • last_n_years - creates a timeframe with the start of n years before the most recent second and an end at the most recent second. Example: if right now it is 2014-02-14 08:30:43 and we use “last_3_years”, this will result in a timeframe of 2011-02-14 08:30:43 until 201-02-14 08:30:43.
  • previous_n_second - creates a timeframe with the start of n seconds before the most recent complete second and an end at the most recent complete second. Example: if right now it is 08:30:43.555 and we use “previous_3_seconds”, this will result in a timeframe of 08:30:40 until 08:30:43.
  • previous_n_minute - creates a timeframe with the start of n minutes before the most recent complete minute and an end at the most recent complete minute. Example: if right now it is 08:30:43 and we use “previous_7_minutes”, this will result in a timeframe of 08:23 until 08:30.
  • previous_n_hour - creates a timeframe with the start of n hours before the most recent complete hour and an end at the most recent complete hour. Example: if right now it is 08:30:43 and we use “previous_3_hours”, this will result in a timeframe of 05:00 until 08:00.
  • previous_n_day - creates a timeframe with the start of n days before the most recent complete minute and an end at the most recent complete day. Example: if right now it is 2014-02-14 08:30:43 and we use “previous_7_days”, this will result in a timeframe of 2014-02-07 until 2014-02-14.
  • previous_n_month - creates a timeframe with the start of n months before the most recent complete month and an end at the most recent complete month. Example: if right now it is 2014-02-14 08:30:43 and we use “previous_4_months”, this will result in a timeframe of 2013-10-01 until 2014-02-01.
  • previous_n_years - creates a timeframe with the start of n years before the most recent complete year and an end at the most recent complete year. Example: if right now it is 2014-02-14 08:30:43 and we use “previous_3_years”, this will result in a timeframe of 2011-01-01 until 2014-01-01.

Synonyms

  • today - synonym for this_day.
  • yesterday - synonym for previous_1_day.
  • this_second - synonym for this_1_second.
  • this_minute - synonym for this_1_minute.
  • this_hour - synonym for this_1_hour.
  • this_day - synonym for this_1_day.
  • this_month - synonym for this_1_month.
  • this_year - synonym for this_1_year.
  • last_second - synonym for last_1_second.
  • last_minute - synonym for last_1_minute.
  • last_hour - synonym for last_1_hour.
  • last_day - synonym for last_1_day.
  • last_month - synonym for last_1_month.
  • last_year - synonym for last_1_year.
  • previous_second - synonym for previous_1_second.
  • previous_minute - synonym for previous_1_minute.
  • previous_hour - synonym for previous_1_hour.
  • previous_day - synonym for previous_1_day.
  • previous_month - synonym for previous_1_month.
  • previous_year - synonym for previous_1_year.

Intervals

Intervals are based on the document's timestamp, and the following are available: second, minute, hour, day, month and year.

Filters

Filters are used to set a query criteria. The syntax is simple and can is based on an array of the following:

  • attribute - the name of the document attribute to test against the match. For example, user.username.
  • operator - the operator to apply between the attribute and the match, here are the supported operators:
    • eq - Matches values that are equal to the value specified in match.
    • gt - Matches values that are greater than the value specified in match.
    • gte - Matches values that are equal to or greater than the value specified in match.
    • in - Matches any of the values that exist in an array specified in match.
    • lt - Matches values that are less than the value specified in match.
    • lte - Matches values that are less than or equal to the value specified in match.
    • ne - Matches all values that are not equal to the value specified in match.
    • nin - Matches values that do not exist in an array specified in match.
    • regex - Selects documents where attribute match a specified regular expression.
  • match - a string or array containing values to test attribute against using the operator.

Calculated metrics

Calculated metrics offer you the option to query existing metric(s) and based on their values, perform a calculation that is later returned as part of the results. In order to query a calculated metric you'll need to use the formula attribute:

  • dependsOn - an array of metric names or objects. Each will be passed to the run function according to the order specifying in the array.
  • run - a string containing a javascript function. The function is called with the metrics specifying in the dependsOn parameter and need to return a value which is then returned as part of the result set.