Skip to content

Commit 405288a

Browse files
evantahlerevantahler
committed
Add Clickhouse docs
1 parent a84f764 commit 405288a

14 files changed

Lines changed: 393 additions & 1 deletion

‎pages/toolkits/databases/clickhouse.mdx‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Clickhouse
2+
3+
import ToolInfo from "@/components/ToolInfo";
4+
import Badges from "@/components/Badges";
5+
import TabbedCodeBlock from "@/components/TabbedCodeBlock";
6+
import TableOfContents from "@/components/TableOfContents";
7+
import ToolFooter from "@/components/ToolFooter";
8+
9+
<ToolInfo
10+
description="Enable agents to interact with Clickhouse databases (read only)."
11+
author="Arcade"
12+
codeLink="https://github.com/ArcadeAI/arcade-ai/tree/main/toolkits/clickhouse"
13+
authType="database connection string"
14+
versions={["0.1.0"]}
15+
/>
16+
17+
<Badges repo="arcadeai/arcade-clickhouse" />
18+
19+
The Arcade Clickhouse toolkit provides a pre-built set of tools for interacting with Clickhouse databases in a read-only manner. This toolkit enables agents to discover database schemas, explore table structures, and execute SELECT queries safely. This toolkit is a companion to the blog post [Designing SQL Tools for AI Agents](https://blog.arcade.dev/sql-tools-ai-agents-security).
20+
21+
<Note>
22+
This toolkit is meant to be an example of how to build a toolkit for a database, and is not intended to be used in production. For production use, we recommend forking this repository and building your own toolkit with use-case specific tools.
23+
</Note>
24+
25+
## Key Features
26+
27+
This toolkit demonstrates several important concepts for LLM-powered database interactions:
28+
29+
* **Schema Discovery**: Automatically discover available database schemas
30+
* **Table Exploration**: Find all tables within a specific schema
31+
* **Schema Inspection**: Get detailed column information including data types, primary keys, and indexes
32+
* **Safe Query Execution**: Execute SELECT queries with built-in safety measures
33+
* **Connection Pooling**: Reuse database connections efficiently
34+
* **Read-Only Access**: Enforce read-only access to prevent data modification
35+
* **Row Limits**: Automatically limit query results to prevent overwhelming responses
36+
37+
## Available Tools
38+
39+
<TableOfContents
40+
headers={["Tool Name", "Description"]}
41+
data={
42+
[
43+
['Clickhouse.DiscoverDatabases', "Discover all databases in a Clickhouse database."],
44+
['Clickhouse.DiscoverSchemas', "Discover all schemas in a Clickhouse database."],
45+
['Clickhouse.DiscoverTables', "Discover all tables in a specific schema."],
46+
['Clickhouse.GetTableSchema', "Get the detailed schema of a specific table."],
47+
['Clickhouse.ExecuteSelectQuery', "Execute a SELECT query with comprehensive clause support."],
48+
]
49+
}
50+
/>
51+
52+
Note that all tools require the `CLICKHOUSE_DATABASE_CONNECTION_STRING` secret to be set.
53+
54+
## Clickhouse.DiscoverDatabases
55+
56+
Discover all databases in a Clickhouse database. This tool returns a list of all available databases.
57+
58+
<TabbedCodeBlock
59+
tabs={[
60+
{
61+
label: "Call the Tool",
62+
content: {
63+
Python: [
64+
"/examples/integrations/toolkits/clickhouse/discover_databases_example_call_tool.py",
65+
],
66+
JavaScript: ["/examples/integrations/toolkits/clickhouse/discover_databases_example_call_tool.js"],
67+
},
68+
}
69+
]}
70+
/>
71+
72+
## Clickhouse.DiscoverSchemas
73+
74+
Discover all schemas in a Clickhouse database. This tool returns a list of all available schemas, excluding the `information_schema` for security.
75+
76+
<TabbedCodeBlock
77+
tabs={[
78+
{
79+
label: "Call the Tool",
80+
content: {
81+
Python: [
82+
"/examples/integrations/toolkits/clickhouse/discover_schemas_example_call_tool.py",
83+
],
84+
JavaScript: ["/examples/integrations/toolkits/clickhouse/discover_schemas_example_call_tool.js"],
85+
},
86+
}
87+
]}
88+
/>
89+
90+
## Clickhouse.DiscoverTables
91+
92+
Discover all tables in a specific schema. This tool should be used before any other tool that requires a table name.
93+
94+
**Parameters:**
95+
- `schema_name` (str): The database schema to discover tables in (default: "public")
96+
97+
<TabbedCodeBlock
98+
tabs={[
99+
{
100+
label: "Call the Tool",
101+
content: {
102+
Python: [
103+
"/examples/integrations/toolkits/clickhouse/discover_tables_example_call_tool.py",
104+
],
105+
JavaScript: ["/examples/integrations/toolkits/clickhouse/discover_tables_example_call_tool.js"],
106+
},
107+
}
108+
]}
109+
/>
110+
111+
## Clickhouse.GetTableSchema
112+
113+
Get the detailed schema of a specific table. This tool provides column information including data types, primary key indicators, and index information. Always use this tool before executing any query.
114+
115+
**Parameters:**
116+
- `schema_name` (str): The database schema containing the table
117+
- `table_name` (str): The name of the table to inspect
118+
119+
<TabbedCodeBlock
120+
tabs={[
121+
{
122+
label: "Call the Tool",
123+
content: {
124+
Python: [
125+
"/examples/integrations/toolkits/clickhouse/get_table_schema_example_call_tool.py",
126+
],
127+
JavaScript: ["/examples/integrations/toolkits/clickhouse/get_table_schema_example_call_tool.js"],
128+
},
129+
}
130+
]}
131+
/>
132+
133+
## Clickhouse.ExecuteSelectQuery
134+
135+
Execute a SELECT query with comprehensive clause support. This tool allows you to build complex queries using individual clauses while maintaining safety and performance.
136+
137+
**Parameters:**
138+
- `select_clause` (str): Columns to select (without SELECT keyword)
139+
- `from_clause` (str): Table(s) to query from (without FROM keyword)
140+
- `limit` (int): Maximum rows to return (default: 100)
141+
- `offset` (int): Number of rows to skip (default: 0)
142+
- `join_clause` (str, optional): JOIN conditions (without JOIN keyword)
143+
- `where_clause` (str, optional): WHERE conditions (without WHERE keyword)
144+
- `having_clause` (str, optional): HAVING conditions (without HAVING keyword)
145+
- `group_by_clause` (str, optional): GROUP BY columns (without GROUP BY keyword)
146+
- `order_by_clause` (str, optional): ORDER BY columns (without ORDER BY keyword)
147+
- `with_clause` (str, optional): WITH clause for CTEs (without WITH keyword)
148+
149+
**Query Construction:**
150+
The final query is constructed as:
151+
```sql
152+
SELECT {select_clause} FROM {from_clause}
153+
JOIN {join_clause}
154+
WHERE {where_clause}
155+
HAVING {having_clause}
156+
GROUP BY {group_by_clause}
157+
ORDER BY {order_by_clause}
158+
LIMIT {limit} OFFSET {offset}
159+
```
160+
161+
**Best Practices:**
162+
- Always use `discover_tables` and `get_table_schema` before executing queries
163+
- Never use "SELECT *" - always specify the columns you need
164+
- Order results by primary keys or important columns
165+
- Use case-insensitive string matching
166+
- Trim strings in queries
167+
- Prefer LIKE queries over exact matches or regex
168+
- Only join on indexed columns or primary keys
169+
170+
<TabbedCodeBlock
171+
tabs={[
172+
{
173+
label: "Call the Tool",
174+
content: {
175+
Python: [
176+
"/examples/integrations/toolkits/clickhouse/execute_select_query_example_call_tool.py",
177+
],
178+
JavaScript: ["/examples/integrations/toolkits/clickhouse/execute_select_query_example_call_tool.js"],
179+
},
180+
}
181+
]}
182+
/>
183+
184+
## Usage Workflow
185+
186+
For optimal results, follow this workflow when using the Clickhouse toolkit:
187+
188+
1. **Discover Schemas**: Use `discover_schemas` to see available schemas
189+
2. **Discover Tables**: Use `discover_tables` with your target schema
190+
3. **Get Table Schema**: Use `get_table_schema` for each table you plan to query
191+
4. **Execute Query**: Use `execute_select_query` with the schema information
192+
193+
This workflow ensures your agent has complete information about the database structure before attempting queries, reducing errors and improving query performance.
194+
195+
<ToolFooter />

‎pages/toolkits/databases/postgres.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ This toolkit demonstrates several important concepts for LLM-powered database in
4848
}
4949
/>
5050

