LlamaIndex Tools Integration: chDB
Give agents analytical SQL over local and remote data with chDB, the in-process ClickHouse engine. The engine runs inside the Python process — no server to start, no connection string, no credentials — and queries local files (Parquet/CSV/JSON), object storage, and remote databases through ClickHouse table functions.
Installation
pip install llama-index-tools-chdb
Usage
from llama_index.tools.chdb import ChDBToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
spec = ChDBToolSpec(attachments={"events": "data/events.parquet"})
agent = FunctionAgent(
tools=spec.to_tool_list(),
llm=OpenAI(model="gpt-4o-mini"),
)
print(await agent.run("What are the top 5 event types by count?"))
The spec exposes seven tools, mirroring the tool surface chDB ships for agents (chdb.agents):
run_select_query— read-only ClickHouse SQL with{name:Type}parameter binding (full dialect: 1000+ functions, window functions, arrays, JSON)list_databases,list_tables,describe_table,get_sample_data,list_functions— schema discovery, including describing table-function expressions such ass3('https://bucket/f.parquet','Parquet')attach_file— register a local file as a named table (writable sessions only; on read-only sessions declare files via theattachmentsargument instead)
Every tool has an async twin (arun_select_query, …) backed by the engine's native async path, so to_tool_list() produces tools usable in both sync and async agents.
Safety defaults
- Read-only by default. Sessions are locked with the ClickHouse
readonly=2setting:INSERT/CREATE/ALTER/DROPare rejected by the engine (not by prompt), whileSELECTand thefile()/s3()/url()table functions keep working. Passread_only=Falsefor a writable session. - Capped results.
max_rows(default 1000) andmax_bytes(default 1 MB) bound every payload; truncated results carry atruncatedflag the agent can react to.max_execution_timeadds an engine-side wall-clock limit. - Optional source allowlist. With
file_allowlist=["/data/"], file-like sources may only read under the listed prefixes and DSN-based sources (postgresql(),mysql(),remote(), …) are refused. - Errors go to the model, not the run. Every call returns a JSON envelope —
{"ok": true, "result": …}or{"ok": false, "error": {"code", "type", "message"}}— so a bad query becomes feedback the agent corrects instead of an exception.
Querying remote data
spec = ChDBToolSpec()
spec.run_select_query(
"SELECT status, count() FROM url('https://example.com/logs.ndjson', 'JSONEachRow') GROUP BY status"
)
s3(...), postgresql(...), mysql(...), mongodb(...), remoteSecure(...), iceberg(...), and deltaLake(...) work the same way, subject to the read-only lock and allowlist.
Sharing and lifecycle
To control the engine's lifecycle yourself — or to share one session across several specs — create the engine explicitly and inject it:
from chdb.agents import ChDBTool
from llama_index.tools.chdb import ChDBToolSpec
engine = ChDBTool("analytics_dir", read_only=False)
spec = ChDBToolSpec(engine=engine)
...
engine.close()
spec.close() closes only an engine the spec created itself.
This package is maintained by the chDB team.
Metadata
Release files for llama-index-tools-chdb 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| llama_index_tools_chdb-0.1.0.tar.gz | 10.6 kB | Without provenance | Details for llama_index_tools_chdb-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| llama_index_tools_chdb-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for llama_index_tools_chdb-0.1.0-py3-none-any.whl |
Total release size: 21.3 kB
Release files / llama_index_tools_chdb-0.1.0.tar.gz
| Download URL | llama_index_tools_chdb-0.1.0.tar.gz |
|---|---|
| Size | 10.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bbb6a95b7af53c53e66c28eb0bda44d1feeb0b153f253739216ebcc1ac6da301
|
|
BLAKE2b-256 checksum How to use checksums |
8dc53f65a65dd5a6299ed6e785e4c370427d0a19480afa8632dc9241a8fa89cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / llama_index_tools_chdb-0.1.0-py3-none-any.whl
| Download URL | llama_index_tools_chdb-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3b1863ba684189042380ce83975ca2442693e9e4f572acf738cab467f3468399
|
|
BLAKE2b-256 checksum How to use checksums |
3cb4ccbc75ecbd5e4e83a0ff2ee98b1861c479bd1df2257d9da04e8d7127210e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for llama-index-tools-chdb 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.