Skip to main content
We support defining queries via JSON. You can use defined queries in Honeycomb with:
To convert query JSON into a sharable query URL, refer to Query Template Links documentation.

​
Fields on a Query Specification

All fields are optional, but a query without any calculations values will have COUNT applied automatically.
  • 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 or CONCURRENCY, which need 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.
  • havings: a list of objects describing filters with which to restrict returned groups. Each having consists of a calculate_op (the same set used for op in calculations, but excluding HEATMAP), a column (except for COUNT, which needs no column), an op (=, >, >=, <, <=), and a value (currently assumed to be numeric). Each column/calculate_op pair must appear in the calculations field. There can be multiple havings for the same column/calculate_op pair.
  • 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.
  • calculated_fields: a list of objects defining the calculated fields that are computed from your data using expressions. Each calculated field consists of a name (used to reference it in calculations, filters, or ordering) and an expression (a formula that derives its value from existing fields).

​
How to Specify an Absolute Time Range

To specify an absolute time range, use start_time and end_time (both UNIX timestamps) to describe the desired range: 
{
  "start_time": 1727755200,
  "end_time": 1728964800
}
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 2024-05-01 00:00 UTC”: 
{
  "end_time": 1714536000,
  "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

​
Top Ten Unique user_agents by Volume

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

​
Query Builder Query

VISUALIZEWHEREGROUP BY
COUNTuser_agent
Use the time picker to apply “Last 1 Hour”.

​
JSON

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

​
Average Content Length of Events

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

​
Query Builder Query

VISUALIZEWHERE
AVG (content_length)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
}

​
Filter Events Based on Length of Duration and Service Name

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):

​
Query Builder Query

VISUALIZEWHERE
HEATMAP(match_quality)duration_ms > 500
service.name != “fraud”

​
JSON

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

​
Top 100 Results for Average Duration and 99th Percentile of Event Duration Ranked by Duration and User

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.

​
Query Builder Query

VISUALIZEWHEREGROUP BY
AVG(duration_ms)
P99(duration_ms)		result = 200user_id
build_id
ORDER BYLIMIT
P99(duration_ms) desc
user_id desc		100

​
JSON

{
  "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
}

​
Top 100 Results for Events with a Duration With Longer Than 10000 Milliseconds

This query specification describes a query over the last hour that 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 that have a P99(duration_ms) > 10000, ordered first by P99(duration_ms) values, then user_id.

​
Query Builder Query

VISUALIZEWHEREGROUP BY
AVG(duration_ms)
P99(duration_ms)		result = 200user_id
build_id
ORDER BYLIMITHAVING
P99(duration_ms) desc
user_id		100P99(duration_ms) > 10000

​
JSON

{
  "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" }
  ],
  "havings": [
    { "calculate_op": "P99", "column": "duration_ms", "op": ">", "value": 10000 }
  ],
  "limit": 100,
  "time_range": 3600
}

​
Match Specific Users and Identify Experienced Errors

This query specification describes a query that filters for specific users based on their email address who are experiencing errors broken down by error code.

​
Query Builder Query

VISUALIZEWHEREGROUP BY
COUNTapp.user.email in foo@example.com, bar@example.com
error exists		error.code

​
JSON

{
    "breakdowns": [
        "error.code"
    ],
    "calculations": [
        { "op": "COUNT" }
    ],
    "filters": [
        { "column": "app.email", "op": "in", "value": ["foo@example.com", "bar@example.com"]},
        { "column": "error", "op": "exists"}
    ],
    "filter_combination": "AND"
}

​
Calculation Operators

Calculation operators are consistent between the API and the UI. The available calculation "op" values are:
  • COUNT (optionally expects an accompanying "column" value)
  • CONCURRENCY (does not expect an accompanying "column" value)
  • SUM
  • AVG
  • COUNT_DISTINCT
  • MAX
  • MIN
  • P001
  • P01
  • P05
  • P10
  • P20
  • P25
  • P50
  • P75
  • P80
  • P90
  • P95
  • P99
  • P999
  • HEATMAP
  • RATE_AVG
  • RATE_SUM
  • RATE_MAX

​
Filter Operators

Filter operators are consistent between the API and the UI. The available filter "op" values are:
  • =
  • !=
  • >
  • >=
  • <
  • <=
  • starts-with
  • does-not-start-with
  • ends-with
  • does-not-end-with
  • exists (does not expect an accompanying "value")
  • does-not-exist (does not expect an accompanying "value")
  • contains
  • does-not-contain
  • in (filter "value" must be present and be an array - example)
  • not-in (filter "value" must be present and be an array)