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¶

Every response carries these 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/DELETE /api/v1/statements¶

• GET — Returns recently executed statement summaries (when statement_summary.enabled = true).
• DELETE — Resets the statement summary ring buffer.

Cluster-only endpoints (subset)¶

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

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)

Series sharding (when [sharding] enabled = true)

See Deep Dive: Clustering — Series Sharding for scatter, failover, and epoch semantics.

POST /api/v1/chdb¶

Execute raw ClickHouse SQL against the embedded chDB engine. Admin-only when auth is enabled.

Query parameters:

Body: Raw ClickHouse SQL as application/x-www-form-urlencoded with key q.

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

Column names follow InfluxQL: an alias wins; otherwise a function call is named after the function (mean("value") → mean), an expression after the fields and functions in it ("a" + "b" → a_b), and a repeated name gets _1, _2 (mean("a"), mean("b") → mean, mean_1).

The time column is always first. Raw selects return each point's time and GROUP BY time() returns each bucket's start. An aggregate without GROUP BY time() returns one row stamped 1970-01-01T00:00:00Z, whatever the WHERE time range; a lone first(), last(), max() or min() returns the selected point's own time.

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¶

Selector Functions¶

These return up to N stored points per group (each GROUP BY time() bucket and tag set), each at its own time, in time order.

Other fields and tags may be selected beside them (SELECT top("value", 3), "host"), taken from the same points, but not other functions. LIMIT and OFFSET apply to the points returned.

A raw field cannot be grouped by time: SELECT "value" ... GROUP BY time(1m) fails with GROUP BY requires at least one aggregate function, as in InfluxDB.

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>")
  [WHERE <tag conditions>] [LIMIT <n>] [OFFSET <n>]
                                      -- tag conditions: =, !=, =~, !~, AND, OR,
                                      -- with or without ::tag; time is ignored
SHOW FIELD KEYS [FROM <measurement>]
SHOW SERIES [FROM <measurement>]
SHOW SERIES [EXACT] CARDINALITY [ON <db>] [FROM <measurement>] [WHERE <tag condition>]
  [LIMIT n] [OFFSET n]
SHOW MEASUREMENT [EXACT] CARDINALITY [ON <db>] [FROM <measurement>]
  [WITH MEASUREMENT <op> <name|/regex/>]
  [WHERE <tag condition>]
SHOW TAG KEY [EXACT] CARDINALITY [ON <db>] [FROM <measurement>] [WHERE <tag condition>]
SHOW TAG VALUES [EXACT] CARDINALITY [ON <db>] [FROM <measurement>] [WITH KEY <op> <key>]
  [WHERE <tag condition>]
SHOW FIELD KEY [EXACT] CARDINALITY [ON <db>] [FROM <measurement>]
SHOW RETENTION POLICIES [ON <database>]
SHOW USERS
SHOW GRANTS FOR <user>                -- admin; database, privilege
SHOW CONTINUOUS QUERIES

Cardinality¶

The CARDINALITY statements count what the matching SHOW would list, and the counts are always exact. Without a WHERE, they come from the metadata caches without scanning anything: the series index (on a sharded cluster, each region's peer counts its own range, so a replicated series counts once), the tag value counts, and the measurement metadata. A WHERE is matched against each series' tags, like SHOW TAG VALUES ... WHERE.

The output follows InfluxDB 1.x. SHOW SERIES CARDINALITY with no FROM or WHERE, and SHOW MEASUREMENT CARDINALITY with no FROM, WITH or WHERE, return one row under cardinality estimation. InfluxDB reports an estimate there; HyperbyteDB reports the exact count. EXACT, or any filter, returns count instead, with one series per measurement, and measurements with a count of zero are left out. SHOW FIELD KEY CARDINALITY refuses WHERE, because fields aren't indexed by tag.

> SHOW SERIES CARDINALITY ON telegraf
cardinality estimation
----------------------
1520

> SHOW SERIES EXACT CARDINALITY ON telegraf FROM cpu
name: cpu
count
-----
304

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>'
GRANT READ | WRITE | ALL ON "<db>" TO "<user>"
REVOKE READ | WRITE | ALL ON "<db>" FROM "<user>"
GRANT ALL PRIVILEGES TO "<user>"       -- make admin
REVOKE ALL PRIVILEGES FROM "<user>"

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

CREATE MATERIALIZED VIEW "<name>" ON "<db>"
  AS <select_into_statement>          -- every column needs AS "<name>"
DROP MATERIALIZED VIEW "<name>" ON "<db>"
SHOW MATERIALIZED VIEWS

SET <setting> = <integer> | TRUE | FALSE | '<text>' | DEFAULT
                                      -- admin; applied on every node at once
SHOW SETTINGS                         -- name, value, source, config, description

Runtime settings¶

A SET overrides the config file on every node. source in SHOW SETTINGS is set (an override), config (the node's config file) or auto (derived from the node's CPUs). Each node keeps its own config value underneath, so DEFAULT returns every node to its own.

The cardinality limits apply to client writes. Region copies, replicas and node syncs copy data that already exists, so a lower limit never refuses them.

The scheduler settings only do anything on a sharded cluster; elsewhere SHOW SETTINGS lists them without a value. Settings that need a restart anyway (listen addresses, data paths, Raft timing, replication factor, TLS, auth) are not runtime settings.

SET is replicated through Raft and stored, so it survives a restart and reaches nodes that join later. SET <setting> = DEFAULT removes the override. Do not run SET while a rolling upgrade from a version without it is in progress: nodes on the older build cannot decode it.

DELETE¶

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

DELETE marks data with tombstone records. Tombstoned data is excluded from queries at read time; underlying MergeTree rows are not rewritten in place.

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