Clickhouse
Tools to query and explore a ClickHouse database
1.0.1ClickHouse Toolkit
Arcade's ClickHouse toolkit connects agents to a ClickHouse database, enabling schema discovery and read-only querying without any OAuth or API key flow.
Capabilities
- Database & table discovery: List all databases, enumerate tables, and retrieve table schemas before constructing queries.
- Read-only query execution: Execute
SELECTstatements with structured clause inputs (select, from, join, where, having, order by, limit, offset); no write operations are permitted. - Schema-aware query guidance: Tools enforce a discovery-first workflow — tables and schemas must be resolved before queries run, reducing runtime errors.
- ClickHouse-specific handling: Schema discovery returns a default schema name (ClickHouse has no PostgreSQL-style schemas); queries are expected to be case-sensitive for identifiers and case-insensitive for string matching.
Secrets
CLICKHOUSE_DATABASE_CONNECTION_STRING — The full connection string used to authenticate and connect to your ClickHouse instance. This is a password-type secret that encodes your host, port, database name, username, and password in a single URI. The typical format is clickhouse://[user]:[password]@[host]:[port]/[database] (or the clickhouse+native:// variant depending on the driver). Obtain this from your ClickHouse deployment:
- ClickHouse Cloud: Log in to the ClickHouse Cloud console, open your service, and navigate to Connect → Connection details to find the hostname, port, and credentials.
- Self-hosted: Use the host and port configured in your
config.xmlorusers.xml, along with the credentials of the database user you want Arcade to use. Create a dedicated read-only user withSELECT-only privileges to match the toolkit's read-only constraint.
For details on storing secrets in Arcade, see the Arcade secrets guide. You can manage stored secrets 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 |