Skip to content

Query Language (OQL)

OQL (Observability Query Language) is how you ask Hexcovery questions about your data. It is a small, SQL-inspired language designed to read like English: a query says what you want, from where, over which time window, and Hexcovery does the rest.

SELECT avg(cpu_user_pct) FROM host
WHERE host = 'web-1'
EVERY 1m LAST 1h

"Give me the average user CPU on host web-1, in one-minute buckets, over the last hour."

Where you write OQL

OQL is the only query surface in Hexcovery. There is no raw SQL: you never touch the underlying database directly. Everywhere you can run a query, you run OQL:

  • The Query Explorer — the interactive page in the dashboard with autocomplete, syntax highlighting, and automatic visualization of results. See Query Explorer.
  • Dashboard widgets — every chart you pin to a dashboard is backed by an OQL query.
  • The query API — the same language over HTTP, for automation and integrations. See Query API.

All three send your query to the same place and get back the same result, so anything you prototype in the Explorer works verbatim in a widget or an API call.

The shape of a query

Every query follows one fixed skeleton. Only SELECT, FROM, and a time window are required; the rest are optional and always appear in this order:

SELECT <columns or aggregates>
FROM   <table>
[WHERE <conditions>]
[BY    <columns>]
[EVERY <bucket>]
LAST <duration>  |  BETWEEN <start> AND <end>
[TOP   <n>]
Clause Meaning
SELECT What to return — raw columns, or aggregates like avg(...), count(*).
FROM Which table to read (host, logs, spans, custom.<metric>, …).
WHERE Filter rows. Supports =, IN, CONTAINS full-text, map access.
BY Split the result into one group per distinct value (faceting).
EVERY Bucket into time intervals → a time series.
LAST / BETWEEN The time window. One of these is mandatory.
TOP Keep only the top N groups by the first aggregate.

A time window is always required — Hexcovery never runs an unbounded query.

Results visualize themselves

You don't pick a chart type. The shape of your query tells Hexcovery how to show it:

Your query You get
Has EVERY (time buckets) A time-series line/area chart
Has BY but no EVERY A bar chart / ranked table
One aggregate, no BY, no EVERY A single number
Raw columns, no aggregate A table (e.g. log lines)

Learn OQL

  • Syntax — every clause, operator, and the dot accessor for map attributes.
  • Functions — the aggregate functions, counters vs gauges, percentiles.
  • Tables — what you can query and the columns each table exposes.
  • Examples — ready-to-use queries grouped by use case.

New to the data model behind the tables? Read Services, External Services, and Projects first — it explains the entities OQL lets you query. Or jump straight back to the documentation home.