Clickhouse
Tools to query and explore a ClickHouse database
2.0.1The Clickhouse toolkit for Arcade connects to a ClickHouse database and enables agents to explore its structure and query its data via a structured, read-only interface.
Capabilities
- Schema discovery: List all databases, schemas (returns a default placeholder, as ClickHouse lacks PostgreSQL-style schemas), tables, and column-level structure before executing any query.
- Read-only querying: Execute
SELECTstatements with explicit support for filtering, joining (on indexed/primary-key columns), ordering, pagination (LIMIT/OFFSET), and aggregation (HAVING). Write operations (INSERT,UPDATE,DELETE) are not permitted. - Query safety guardrails: Built-in rules enforce column-explicit selects, case-insensitive string matching, string trimming,
LIKE-based matching, and indexed-only joins to reduce runtime errors.
Secrets
CLICKHOUSE_DATABASE_CONNECTION_STRING
A ClickHouse connection string that encodes the host, port, database name, username, and password needed to reach your ClickHouse instance. The exact format depends on your client driver (e.g., clickhouse://user:password@host:port/database for HTTP-based clients). Obtain the values from your ClickHouse deployment:
- ClickHouse Cloud: Navigate to your service in the ClickHouse Cloud console, click Connect, and copy the connection details shown for your preferred client.
- Self-hosted: Use the host/port configured in your
config.xml(default HTTP port8123, native port9000), along with the credentials of a user that has at minimumSELECTandSHOWprivileges on the target database.
Ensure the user account has read-only access restricted to the intended database to limit exposure.
For guidance on storing secrets in Arcade, see the Arcade secrets documentation. You can manage secret values at https://api.arcade.dev/dashboard/auth/secrets.
Available tools(5)
| Tool name | Description | Secrets | |
|---|---|---|---|
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 | ||
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 |