Queries

Wiki ▸ API Reference ▸ Queries

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

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.

If a filter is tested against an array, the filter will return true (include 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 compound values in the future (arithmetic expressions on data fields, similar to how the event’s value is derived); note, however, that these filters would not be indexable. Multiple filters can be chained together, such as sum(request.ge(duration, 250).lt(duration, 500)).

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