51-
Note that all tools require the `DATABASE_CONNECTION_STRING` secret to be set.
51+
Note that all tools require the `POSTGRES_DATABASE_CONNECTION_STRING` secret to be set.
5252

5353
## Postgres.DiscoverSchemas
5454

‎public/examples/integrations/toolkits/clickhouse/discover_databases_example_call_tool.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import { Arcade } from "@arcadeai/arcadejs";
2+
3+
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
4+
5+
const USER_ID = "{arcade_user_id}";
6+
const TOOL_NAME = "Clickhouse.DiscoverSchemas";
7+
8+
const toolInput = {};
9+
10+
const response = await client.tools.execute({
11+
tool_name: TOOL_NAME,
12+
input: toolInput,
13+
user_id: USER_ID,
14+
});
15+
16+
console.log(response.output.value);

‎public/examples/integrations/toolkits/clickhouse/discover_databases_example_call_tool.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
from arcadepy import Arcade
2+
3+
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable
4+
5+
TOOL_NAME = "Clickhouse.DiscoverSchemas"
6+
7+
user_id = "{arcade_user_id}"
8+
9+
tool_input = {}
10+
11+
response = client.tools.execute(
12+
tool_name=TOOL_NAME,
13+
input=tool_input,
14+
user_id=user_id,
15+
)
16+
17+
print(response.output.value)

