ClickHouse
Using data-peek with ClickHouse
ClickHouse
ClickHouse support is in beta. It is tested against ClickHouse 24.8. Report problems on GitHub.
data-peek connects to ClickHouse over its HTTP interface. ClickHouse support is for querying and browsing. You can run scripts, read typed results, explore databases and tables, and read query plans. Editing data and changing table structure are not available on ClickHouse connections.
Connection Setup
- Click Add Connection in the sidebar
- Select ClickHouse as the database type
- Enter your connection details:
- Host: Your ClickHouse hostname or IP
- Port: Default is
8123. ClickHouse usually serves HTTPS on8443. - Database: Default is
default - Username: Default is
default - Password: Your password
Use the HTTP Port
data-peek uses the ClickHouse HTTP interface, not the native TCP protocol. Ports 9000 and 9440 are native-protocol ports. If you enter one of them, data-peek refuses the connection and suggests the HTTP port instead: usually 8123, or 8443 for TLS.
Connection Strings
Paste a URL that starts with clickhouse:// or clickhouses:// to fill in the form:
clickhouse://default:password@localhost:8123/defaultA clickhouses:// URL, or a ?secure=true parameter, turns on SSL.
SSL and SSH Tunnels
Turn on SSL to connect over HTTPS. To reach a server behind a bastion host, use an SSH tunnel. See SSH Tunnels for configuration details.
Supported Features
| Feature | Support |
|---|---|
| Query execution | ✓ |
| Multiple statements | ✓ |
| Schema explorer | ✓ |
| Table preview and pagination | ✓ |
| Views and materialized views | ✓ |
| Enum types | ✓ |
| Query plans | Text plans |
| Cancel and timeouts | ✓ |
| Column statistics | ✓ |
| Performance analysis | ✓ |
| Health Monitor | Active Queries, Table Sizes |
| AI assistant | ✓ |
| MCP server | ✓ |
| SSH tunnels | ✓ |
| Inline editing | - |
| Table designer | - |
| Transactions | - |
Not Available on ClickHouse
data-peek hides these features on ClickHouse connections:
- Inline editing
- Table designer
- CSV import
- Data generator
- Transactions and step-through debugging
- LISTEN/NOTIFY
- Triggers
- SQL dump export and import
- Schema Intel
- Health Monitor panels for locks and cache stats
- Cross-tab
@namereferences
Query Execution
Multiple Statements
data-peek runs a script one statement at a time on a single ClickHouse session. A SET applies to every statement after it in the same run:
SET max_threads = 2;
SELECT getSetting('max_threads');Each statement that returns rows gets its own result tab. A SET does not carry over to your next run.
FORMAT Clauses
data-peek formats results itself. If a query ends with a FORMAT clause, such as FORMAT CSV, data-peek refuses it and asks you to remove the clause. To save results to a file, use Export.
Autocomplete
The editor suggests common ClickHouse functions, such as uniqExact, toStartOfInterval, and arrayJoin, and ClickHouse types, such as UInt64, LowCardinality, and DateTime64. Most ClickHouse function and type names are case-sensitive, so suggestions are inserted with ClickHouse’s own casing.
Types
Int64,UInt64, andDecimalvalues display exactly as the server returns them. data-peek never rounds them through JavaScript numbers, and these columns still sort numerically.- The results grid shows each column’s ClickHouse type as written, for example
LowCardinality(String)orNullable(DateTime64(3)). Nullable(T)columns show as nullable in the schema explorer, including when wrapped inLowCardinality.Enum8andEnum16columns list their allowed values.
Schema Explorer
- Each ClickHouse database appears as a schema. The connection’s own database is listed first.
- Tables, views, and materialized views appear with their columns and types.
- The
.innertables that back materialized views are hidden. - The
system,INFORMATION_SCHEMA, andinformation_schemadatabases are hidden. You can still query them in the editor. - Columns in a table’s primary key are marked as key columns. In ClickHouse, the primary key defaults to the sorting key.
- Row counts come from the
total_rowsestimate insystem.tables.
ClickHouse has no foreign keys, so ER diagrams show tables and columns without relationship lines.
Health Monitor
The Health Monitor (click Health Monitor in the sidebar) shows two panels for ClickHouse connections:
- Active Queries — lists queries currently running in
system.processes, with the user, elapsed time, and a truncated view of the query text. Use the Kill button (skull icon) to sendKILL QUERYfor a selected query. The PID column shows the ClickHousequery_id, which is a string rather than an integer. - Table Sizes — shows per-table disk usage from
system.parts.
Cache hit ratios and lock monitoring are not available for ClickHouse.
Column Statistics
The column statistics panel shows row, null and distinct counts, plus min, max and average for numeric columns, and the most common values for text columns. The distinct count comes from ClickHouse’s uniq, so it is approximate on large tables.
Query Plans
The Explain button runs EXPLAIN indexes = 1 on the current statement and shows the plan as text. ClickHouse has no EXPLAIN ANALYZE, so Explain plans the statement without executing it.
You can also write EXPLAIN yourself. It returns one row per plan line:
EXPLAIN indexes = 1
SELECT count() FROM events WHERE event_date >= today() - 7;Performance Analysis
Click Analyze in the results toolbar to check the current statement. data-peek reads the plan with EXPLAIN json = 1, indexes = 1 and flags a table read that skips few of the table’s granules. It also summarizes earlier runs of the same query shape from system.query_log over the last 7 days, and flags the query as slow when its p95 duration passes the threshold. Your query is not run again.
system.query_log is per node, so on a cluster only the runs on the connected node are counted, and a run from the last few seconds may not be logged yet. If your user cannot read system.query_log, the pruning check still runs. See Performance Analysis.
Cancel and Timeouts
Cancel stops the request and sends KILL QUERY for it, so the server stops the work too. The query timeout setting becomes ClickHouse’s max_execution_time, so the server ends a query that runs past it.
MCP Server
When an agent calls run_query on a ClickHouse connection, data-peek sends the query with the readonly = 1 setting. ClickHouse then refuses writes and table functions such as url(). See MCP Server.
Troubleshooting
Connection Refused or a Native-Port Error
- Check that you are using the HTTP port:
8123, or8443with SSL - Verify the server is reachable from your network
- Check firewall rules allow connections on that port
Authentication Failures
- Verify your username and password. A fresh ClickHouse install has a user named
default. - Ensure the user can read the database you entered