Reference: Query Specification

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).
formulas: a list of objects that combine named calculations into an expression (Query Math). Each formula consists of a name and an expression that references calculations by name, such as $errors / $total. To reference a calculation in a formula, give that calculation a name in the calculations field (each calculation may also carry its own filters).

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

VISUALIZE	WHERE	GROUP BY
COUNT		`user_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

VISUALIZE	WHERE
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

VISUALIZE	WHERE
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

VISUALIZE	WHERE	GROUP BY
AVG(duration_ms) P99(duration_ms)	result = 200	`user_id` `build_id`

ORDER BY	LIMIT
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

VISUALIZE	WHERE	GROUP BY
AVG(duration_ms) P99(duration_ms)	result = 200	user_id build_id

ORDER BY	LIMIT	HAVING
P99(duration_ms) desc user_id	100	P99(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

VISUALIZE	WHERE	GROUP BY
COUNT	app.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
COUNT_DATAPOINTS (time series metrics datasets only; counts datapoints ingested across all metric fields, or for a single metric when given a "column")
HISTOGRAM_COUNT (time series metrics datasets only; expects a histogram "column" and counts the observations recorded in it)

On time series metrics datasets, temporal aggregation (LAST, SUMMARIZE, INCREASE, and the per-second RATE) is applied automatically based on each metric’s type, so it is not selected as a calculation op. Choose a spatial calculation such as SUM, AVG, MAX, a percentile, or HISTOGRAM_COUNT on the metric column, and Honeycomb applies the matching temporal function underneath (for example, INCREASE for a cumulative counter). To learn more, visit Temporal Aggregation Concepts.RATE_AVG, RATE_SUM, RATE_MAX, CONCURRENCY, and bare COUNT (without a column) are not available on time series metrics datasets.

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)

Getting Started

Reference

API Endpoints

Reference: Query Specification

Fields on a Query Specification

How to Specify an Absolute Time Range

Examples

Top Ten Unique `user_agents` by Volume

Query Builder Query

JSON

Average Content Length of Events

Query Builder Query

Filter Events Based on Length of Duration and Service Name

Query Builder Query

JSON

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

Query Builder Query

JSON

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

Query Builder Query

JSON

Match Specific Users and Identify Experienced Errors

Query Builder Query

JSON

Calculation Operators

Filter Operators

​Fields on a Query Specification

​How to Specify an Absolute Time Range

​Examples

​Top Ten Unique user_agents by Volume

​Query Builder Query

​JSON

​Average Content Length of Events

​Query Builder Query

​Filter Events Based on Length of Duration and Service Name

​Query Builder Query

​JSON

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

​Query Builder Query

​JSON

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

​Query Builder Query

​JSON

​Match Specific Users and Identify Experienced Errors

​Query Builder Query

​JSON

​Calculation Operators

​Filter Operators

Fields on a Query Specification

How to Specify an Absolute Time Range

Examples

Top Ten Unique `user_agents` by Volume

Query Builder Query

JSON

Average Content Length of Events

Query Builder Query

Filter Events Based on Length of Duration and Service Name

Query Builder Query

JSON

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

Query Builder Query

JSON

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

Query Builder Query

JSON

Match Specific Users and Identify Experienced Errors

Query Builder Query

JSON

Calculation Operators

Filter Operators