Query Specification

Honeycomb supports defining queries via JSON for use in Query Template Links, the Boards API, and the Triggers API.

Fields on a Query Specification

All fields are optional, but a query without any calculations defined will default to a COUNT.

• breakdowns: a list of strings describing the columns by which to break events down into groups
• calculations: a list of objects describing the calculations to return as a time series and summary table. Each calculation consists of an op and a column (except for COUNT, which needs no column). If no calculations are provided, COUNT is applied. See below for a list of valid ops.
• filters: a list of objects describing the filters with which to restrict the considered events. Each filter consists of a column, op, and (sometimes) value. See below for a list of valid ops.
• filter_combination: either "AND" or "OR". If multiple filters are specified, filter_combination determines how they are applied; set to "OR" to match ANY filter in the filter list. Defaults to "AND".
• granularity: an integer describing the time resolution of the query’s graph, in seconds. Valid values are the query’s time range /10 at maximum, and /1000 at minimum.
• orders: a list of objects describing the terms on which to order the query results. Each term must appear in either the breakdowns field or the calculations field.
• limit: an integer describing the maximum number of query results.
• time_range: an integer describing the time range of query in seconds, for relative-time queries. Cannot be combined with both start_time and end_time (See caveat below.) Defaults to two hours.
• start_time: an integer describing the UNIX timestamp of the absolute start time of the query.
• end_time: an integer describing the UNIX timestamp of the absolute end time of the query.

A caveat on time

To specify an absolute time range, use start_time and end_time (both UNIX timestamps) to describe the desired range:

{
    "start_time": 1525125600,
    "end_time": 1525132800
}

start_time or end_time can also be used in combination with time_range to specify a fixed time plus a range. (Specifying values for all three, however, will result in an error.)

The following describes “the one-hour period leading up to the absolute time 2018-05-01 00:00 UTC”:

{
    "end_time": 1525132800,
    "time_range": 3600
}

Without a start_time or end_time, a single time_range argument will default to an end_time of “now.” The following describes “the last hour” relative to the time of invocation:

{
    "time_range": 3600
}

Examples

This query specification calculates the top 10 (by volume, or COUNT) unique user_agents for the hour leading up to the absolute time 2018-01-01 00:00 UTC:

{
    "breakdowns": [
        "user_agent"
    ],
    "calculations": [
        {"op": "COUNT"}
    ],
    "orders": [
        {"op": "COUNT", "order": "descending"}
    ],
    "limit": 10,
    "time_range": 3600,
    "end_time": 1514768400
}

This query specification calculates the AVG(content_length) of events from the last hour matching kafka_partition = 3 or kafka_partition = 6:

{
    "calculations": [
        {"column": "content_length", "op": "AVG"}
    ],
    "filters": [
        {"column": "kafka_partition", "op": "=", "value": 3},
        {"column": "kafka_partition", "op": "=", "value": 6}
    ],
    "filter_combination": "OR",
    "time_range": 3600
}

This query specification matches events with duration_ms > 500 and service_name != "fraud", then calculates a HEATMAP(match_quality) (where the graph spans the last 3 hours, drawn at 15-minute intervals):

{
    "calculations": [
        {"column": "match_quality", "op": "HEATMAP"}
    ],
    "filters": [
        {"column": "duration_ms", "op": ">", "value": 500},
        {"column": "service_name", "op": "!=", "value": "fraud"}
    ],
    "granularity": 900,
    "time_range": 10800
}

This query specification describes an absolute-time query which matches events with result = 200, then calculates the AVG(duration_ms) and P99(duration_ms) broken down into unique (user_id, build_id) pairs. It then returns the first 100 results, ordered first by P99(duration_ms) values, then user_id:

{
    "breakdowns": [
        "user_id",
        "build_id"
    ],
    "calculations": [
        {"column": "duration_ms", "op": "AVG"},
        {"column": "duration_ms", "op": "P99"}
    ],
    "filters": [
        {"column": "result", "op": "=", "value": 200}
    ],
    "orders": [
        {"column": "duration_ms", "op": "P99", "order": "descending"},
        {"column": "user_id"}
    ],
    "limit": 100,
    "start_time": 1515542451,
    "end_time": 1515546051
}

Calculation Operators

Calculation operators are consistent between the API and the UI. These are the available calculation "op" values:

• COUNT (does not expect an accompanying "column" value)
• SUM
• AVG
• COUNT_DISTINCT
• MAX
• MIN
• P001
• P01
• P05
• P10
• P25
• P50
• P75
• P90
• P95
• P99
• P999
• HEATMAP

Filter Operators

Filter operators are consistent between the API and the UI. These are the available filter "op" values:

• =
• !=
• >
• >=
• <
• <=
• starts-with
• does-not-start-with
• exists
• does-not-exist
• contains
• does-not-contain