Clickhouse
Tools to query and explore a ClickHouse database
1.0.2ClickHouse Toolkit
Arcade's ClickHouse toolkit connects agents to a ClickHouse database, enabling read-only querying and full schema/metadata exploration.
Capabilities
- Database & schema discovery: List all databases and retrieve default schema info (note: ClickHouse has no schema hierarchy like PostgreSQL).
- Table discovery: Enumerate all tables in the connected database — required before any query or schema lookup.
- Schema inspection: Fetch the structure of a specific table (columns, types, keys) before constructing queries.
- Read-only querying: Execute
SELECTstatements with support for joins, filters, ordering, pagination, and aggregation;INSERT,UPDATE,DELETE, and DDL are blocked.
Secrets
CLICKHOUSE_DATABASE_CONNECTION_STRING
A full connection string that encodes everything needed to reach your ClickHouse instance: host, port, database name, username, and password. The exact format depends on your driver or SDK, but typically follows the pattern clickhouse://[user]:[password]@[host]:[port]/[database] (or an HTTP DSN such as http://user:password@host:8123/database). Obtain these credentials from wherever your ClickHouse cluster is managed:
- ClickHouse Cloud: Open the ClickHouse Cloud console, select your service, and go to Connect → Connect String to copy a ready-made DSN. Your username is usually
default; the password is set when the service is created (or can be reset under Security). - Self-hosted: Use the host/port you configured in
config.xmlorusers.xml, along with the credentials defined there. If using TLS, append the appropriate query parameters (e.g.,?secure=true&skip_verify=false).
For guidance on storing secrets in Arcade, see the Arcade secrets docs or manage them directly at https://api.arcade.dev/dashboard/auth/secrets.
Available tools(5)
| Tool name | Description | Secrets | |
|---|---|---|---|
Discover all the databases in the ClickHouse database. | 1 | ||
Discover all the schemas in the ClickHouse database.
Note: ClickHouse doesn't have schemas like PostgreSQL, so this returns a default schema name. | 1 | ||
Discover all the tables in the ClickHouse database when the list of tables is not known.
ALWAYS use this tool before any other tool that requires a table name. | 1 | ||
You have a connection to a ClickHouse database.
Execute a SELECT query and return the results against the ClickHouse database.
No other queries (INSERT, UPDATE, DELETE, etc.) are allowed.
ONLY use this tool if you have already loaded the schema of the tables you need to query.
The final query will be constructed as follows:
SELECT {select_query_part} FROM {from_clause} JOIN {join_clause}
WHERE {where_clause} HAVING {having_clause}
ORDER BY {order_by_clause} LIMIT {limit} OFFSET {offset}
When running queries, follow these rules which will help avoid errors:
* Never "select *" from a table. Always select the columns you need.
* Always order your results. Use the most important columns or the primary key if you're unsure.
* Always use case-insensitive queries to match strings in the query.
* Always trim strings in the query.
* Prefer LIKE queries over direct string matches or regex queries.
* Only join on columns that are indexed or the primary key. Do not join on arbitrary columns.
* ClickHouse is case-sensitive, so be careful with table and column names. | 1 | ||
Get the schema/structure of a ClickHouse table in the ClickHouse database
when the schema is not known, and the name of the table is provided.
This tool should ALWAYS be used before executing any query.
All tables in the query must be discovered first,
so that their exact names are known. | 1 |