‎public/examples/integrations/toolkits/clickhouse/discover_schemas_example_call_tool.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import { Arcade } from "@arcadeai/arcadejs";
2+
3+
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
4+
5+
const USER_ID = "{arcade_user_id}";
6+
const TOOL_NAME = "Clickhouse.DiscoverSchemas";
7+
8+
const toolInput = {};
9+
10+
const response = await client.tools.execute({
11+
tool_name: TOOL_NAME,
12+
input: toolInput,
13+
user_id: USER_ID,
14+
});
15+
16+
console.log(response.output.value);

‎public/examples/integrations/toolkits/clickhouse/discover_schemas_example_call_tool.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
from arcadepy import Arcade
2+
3+
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable
4+
5+
TOOL_NAME = "Clickhouse.DiscoverSchemas"
6+
7+
user_id = "{arcade_user_id}"
8+
9+
tool_input = {}
10+
11+
response = client.tools.execute(
12+
tool_name=TOOL_NAME,
13+
input=tool_input,
14+
user_id=user_id,
15+
)
16+
17+
print(response.output.value)

‎public/examples/integrations/toolkits/clickhouse/discover_tables_example_call_tool.js‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import { Arcade } from "@arcadeai/arcadejs";
2+
3+
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
4+
5+
const USER_ID = "{arcade_user_id}";
6+
const TOOL_NAME = "Clickhouse.DiscoverTables";
7+
8+
const toolInput = {
9+
schema_name: "public",
10+
};
11+
12+
const response = await client.tools.execute({
13+
tool_name: TOOL_NAME,
14+
input: toolInput,
15+
user_id: USER_ID,
16+
});
17+
18+
console.log(response.output.value);

‎public/examples/integrations/toolkits/clickhouse/discover_tables_example_call_tool.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
from arcadepy import Arcade
2+
3+
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable
4+
5+
TOOL_NAME = "Clickhouse.DiscoverTables"
6+
7+
user_id = "{arcade_user_id}"
8+
9+
tool_input = {
10+
"schema_name": "public",
11+
}
12+
13+
response = client.tools.execute(
14+
tool_name=TOOL_NAME,
15+
input=tool_input,
16+
user_id=user_id,
17+
)
18+
19+
print(response.output.value)

‎public/examples/integrations/toolkits/clickhouse/execute_select_query_example_call_tool.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import { Arcade } from "@arcadeai/arcadejs";
2+
3+
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
4+
5+
const USER_ID = "{arcade_user_id}";
6+
const TOOL_NAME = "Clickhouse.ExecuteSelectQuery";
7+
8+
const toolInput = {
9+
select_clause: "id, name, email",
10+
from_clause: "users",
11+
where_clause: "active = true",
12+
order_by_clause: "name",
13+
limit: 10,
14+
};
15+
16+
const response = await client.tools.execute({
17+
tool_name: TOOL_NAME,
18+
input: toolInput,
19+
user_id: USER_ID,
20+
});
21+
22+
console.log(response.output.value);

‎public/examples/integrations/toolkits/clickhouse/execute_select_query_example_call_tool.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
from arcadepy import Arcade
2+
3+
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable
4+
5+
TOOL_NAME = "Clickhouse.ExecuteSelectQuery"
6+
7+
user_id = "{arcade_user_id}"
8+
9+
tool_input = {
10+
"select_clause": "id, name, email",
11+
"from_clause": "users",
12+
"where_clause": "active = true",
13+
"order_by_clause": "name",
14+
"limit": 10,
15+
}
16+
17+
response = client.tools.execute(
18+
tool_name=TOOL_NAME,
19+
input=tool_input,
20+
user_id=user_id,
21+
)
22+
23+
print(response.output.value)

0 commit comments

Comments
 (0)