API & TimeseriesQL Reference¶

Core HTTP routes for writes, queries, and health, plus TimeseriesQL. Authentication (which routes need credentials, 401 vs 403 on internal APIs, Basic/Token/u&p) is covered in Authentication. For cluster, replication, Raft, and internal route lists, see Cluster, replication, and internal routes below; the authoritative list is src/adapters/http/router.rs.

HTTP API¶

All endpoints return InfluxDB v1-compatible response headers:

POST /write¶

Write time-series data using InfluxDB line protocol.

Query parameters:

Supports: Content-Encoding: gzip for compressed payloads.

Response codes:

GET/POST /query¶

Execute TimeseriesQL queries.

Query parameters:

Accept header:

POST body: Parameters can be sent as application/x-www-form-urlencoded. Body parameters override query string parameters.

GET/HEAD /ping¶

Returns 204 No Content with version headers. Compatible with InfluxDB client library connection tests.

GET /health¶

Returns JSON health status:

{"status": "pass", "message": "ready for queries and writes"}

GET /metrics¶

Prometheus-format metrics. See Administration for the full metric catalog.

GET /api/v1/statements¶

Returns recently executed statement summaries (when statement_summary.enabled = true).

Cluster-only endpoints (subset)¶

These are available when cluster mode is enabled and are often used with hyperbytedb-debug or internal automation.

Cluster, replication, and internal routes¶

The following apply when the corresponding features are compiled in and enabled. When [auth] enabled = true, these routes require admin credentials (same u/p, Basic, or Token as elsewhere); a logged-in non-admin user receives 403. If auth is off, the HTTP layer does not check credentials—use network controls in production. Details: Authentication.

Cluster / peer (non-Raft)

Raft (when Raft is enabled)

GET /health/ready¶

Readiness probe: verifies the query engine (chDB) is usable. Used for Kubernetes readiness checks (see Installation).

TimeseriesQL Reference¶

SELECT¶

SELECT <field_expression>[, ...] FROM <measurement>
  [INTO <target_measurement>]
  [WHERE <condition>]
  [GROUP BY time(<interval>[, <offset>])[, <tag_key>...]]
  [ORDER BY time [ASC|DESC]]
  [LIMIT <n>] [OFFSET <n>]
  [SLIMIT <n>] [SOFFSET <n>]
  [fill(<option>)]
  [TZ('<timezone>')]

Field expressions: - Column references: "usage_idle", * - Aggregate functions: mean("value"), count(*), etc. - Transform functions: derivative(mean("value"), 1s), etc. - Arithmetic: mean("a") * 100 + mean("b") - Aliases: mean("value") AS avg_value - Type hints: "host"::tag, "value"::field

FROM clause: - Single: FROM "cpu" - Fully-qualified: FROM "mydb"."myrp"."cpu" - Regex: FROM /^cpu.*/ - Subquery: FROM (SELECT mean("value") FROM "cpu" GROUP BY time(1h))

WHERE Operators¶

Time Expressions¶

• now() — current server time
• Duration literals: 1ns, 5u, 100ms, 30s, 15m, 2h, 7d, 4w
• RFC3339: '2024-01-01T00:00:00Z'

Fill Options¶

Aggregate Functions¶

Transform Functions¶

Transforms can wrap aggregates:

SELECT non_negative_derivative(mean("bytes_recv"), 1s) FROM "net"
  WHERE time > now() - 1h GROUP BY time(10s)

SHOW Commands¶

SHOW DATABASES
SHOW MEASUREMENTS [ON <database>]
SHOW TAG KEYS [FROM <measurement>]
SHOW TAG VALUES [FROM <measurement>] WITH KEY = "<key>"
SHOW TAG VALUES [FROM <measurement>] WITH KEY =~ /<regex>/
SHOW TAG VALUES [FROM <measurement>] WITH KEY IN ("<key1>", "<key2>")
SHOW FIELD KEYS [FROM <measurement>]
SHOW SERIES [FROM <measurement>]
SHOW RETENTION POLICIES [ON <database>]
SHOW USERS
SHOW CONTINUOUS QUERIES

DDL Statements¶

CREATE DATABASE "<name>"
DROP DATABASE "<name>"
DROP MEASUREMENT "<name>"

CREATE RETENTION POLICY "<name>" ON "<db>"
  DURATION <duration> REPLICATION <n> [SHARD DURATION <duration>] [DEFAULT]
ALTER RETENTION POLICY "<name>" ON "<db>"
  DURATION <duration> [REPLICATION <n>] [DEFAULT]
DROP RETENTION POLICY "<name>" ON "<db>"

CREATE USER "<name>" WITH PASSWORD '<password>'
DROP USER "<name>"
SET PASSWORD FOR "<name>" = '<password>'

CREATE CONTINUOUS QUERY "<name>" ON "<db>"
  [RESAMPLE EVERY <interval> FOR <interval>]
  BEGIN <select_into_statement> END
DROP CONTINUOUS QUERY "<name>" ON "<db>"

DELETE¶

DELETE FROM "<measurement>" [WHERE <condition>]

DELETE marks data with tombstone records. Tombstoned data is excluded from queries at read time; Parquet files are not rewritten.

InfluxDB v1 Compatibility Matrix¶

What works identically¶

• Line protocol write format and semantics
• /write and /query endpoint behavior
• /ping response for client library connection tests
• JSON response shapes ({"results":[...]})
• epoch parameter for timestamp formatting
• Authentication methods (query params, Basic, Token)
• Multiple statement queries (; separator)
• All SHOW commands listed above
• CREATE/DROP DATABASE, retention policy management
• Gzip write support
• Chunked query responses

Known Differences¶

Recommendations¶

• Use fill(null) or fill(none) when exact InfluxDB behavior is required at time boundaries.
• Test fill(previous) and fill(linear) results for critical dashboards.
• Avoid SELECT INTO with regex measurement sources.
• Plan authorization around admin/non-admin roles only.

See Also¶

• Authentication — Enabling auth, public endpoints, 401/403 on internal routes
• Basic operations — Getting started with writes and queries
• Advanced features — Clustering, CQs, TLS
• Configuration — All settings reference