We use cookies or similar technologies to personalize your online experience and tailor marketing to you. Many of our product features require cookies to function properly. Your use of this site and online product constitutes your consent to these personalization technologies. Read our Privacy Policy to find out more.

X

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.

Note: Specify columns using their key_names, even if they have an alias defined. A Derived Column, however, must be specified by its alias (like it is displayed in the Honeycomb UI.)

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:

Filter Operators

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