> **chdb-datastore** — chapter 1 of 11 in [ClickHouse/agent-skills](https://skillsdocs.com/ClickHouse/agent-skills).
>
> Book (all chapters, one file): https://skillsdocs.com/ClickHouse/agent-skills.md
> Machine manifest: https://skillsdocs.com/ClickHouse/agent-skills/.well-known/agent-skills/index.json
> Install the book: `npx skills add ClickHouse/agent-skills`
> Upstream: https://github.com/ClickHouse/agent-skills/blob/main/skills/chdb-datastore/SKILL.md @ `main`
> Raw bytes, no header: https://raw.githubusercontent.com/ClickHouse/agent-skills/main/skills/chdb-datastore/SKILL.md
> Base for relative paths: https://raw.githubusercontent.com/ClickHouse/agent-skills/main/skills/chdb-datastore/
> Licence: Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html
>
> Bundled files (6), referenced from this skill's directory:
>   - `examples/examples.md` — https://raw.githubusercontent.com/ClickHouse/agent-skills/main/skills/chdb-datastore/examples/examples.md
>   - `metadata.json` — https://raw.githubusercontent.com/ClickHouse/agent-skills/main/skills/chdb-datastore/metadata.json
>   - `README.md` — https://raw.githubusercontent.com/ClickHouse/agent-skills/main/skills/chdb-datastore/README.md
>   - `references/api-reference.md` — https://raw.githubusercontent.com/ClickHouse/agent-skills/main/skills/chdb-datastore/references/api-reference.md
>   - `references/connectors.md` — https://raw.githubusercontent.com/ClickHouse/agent-skills/main/skills/chdb-datastore/references/connectors.md
>   - `scripts/verify_install.py` — https://raw.githubusercontent.com/ClickHouse/agent-skills/main/skills/chdb-datastore/scripts/verify_install.py
>
> Content © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: chdb-datastore
description: >-
  Use when the user has tabular data (pandas DataFrame, parquet, csv,
  Arrow, json) and wants to filter, group, aggregate, join, or speed
  up slow pandas. Provides chDB DataStore — same pandas API,
  ClickHouse engine underneath. Also handles reading from S3, MySQL,
  PostgreSQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake as
  DataFrames and joining across sources.
  TRIGGER when: user mentions DataFrame, parquet, csv, "fast pandas",
  "speed up pandas", or cross-source DataFrame joins; user imports
  `chdb.datastore` or `from datastore import DataStore`.
  SKIP this skill for raw SQL syntax (use chdb-sql instead),
  ClickHouse server administration, or non-Python DataStore API work.
license: Apache-2.0
compatibility: Requires Python 3.9+, macOS or Linux. pip install chdb.
metadata:
  author: chdb-io
  version: "4.1"
  homepage: https://clickhouse.com/docs/chdb
---

# chdb DataStore — It's Just Faster Pandas

## The Key Insight

```python
# Change this:
import pandas as pd
# To this:
import chdb.datastore as pd
# Everything else stays the same.
```

DataStore is a **lazy, ClickHouse-backed pandas replacement**. Your existing pandas code works unchanged — but operations compile to optimized SQL and execute only when results are needed (e.g., `print()`, `len()`, iteration).

```bash
pip install chdb
```

## Decision Tree: Pick the Right Approach

```
1. "I have a file/database and want to analyze it with pandas"
   → DataStore.from_file() / from_mysql() / from_s3() etc.
   → See references/connectors.md

2. "I need to join data from different sources"
   → Create DataStores from each source, use .join()
   → See examples/examples.md #3-5

3. "My pandas code is too slow"
   → import chdb.datastore as pd — change one line, keep the rest

4. "I need raw SQL queries"
   → Use the chdb-sql skill instead
```

## Connect to Any Data Source — One Pattern

```python
from datastore import DataStore

# Local file (auto-detects .parquet, .csv, .json, .arrow, .orc, .avro, .tsv, .xml)
ds = DataStore.from_file("sales.parquet")

# Database
ds = DataStore.from_mysql(host="db:3306", database="shop", table="orders", user="root", password="pass")

# Cloud storage
ds = DataStore.from_s3("s3://bucket/data.parquet", nosign=True)

# URI shorthand — auto-detects source type
ds = DataStore.uri("mysql://root:pass@db:3306/shop/orders")
```

All 16+ sources and URI schemes → [connectors.md](references/connectors.md)

## After Connecting — Full Pandas API

```python
result = ds[ds["age"] > 25]                                          # filter
result = ds[["name", "city"]]                                        # select columns
result = ds.sort_values("revenue", ascending=False)                  # sort
result = ds.groupby("dept")["salary"].mean()                         # groupby
result = ds.assign(margin=lambda x: x["profit"] / x["revenue"])     # computed column
ds["name"].str.upper()                                               # string accessor
ds["date"].dt.year                                                   # datetime accessor
result = ds1.join(ds2, on="id")                                      # join
result = ds.head(10)                                                 # preview
print(ds.to_sql())                                                   # see generated SQL
```

209 DataFrame methods supported. Full API → [api-reference.md](references/api-reference.md)

## Cross-Source Join — The Killer Feature

```python
from datastore import DataStore

customers = DataStore.from_mysql(host="db:3306", database="crm", table="customers", user="root", password="pass")
orders = DataStore.from_file("orders.parquet")

result = (orders
    .join(customers, left_on="customer_id", right_on="id")
    .groupby("country")
    .agg({"amount": "sum", "rating": "mean"})
    .sort_values("sum", ascending=False))
print(result)
```

More join examples → [examples.md](examples/examples.md)

## Writing Data

```python
source = DataStore.from_mysql(host="db:3306", database="shop", table="orders", user="root", password="pass")
target = DataStore("file", path="summary.parquet", format="Parquet")

target.insert_into("category", "total", "count").select_from(
    source.groupby("category").select("category", "sum(amount) AS total", "count() AS count")
).execute()
```

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `ImportError: No module named 'chdb'` | `pip install chdb` |
| `ImportError: cannot import 'DataStore'` | Use `from datastore import DataStore` or `from chdb.datastore import DataStore` |
| Database connection timeout | Include port in host: `host="db:3306"` not `host="db"` |
| Join returns empty result | Check key types match (both int or both string); use `.to_sql()` to inspect |
| Unexpected results | Call `ds.to_sql()` to see the generated SQL and debug |
| Environment check | Run `python scripts/verify_install.py` (from skill directory) |

## References

- [API Reference](references/api-reference.md) — Full DataStore method signatures
- [Connectors](references/connectors.md) — All 16+ data source connection methods
- [Examples](examples/examples.md) — 10+ runnable examples with expected output
- [Verify Install](scripts/verify_install.py) — Environment verification script
- [Official Docs](https://clickhouse.com/docs/chdb)

> Note: This skill teaches how to *use* chdb DataStore.
> For raw SQL queries, use the `chdb-sql` skill.
> For contributing to chdb source code, see CLAUDE.md in the project root.