Queries

Wiki ▸ API Reference ▸ Evaluator ▸ Queries

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

Metric Expressions

The general form of a metric query is: reduce(type(value).filter(field, literal)).

You can also construct compound metrics using simple arithmetic. For example, to sum(foo) + sum(bar) counts both "foo" and "bar" events. 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.