honeycomb · Schema

Honeycomb Query Specification

Defines a query specification for retrieving and aggregating data in Honeycomb. Queries are used across boards, triggers, SLOs, and query annotations.

Properties

Name	Type	Description
calculations	array	The calculations (aggregations) to perform on the query data.
filters	array	Filters to apply to events before aggregation.
filter_combination	string	How to combine multiple filters. Defaults to AND.
breakdowns	array	Column names to group results by.
orders	array	Ordering rules for the query results.
havings	array	Post-aggregation filters applied to calculated results.
time_range	integer	The relative time range in seconds to query over.
start_time	integer	Unix timestamp for the absolute query start time.
end_time	integer	Unix timestamp for the absolute query end time.
granularity	integer	The time granularity of results in seconds.
limit	integer	Maximum number of result rows to return.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://honeycomb.io/schemas/honeycomb/query.json",
  "title": "Honeycomb Query Specification",
  "description": "Defines a query specification for retrieving and aggregating data in Honeycomb. Queries are used across boards, triggers, SLOs, and query annotations.",
  "type": "object",
  "properties": {
    "calculations": {
      "type": "array",
      "description": "The calculations (aggregations) to perform on the query data.",
      "items": {
        "$ref": "#/$defs/Calculation"
      }
    },
    "filters": {
      "type": "array",
      "description": "Filters to apply to events before aggregation.",
      "items": {
        "$ref": "#/$defs/Filter"
      }
    },
    "filter_combination": {
      "type": "string",
      "description": "How to combine multiple filters. Defaults to AND.",
      "enum": ["AND", "OR"]
    },
    "breakdowns": {
      "type": "array",
      "description": "Column names to group results by.",
      "items": {
        "type": "string"
      }
    },
    "orders": {
      "type": "array",
      "description": "Ordering rules for the query results.",
      "items": {
        "$ref": "#/$defs/Order"
      }
    },
    "havings": {
      "type": "array",
      "description": "Post-aggregation filters applied to calculated results.",
      "items": {
        "$ref": "#/$defs/Having"
      }
    },
    "time_range": {
      "type": "integer",
      "minimum": 1,
      "description": "The relative time range in seconds to query over."
    },
    "start_time": {
      "type": "integer",
      "description": "Unix timestamp for the absolute query start time."
    },
    "end_time": {
      "type": "integer",
      "description": "Unix timestamp for the absolute query end time."
    },
    "granularity": {
      "type": "integer",
      "minimum": 1,
      "description": "The time granularity of results in seconds."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "Maximum number of result rows to return."
    }
  },
  "$defs": {
    "Calculation": {
      "type": "object",
      "description": "An aggregation calculation to perform.",
      "required": ["op"],
      "properties": {
        "op": {
          "type": "string",
          "description": "The aggregation operation to perform.",
          "enum": [
            "COUNT",
            "SUM",
            "AVG",
            "COUNT_DISTINCT",
            "MAX",
            "MIN",
            "P001",
            "P01",
            "P05",
            "P10",
            "P25",
            "P50",
            "P75",
            "P90",
            "P95",
            "P99",
            "P999",
            "HEATMAP",
            "RATE_AVG",
            "RATE_SUM",
            "RATE_MAX"
          ]
        },
        "column": {
          "type": "string",
          "description": "The column to perform the calculation on. Not required for COUNT."
        }
      }
    },
    "Filter": {
      "type": "object",
      "description": "A filter condition applied to events.",
      "required": ["column", "op"],
      "properties": {
        "column": {
          "type": "string",
          "description": "The column name to filter on."
        },
        "op": {
          "type": "string",
          "description": "The comparison operator.",
          "enum": [
            "=",
            "!=",
            ">",
            ">=",
            "<",
            "<=",
            "starts-with",
            "does-not-start-with",
            "contains",
            "does-not-contain",
            "exists",
            "does-not-exist",
            "in",
            "not-in"
          ]
        },
        "value": {
          "description": "The value to compare against. Not required for exists/does-not-exist operators."
        }
      }
    },
    "Order": {
      "type": "object",
      "description": "An ordering rule for query results.",
      "properties": {
        "column": {
          "type": "string",
          "description": "The column to order by."
        },
        "op": {
          "type": "string",
          "description": "The aggregation operation to order by, if ordering by a calculation."
        },
        "order": {
          "type": "string",
          "description": "The sort direction.",
          "enum": ["ascending", "descending"]
        }
      }
    },
    "Having": {
      "type": "object",
      "description": "A post-aggregation filter applied to calculated results.",
      "properties": {
        "calculate_op": {
          "type": "string",
          "description": "The calculation operation this having clause applies to."
        },
        "column": {
          "type": "string",
          "description": "The column the calculation is performed on."
        },
        "op": {
          "type": "string",
          "description": "The comparison operator.",
          "enum": [">", ">=", "<", "<=", "=", "!="]
        },
        "value": {
          "type": "number",
          "description": "The value to compare the calculated result against."
        }
      }
    }
  }
}