ClickHouse.

Connect Orchid to ClickHouse Cloud or any self-hosted ClickHouse cluster. The connector speaks both the HTTPS protocol (port 8443 / Cloud) and the native protocol (port 9000 / self-hosted).

Requirements

• A ClickHouse server (Cloud or self-hosted) reachable from your machine.
• A user with SELECT on the databases you want to query.
• Network reachability — direct, VPN, or SSH tunnel.

Connect to ClickHouse Cloud

1. In ClickHouse Cloud, open your service → Connect. Copy the HTTPS host.
2. In Orchid: Integrations → + Add connection → ClickHouse.
3. Fill in:
   • Host — e.g. abc123.us-east-2.aws.clickhouse.cloud
   • Port — 8443 for HTTPS
   • Protocol — HTTPS
   • Database — default typically
   • User — default or a user you created
   • Password — generated in ClickHouse Cloud
   • Toggle Require TLS on (Cloud requires it)
4. Click Test connection → save.

Connect to self-hosted ClickHouse

Self-hosted clusters usually expose the native protocol on port 9000 (faster for bulk queries) and HTTPS on 8123 / 8443. Pick:

• Native — port 9000. Better performance for large result sets.
• HTTPS — port 8443 (TLS) or 8123 (plain). Easier through HTTP proxies and firewalls.

Optional settings

Default database

Set a default database in the connection settings. ClickHouse allows SELECT * FROM table unqualified once a default is set.

SSH tunnel

For clusters in private networks, toggle Use SSH tunnel. Same form as PostgreSQL — bastion host, user, private key. Useful for internal ClickHouse clusters behind a VPN.

MergeTree basics

ClickHouse's default table engine family is MergeTree. Tables in this family have an ORDER BY key that doubles as the primary sort and the primary index. Queries that filter on a prefix of the ORDER BY key are dramatically faster than those that don't — by orders of magnitude.

-- A typical MergeTree table
CREATE TABLE events (
  event_ts   DateTime,
  user_id    UInt64,
  event_type LowCardinality(String),
  payload    String
)
ENGINE = MergeTree
ORDER BY (event_ts, user_id)
PARTITION BY toYYYYMM(event_ts);

-- This query uses the index efficiently
SELECT count() FROM events
WHERE event_ts >= '2026-05-01 00:00:00'
  AND event_ts <  '2026-05-15 00:00:00';

-- This one scans the whole table
SELECT count() FROM events
WHERE event_type = 'signup';
      

Rules of thumb for fast queries: always filter on the leading columns of the ORDER BY key, and on the PARTITION BY column when present.

Common gotchas

• "Code: 516. Authentication failed" — wrong user or password. ClickHouse Cloud uses the default user by default; the password is auto-generated and shown on the Connect page.
• HTTPS handshake fails — port mismatch. Cloud requires 8443 for HTTPS; 9440 for native TLS. Self-hosted defaults are 8123 (plain HTTP) and 9000 (plain native).
• "Memory limit exceeded" — ClickHouse caps per-query memory by default. A wide aggregation or join can exhaust it. Raise per-query with SET max_memory_usage = 20000000000; at the top of the cell, or rewrite the query to avoid materializing huge intermediate results.
• Slow first query after idle — ClickHouse Cloud idles services. First query after several minutes can take ~5–10 seconds while compute resumes.
• Unexpected NULLs in result — ClickHouse's String type is non-nullable by default; NULL only exists with Nullable(String). Aggregations and joins on the wrong nullability can silently return weird results.
• Schema panel shows engines you don't recognize — system tables use SystemNumbers, SystemMetrics, etc. They're fine to query; just don't try to INSERT into them.

Example queries

-- List databases
SHOW DATABASES;
      

-- Tables and their sizes in the current database
SELECT
  database,
  table,
  formatReadableSize(sum(bytes_on_disk)) AS size,
  sum(rows) AS rows
FROM system.parts
WHERE active AND database = currentDatabase()
GROUP BY database, table
ORDER BY sum(bytes_on_disk) DESC;
      

-- Top events per day for the last week
SELECT
  toDate(event_ts) AS day,
  event_type,
  count() AS events
FROM events
WHERE event_ts >= now() - interval 7 day
GROUP BY day, event_type
ORDER BY day, events DESC
LIMIT 100;
      

Where to go next

For more on writing SQL cells, see SQL cells.