内容
# 数据宪章
> 在本地一站式探索所有数据，受合约治理的数据探索，由DuckDB提供支持
[](https://pypi.org/project/datacharter/)
[](https://pypi.org/project/datacharter/)
[](LICENSE)
受合约治理的本地数据探索，**由DuckDB提供支持**。
将数据源定义为数据合约
（兼容[ODCS](https://bitol-io.github.io/open-data-contract-standard/)的YAML），
通过DuckDB的SQL联邦引擎查询数据源，支持实时源推送，
并在本地Web UI中探索 - 带有实时预览的SQL编辑器、自动图表、
性能分析。每个答案都显示其读取的源列；用自然语言提问或
通过[MCP](docs/mcp.md)将整个过程提供给AI代理，
并对模型隐藏敏感信息 — 所有操作都在您的机器上进行。
## 功能
- **拖放文件，立即查询**。将CSV、Parquet或JSON文件拖放到窗口中，即可立即对其运行SQL查询 — 无需导入，无需模式设置。
- **跨源连接 — 无需数据管道**。在单个SQL语句中查询和连接Postgres表、Parquet文件和Snowflake表 — 无需ETL，无需将所有数据复制到数据仓库中。
- **连接所有数据**。Postgres、MySQL、SQLite、SQL Server、BigQuery、Snowflake、S3/GCS/Azure上的文件以及Iceberg/Delta表 — 所有都通过一个引擎提供。
- **边写边看结果**。在编写SQL查询时实时预览结果，一键自动生成图表，并提供性能分析面板（缺失值、分布、离群点）— 无需单独的BI工具。
- **用自然语言提问（可选）**。将问题转化为SQL查询和答案，使用内置代理 — 您可以自带模型，或完全在本地运行模型，无需API密钥。
- **保护敏感数据**。标记PII列一次；代理和任何连接的AI看到的都是屏蔽的值（`•••`），而您在本地看到的是真实数据。切换**代理视图**，以查看模型看到的内容。
- **设计安全**。引擎在设计上仅支持读取操作 — 任何查询都无法写入、删除或触摸文件系统 — 因此将AI（或同事）指向您的真实数据库不会造成损害。
- **安全地指向AI工具**。受管的MCP服务器向Cursor、Cline或您的代理公开只读、PII屏蔽的查询工具。
- **信任每个答案**。每个结果都显示其读取的源列 — 因此您始终知道数字的来源。
- **保存、重用、导出**。将结果快照为可重用的本地表；导出为CSV、Parquet、JSON或XLSX。
- **可自动化的治理**。在CI中捕获模式/PII漂移，自动检测PII列，跨源差异，并定义认证指标 — 从命令行。
**状态：预发布**。V1版本正在开发中。
## 快速开始
```sh
# 在生成的演示数据上立即试用 — 无需安装，无需配置：
uvx datacharter serve # 需要 `uv` → https://astral.sh/uv
# → 在 http://127.0.0.1:8321 提供服务（在浏览器中打开）
# 或安装它：
pip install datacharter # Python 3.11+
# 启动您自己的工作区：
datacharter init # 搭建 charter.yaml、queries/、.env.example
# → 添加一个源：编辑 charter.yaml，或在UI中使用“源”面板
datacharter serve # → http://127.0.0.1:8321
```
然后，一旦它运行，**将CSV、Parquet或JSON文件拖放到窗口中**，即可立即查询 — 无需配置。
**可选的自然语言代理** — 指向任何OpenAI兼容的端点：
```sh
export OPENAI_BASE_URL=... # 任何OpenAI兼容的API
export OPENAI_API_KEY=...
datacharter serve
```
… 或运行**完全本地** — 无需API密钥，数据不会离开您的机器（需要
[Ollama](https://ollama.com)）：
```sh
ollama pull qwen3:8b # 一次
datacharter serve --local # 默认qwen3:8b（--model更改）
```
## 为什么选择数据宪章
- **您的合约是目录**。`charter.yaml`描述源、表和PII字段 — 与您的数据团队已经编写的相同合约规范，因此无需维护单独的元数据存储。
- **真正的联邦，不只是共享连接**。筛选器和投影被推送到每个源 — 即使跨源连接，每个腿都在其数据所在的位置进行筛选。（Snowflake通过连接器提取，`datacharter[snowflake]`，并将筛选器推送到提取中。）
- **本地优先**。一个进程，您的机器，无云依赖。可选的 `--local` 代理通过Ollama运行小型开放模型 — 无需API密钥，数据不会离开您的机器。
- **工作区是一个目录**。`charter.yaml` + `queries/*.sql` + `.env.example` — 提交它，克隆它，`datacharter serve`。您团队的整个探索环境作为存储库旅行；秘密和本地状态永远不会。
数据宪章管理并审计您的数据，而不仅仅是显示它。完整的命令集（`drift`、`scan`、`diff`、`metric`、`mcp`等）位于
[CLI参考](docs/cli.md)；安全模型位于[安全](docs/security.md)。
## 构建于
数据宪章建立在优秀的开源基础之上：
- **[DuckDB](https://duckdb.org)** — 我们核心的分析引擎：联合查询（`ATTACH`）、文件格式、Iceberg/Delta、加密、自动补全。
- **[开放数据合约标准](https://bitol-io.github.io/open-data-contract-standard/)** /
[datacontract.com](https://datacontract-specification.com/) — `charter.yaml`所使用的合约格式。
- **[模型上下文协议](https://modelcontextprotocol.io)** — `datacharter mcp`服务器与代理和MCP客户端所使用的开放协议。
- **[Vega-Lite](https://vega.github.io/vega-lite/)** — 声明式图表。
- **[Monaco编辑器](https://microsoft.github.io/monaco-editor/)** — SQL编辑器。
- **[TanStack Table & Virtual](https://tanstack.com/)** — 虚拟化结果网格。
- 以及Python和React生态系统 — FastAPI、pydantic、httpx、keyring和
ruamel.yaml在后端；React和Vite在前端。
测试使用 **[VidaiMock](https://github.com/vidaiUK/VidaiMock)** ，
一个Apache-2.0许可的mock LLM服务器，作为CI中的离线代理端点。
DuckDB是DuckDB基金会的商标。数据宪章是一个独立项目，不隶属于DuckDB基金会，也不获得其认可。
## 许可证
[Apache-2.0](LICENSE)
