HTTP interface

The HTTP interface is the most universal way to talk to ClickHouse. Default ports: 8123 (plain), 8443 (TLS). Implementation: src/Server/HTTPHandler.cpp.

Endpoints

Path	What it does
/	Default query endpoint. Reads query from the URL or the request body.
/?query=...	Same, with the SQL in the URL. Body becomes input data for INSERT.
/ping	Returns Ok.
/replicas_status	Per-replica delay summary (handler in ReplicasStatusHandler.cpp).
/play	Embedded SQL UI.
/dashboard	Embedded ops dashboard.
/binary	Build info.
/metrics	Prometheus exposition (PrometheusMetricsWriter.cpp).
/?<custom>	Custom routes wired up via <http_handlers> in the config.
/static (configurable)	Static-file responses (StaticRequestHandler.cpp).

Examples

# Trivial select
curl 'http://localhost:8123/?query=SELECT 1'

# Long query in the body
curl 'http://localhost:8123/?database=default' \
  --data-binary 'SELECT count() FROM system.numbers LIMIT 1000000'

# Output format
curl 'http://localhost:8123/?query=SELECT%201&default_format=JSON'

# INSERT from a file
curl 'http://localhost:8123/?query=INSERT INTO t FORMAT CSV' --data-binary @data.csv

# Compressed body in, native compression on the way out
curl --compressed -H 'Content-Encoding: zstd' \
  'http://localhost:8123/?query=INSERT INTO t FORMAT Native&compress=1' \
  --data-binary @blob.zst

Important parameters

Param	Meaning
query	SQL text. May also live in the request body.
database	Default database.
user / password	Basic auth alternative.
default_format	Output format (Pretty, JSON, CSVWithNames, Parquet, …).
compress=1	Use ClickHouse-native compression for the response.
decompress=1	Body is ClickHouse-native compressed.
enable_http_compression=1	Allow HTTP compression negotiation.
session_id	Open a session (settings persist across requests).
session_timeout	Override the session TTL.
query_id	Externally-supplied query id.
wait_end_of_query=1	Buffer the entire response before sending.
param_<name>	Pass parameterised query parameter.

Authentication

• Basic auth: curl -u user:pass ....
• Headers: X-ClickHouse-User, X-ClickHouse-Key, X-ClickHouse-Database.
• mTLS via <openSSL> config and --cacert/--cert/--key.
• Bearer / JWT (<jwt_validator> config).

Sessions

session_id=<...> makes consecutive requests share a Context. Settings, temporary tables, and USE survive across calls. Sessions have a TTL (session_timeout or default_session_timeout); idle sessions expire.

Response format

The body is the result formatted in default_format. Useful response headers:

• X-ClickHouse-Server-Display-Name
• X-ClickHouse-Format
• X-ClickHouse-Timezone
• X-ClickHouse-Summary — JSON of read/written rows/bytes, peak memory, etc.
• X-ClickHouse-Progress — repeated per buffered chunk; rows/bytes processed.
• X-ClickHouse-Query-Id.

Custom HTTP handlers

<http_handlers> in config.xml lets the operator declaratively add routes:

<http_handlers>
  <rule>
    <url>/healthz</url>
    <methods>GET</methods>
    <handler>
      <type>predefined_query_handler</type>
      <query>SELECT 1</query>
    </handler>
  </rule>
</http_handlers>

Three handler types: predefined_query_handler, dynamic_query_handler, static.

Streaming and chunked responses

Large SELECTs stream chunked HTTP responses. The body is consumed format-by-format — for JSON the server emits the data array as it goes; for Native it emits whole Blocks.

Related pages

• Server protocols — implementation walkthrough.
• Formats
• Access control