We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

Query Specification

Honeycomb supports defining queries via JSON for use in Query Template Links, the Query API, 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.

Specify columns using their key_names, even if they have an alias defined. A Derived Column, however, must be specified by its alias as 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 fields, 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: