Clickhouse
Tools to query and explore a ClickHouse database
1.0.2ClickHouse Toolkit
Arcade toolkit for querying and exploring a ClickHouse database — enables schema discovery, table inspection, and read-only SQL execution.
Capabilities
- Database & schema discovery: List all databases and retrieve default schema information from a connected ClickHouse instance.
- Table discovery: Enumerate all tables in the database; required before executing any query so exact table names are known.
- Schema inspection: Retrieve the full column structure of a specific table prior to querying.
- Read-only query execution: Run parameterized
SELECTqueries with support for joins, filtering, ordering, pagination, and aggregation — no write operations permitted.
Secrets
CLICKHOUSE_DATABASE_CONNECTION_STRING — The full connection string used to authenticate and connect to your ClickHouse instance. This is a password-type secret containing credentials and connection details in a single string.
The connection string typically follows the format: clickhouse://[user]:[password]@[host]:[port]/[database] (or the HTTP variant http://...). To obtain it:
- Log in to your ClickHouse Cloud console or your self-hosted ClickHouse admin interface.
- Locate your cluster's hostname, native TCP port (default
9000) or HTTP port (default8123), and the target database name. - Use a service account or a dedicated user with at minimum
SELECTprivileges on the target database — avoid using the default admin user in production. - Assemble the connection string from those values and store it as a secret in Arcade.
For self-hosted deployments, refer to your ClickHouse instance configuration. For ClickHouse Cloud, connection details are available in the Connect tab of your service in the ClickHouse Cloud console.
See Arcade secrets documentation for how to register secrets, 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 |