Queries

Wiki ▸ API Reference ▸ Evaluator ▸ Queries

The evaluator supports two different types of queries. One for events and one for metrics.

Metric Expressions

The simplest type of metric expression is reduce(type), where reduce is a reduce function, and type is an event type. For example, you might count "request" events:

sum(request)

In this case, the subexpression request matches all request events. You can filter those events to only requests of interest, say only requests to "/account" from Chrome browsers:

sum(request.eq(path, "/account").re(user_agent, "^Chrome/"))

The eq filter requires an exact match, while the re filter applies a regular expression.

A reduce function, such as sum, takes an array of values as input. To count events, each event is given the default value of 1 and then passed to sum. You can specify the value to sum for each event explicitly:

sum(request(1))

More commonly, this is used to access a particular value from the event's data, and use that to reduce. For example, you can sum the duration for all requests for a [load](http://en.wikipedia.org/wiki/Load_(computing\))-type metric:

sum(request(duration))

This can be combined with filters, so as to sum the duration for only requests whose path is "/account":

sum(request(duration).eq(path, "/account"))

More elaborate expressions are possible as well. Note that you can combine constants with data accessors:

sum(foo(i * j - 2)) // do some arithmetic on foo.i, foo.j
sum(foo(i[0])) // access an array's first element

You can even construct compound metrics using simple arithmetic. For example, to compute the average duration for requests:

sum(request(duration)) / sum(request)

Cube also supports simple constant metrics, such as 42; these can be combined with other metrics. For example, sum(foo(.1)) and sum(foo) / 10 are equivalent.

The type is an event type, as specified in the type field in events emitted to collectors. For example, it might be "request" or "random".

The value is optional; if not specified, the value derived from each event is 1. If a value is specified, it is either a field or an arithmetic expression that may include fields and numbers. This value is then fed to the reduces. For example, if request events have a duration field, you can feed that to a reduce as request(duration). Likewise, you can use simple arithmetic operators such as payment(cents / 100). We plan on adding support for conditional expressions and simple mathematical transforms (e.g., log, sqrt, abs, exp).

A field can be a simple identifier such as duration or duration_ms. You can also refer to nested fields such as foo.bar.baz; likewise, you can reference array elements such as location[0]. See the MongoDB documentation for more examples of referencing fields in query filters; Cube’s syntax is identical.

The available reduce functions are:

• sum
• min
• max
• median
• distinct

The available filter functions are:

• eq - equal.
• lt - less than.
• le - less than or equal to.
• gt - greater than.
• ge - greater than or equal to.
• ne - not equal to.
• re - regular expression.
• in - one of an array of values (e.g., in(foo, [1, 2, 3])).

Multiple filters can be chained together, such as sum(request.ge(duration, 250).lt(duration, 500)).

If a filter is tested against an array, the filter will return true (i.e., match the event) if any element in the array passes the filter. Filters are tested against literal values, such as strings, numbers and booleans. Cube may allow testing of derived values in the future (arithmetic expressions on data fields, similar to how the event’s value is derived).

The full query grammar is in metric-expression.peg.

Event Expressions

Event expressions are similar to metric expressions, but used for querying events rather than computing metrics. See the evaluator's event/get endpoint, for example.

The general form of an event query is: type(value1, value2…).filter(field, literal).

The values (value1, value2, etc.) are optional; if you don't specify any values, then only the event time is returned. For example, the expression request will match all requests, and only return the "time" property.