ClickHouse HTTP Interface: API

Tip: Basic Query

curl 'http://localhost:8123/?query=SELECT+1'

Gotcha: POST for Large Queries

curl -d "SELECT * FROM events WHERE date = '2024-01-01'" 'http://localhost:8123/'

Tip: JSON Format

curl 'http://localhost:8123/?query=SELECT+*+FROM+events+FORMAT+JSON'

Gotcha: Insert Data

curl -d @data.csv 'http://localhost:8123/?query=INSERT+INTO+events+FORMAT+CSV'

Tip: Database Selection

curl 'http://localhost:8123/?database=mydb&query=SELECT+1'

Gotcha: Authentication

curl -u user:password 'http://localhost:8123/?query=SELECT+1'

Tip: Order of Columns in ORDER BY Matters Massively

ClickHouse's primary key is defined by ORDER BY. Put high-cardinality columns first for better data skipping. ORDER BY (timestamp, user_id) is very different from ORDER BY (user_id, timestamp) in query performance.

Tip: Use LowCardinality for Enum-Like Strings

Strings like status, country, browser benefit from LowCardinality(String) — it's stored as a dictionary internally, reducing storage 10x and speeding up scans.

Gotcha: Mutations Are Heavy

ALTER TABLE ... UPDATE and DELETE in ClickHouse create new parts instead of modifying in place. A single mutation on a large table can take hours and block merges. Design for append-only from day one.

Senior Insight

ClickHouse's HTTP interface is a hidden gem. Every SQL operation is accessible via REST API at port 8123. I've used it for serverless query execution, direct browser queries for debugging, and language-agnostic integration. The HTTP interface has lower overhead than the native TCP protocol for one-off queries. I've built ad-hoc reporting tools that let non-technical users run parameterized ClickHouse queries through a web form backed by HTTP requests.

Source: ClickHouse Blog (https://clickhouse.com/blog), Altinity Blog (https://altinity.com/blog), Altinity Knowledge Base (https://kb.altinity.com/)