使用说明

DataQL

Query any data file using SQL. One command, instant results.

Quick Start • Features • Installation • Usage • LLM Integration • Documentation

DataQL是在Go中开发的CLI工具，允许您使用SQL语句查询和操作数据文件。它通过自动类型推理将数据加载到DuckDB数据库（内存或基于文件）中，从而实现了针对分析查询优化的强大SQL操作。

为什么选择DataQL？

问题

处理数据文件总是很乏味。您可以编写一次性脚本，将所有内容加载到pandas中，或者复制粘贴到电子表格中。随着LLM进入工作流程，出现了一个新问题： 如何在不烧毁整个上下文窗口的情况下分析10MB CSV？

传统方法失败了：

将文件发送到LLM上下文：10MB CSV=约100000+代币。昂贵、缓慢，往往不可能。
写剧本：上下文切换，设置开销，非对话。
使用pandas/Excel：对人类来说很棒，对LLM自动化毫无用处。

解决方案

DataQL允许您使用SQL查询任何数据文件。一个命令，即时结果：

# Instead of sending 50,000 rows to an LLM...
dataql run -f sales.csv -q "SELECT region, SUM(revenue) FROM sales GROUP BY region"

# You get just what you need:
# region    | SUM(revenue)
# North     | 1,234,567
# South     | 987,654

为什么这很重要

场景	没有DataQL	有DataQL
使用LLM分析10MB CSV	~100000个代币（3美元以上）	~500个代币（0.01美元）
从S3查询数据	下载→ 脚本→ 解析	一个命令
加入CSV+JSON+数据库	自定义ETL管道	单个SQL查询
自动化数据报告	复杂的脚本	简单的CLI+cron
LLM数据分析	上下文溢出	无大小限制

关键利益

代币高效：LLM获取查询结果，而不是原始数据。代币使用量减少99%。
通用格式支持：CSV、JSON、JSONL、Parquet、Excel、XML、YAML、Avro、ORC——所有这些都可以用SQL查询（加上透明 .gz, .bz2, .xz 减压）。
任何数据源：本地文件、URL、S3、GCS、Azure、PostgreSQL、MySQL、MongoDB、DynamoDB和消息队列（Kafka、SQS-peek而不消费）。
LLM本地：内置MCP服务器，适用于Claude Code、Codex、opencode、Gemini。一 dataql setup 将它们全部连接起来。克劳德代码的自动激活技能。
独立和离线：一个嵌入了DuckDB引擎和每个驱动程序的二进制文件。没有运行时下载，没有外部服务——完全离线工作。也作为完整的Docker镜像发布。
熟悉语法如果你知道SQL，你就知道DataQL。包括类型推断、参数化查询、跨源连接和丰富的导出格式。

快速开始

# Install DataQL (also: `go install github.com/adrianolaselva/dataql@latest`,
# or `docker run --rm -v "$PWD":/data ghcr.io/adrianolaselva/dataql ...`)
curl -fsSL https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.sh | bash

# (Optional) wire DataQL into your AI agents (Claude Code, Codex, opencode).
# The install script already runs this for you.
dataql setup

# Query a CSV file
dataql run -f data.csv -q "SELECT * FROM data WHERE amount > 100"

# Query JSON from a URL
dataql run -f "https://api.example.com/data.json" -q "SELECT name, value FROM data"

# Query data from S3
dataql run -f "s3://bucket/data.parquet" -q "SELECT * FROM data LIMIT 10"

# Export results to JSON
dataql run -f data.csv -q "SELECT * FROM data" -e output.json -t json

# Interactive REPL mode
dataql run -f data.csv
# dataql> SELECT COUNT(*) FROM data;
# dataql> .tables
# dataql> .exit

特征

支持的文件格式：

CSV（带可配置分隔符）
JSON（数组或单个对象）
JSONL/NDJSON（换行符分隔的JSON）
可扩展标记语言
YAML
镶木地板
Excel（.xlsx、.xls）
阿夫罗
兽人

数据来源：

本地文件
HTTP/HTTPS URL
亚马逊S3
谷歌云存储
Azure Blob存储
标准输入（stdin）
消息队列——Kafka、Amazon SQS（在不消费的情况下查看）。RabbitMQ和Pulsar在路线图上。

数据库连接器：

PostgreSQL
MySQL
鸭数据库
MongoDB
DynamoDB

关键能力：

使用DuckDB语法执行SQL查询（OLAP优化）
导出到CSV、JSONL、JSON、Excel、Parquet、XML、YAML、， Markdown和HTML 表格
透明减压 .gz, .bz2, .xz 文件
参数化查询 (-p name=value)用于安全、可重用的脚本
describe 用于即时探索性统计的命令（min/max/mean/nulls/unique）
数据缓存 加快对同一源的重复查询
具有命令历史记录的交互式REPL模式(.tables, .schema, .exit)
进度条、并行多文件处理、自动嵌套JSON扁平化
在单个查询中连接来自多个源的数据

LLM集成：

用于Claude Code、Codex、opencode、Gemini的MCP服务器——一个 dataql setup 将它们全部配置
自动激活克劳德代码技能
AI助手的令牌高效数据处理

命令一览

命令	它的作用
`dataql run`	使用SQL查询任何文件/源（或打开REPL）
`dataql describe`	数据集列的探索性统计
`dataql cache`	检查和管理本地查询缓存
`dataql mcp serve`	为AI代理运行MCP服务器（stdio）
`dataql setup`	为Claude Code、Codex、opencode自动配置MCP服务器
`dataql skills`	安装/列出Claude Code的DataQL技能

跑 dataql <command> --help 完整的选项。

LLM集成

DataQL旨在与大型语言模型高效配合使用，使AI助手能够查询大型数据集，而无需将整个文件加载到上下文中。

# One command wires up every agent on your machine (Claude Code, Codex, opencode):
# registers the MCP server, idempotent, no network, no manual config editing.
dataql setup

# Install the auto-activating Skills for Claude Code
dataql skills install

# Or run the MCP server directly (stdio) for any MCP-capable client
dataql mcp serve

安装脚本运行 dataql setup 对你来说，代理在安装后就可以工作了。

为什么在LLM中使用DataQL？

传统方法	使用DataQL
向上下文发送10MB CSV	运行SQL查询
~10000+个代币	~500个代币
受上下文窗口限制	没有文件大小限制

看 LLM集成指南以获取完整的文档。

安装

快速安装（推荐）

Linux/macOS：

curl -fsSL https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.sh | bash

Windows（PowerShell）：

irm https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.ps1 | iex

使用Docker运行

DataQL以自包含映像的形式发布（嵌入DuckDB，脱机运行）。a座目录并查询它——无需安装：

docker build -t dataql .   # or: make docker-build
docker run --rm -v "$PWD":/data dataql run -f /data/sales.csv -q "SELECT region, SUM(revenue) FROM sales GROUP BY region"

已发布的图像(ghcr.io/adrianolaselva/dataql)由添加分布里程碑；在此之前，请按照上述方式在本地进行构建。

安装选项

具体版本：

Linux/macOS：

curl -fsSL https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.sh | bash -s -- --version v1.0.0

Windows（PowerShell）：

$env:DATAQL_VERSION="v1.0.0"; irm https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.ps1 | iex

用户安装（无需sudo/admin）：

Linux/macOS：

curl -fsSL https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.sh | bash -s -- --local

Windows（PowerShell）：

$env:DATAQL_USER_INSTALL="true"; irm https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.ps1 | iex

来源

# Clone the repository
git clone https://github.com/adrianolaselva/dataql.git
cd dataql

# Build and install
make build
make install       # requires sudo
# or
make install-local # installs to ~/.local/bin

验证安装

dataql --version

更新

升级至最新版本：

Linux/macOS：

# Only upgrades if a newer version is available
curl -fsSL https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.sh | bash -s -- --upgrade

# Force reinstall (same or different version)
curl -fsSL https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.sh | bash -s -- --force

# Clean install (remove all versions first, then install)
curl -fsSL https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.sh | bash -s -- --clean --force

Windows（PowerShell）：

# Force reinstall
$env:DATAQL_FORCE="true"; irm https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/install.ps1 | iex

卸载

Linux/macOS：

curl -fsSL https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/uninstall.sh | bash

Windows（PowerShell）：

irm https://raw.githubusercontent.com/adrianolaselva/dataql/main/scripts/uninstall.ps1 | iex

用法

基本用法

加载数据文件并启动交互模式（格式自动检测）：

# CSV file
dataql run -f data.csv -d ","

# JSON file (array or single object)
dataql run -f data.json

# JSONL/NDJSON file (one JSON per line)
dataql run -f data.jsonl

支持的输入格式

格式	扩展名	描述
CSV	`.csv`	逗号分隔值，带可配置分隔符
JSON	`.json`	JSON数组或单个对象
jsonl	`.jsonl`, `.ndjson`	换行符分隔的JSON（流式）
XML	`.xml`	XML文档
YAML	`.yaml`, `.yml`	YAML文档
拼花地板	`.parquet`	Apache Parquet柱状格式
Excel	`.xlsx`, `.xls`	Microsoft Excel电子表格
Avro	`.avro`	Apache Avro格式
兽人	`.orc`	Apache ORC格式

支持的数据源

来源	格式	示例
本地文件	路径	`-f data.csv`
HTTP/HTTPS	URL	`-f "https://example.com/data.csv"`
亚马逊S3	`s3://`	`-f "s3://bucket/path/data.csv"`
谷歌云存储	`gs://`	`-f "gs://bucket/path/data.json"`
Azure Blob	`az://`	`-f "az://container/path/data.parquet"`
标准输入	`-`	`cat data.csv \| dataql run -f -`
PostgreSQL	`postgres://`	`-f "postgres://user:pass@host/db?table=t"`
MySQL	`mysql://`	`-f "mysql://user:pass@host/db?table=t"`
DuckDB	`duckdb://`	`-f "duckdb:///path/db.db?table=t"`
MongoDB	`mongodb://`	`-f "mongodb://host/db?collection=c"`
DynamoDB	`dynamodb://`	`-f "dynamodb://region/table-name"`

命令行选项

标志	简短	描述	默认
`--file`	`-f`	输入文件、URL或数据库连接	必填
`--delimiter`	`-d`	CSV分隔符（仅适用于CSV文件）	`,`
`--query`	`-q`	要执行的SQL查询	-
`--export`	`-e`	导出路径	-
`--type`	`-t`	导出格式(`csv`, `jsonl`, `json`, `excel`, `parquet`, `xml`, `yaml`)	-
`--storage`	`-s`	DuckDB文件路径（用于持久化）	内存中
`--lines`	`-l`	限制要读取的行数/记录数	全部
`--collection`	`-c`	自定义表名	文件名

例子

探索性统计(describe):

# Instant column profile: type, nulls, unique, min/max/mean/std
dataql describe -f sales.csv

参数化查询（安全且可重用）：

dataql run -f orders.csv \
  -q "SELECT * FROM orders WHERE region = :region AND amount > :min" \
  -p region=North -p min=100

压缩文件（透明）：

# .gz, .bz2 and .xz are decompressed on the fly
dataql run -f logs.jsonl.gz -q "SELECT level, COUNT(*) FROM logs GROUP BY level"

缓存重复查询的源：

dataql run -f huge.parquet -q "SELECT ..." --cache   # first run loads & caches
dataql cache list                                     # inspect cached datasets

通过Docker运行（无需安装）：

docker run --rm -v "$PWD":/data ghcr.io/adrianolaselva/dataql \
  run -f /data/sales.csv -q "SELECT region, SUM(revenue) FROM sales GROUP BY region"

交互模式：

dataql run -f sales.csv -d ";"

dataql> SELECT product, SUM(amount) as total FROM sales GROUP BY product ORDER BY total DESC LIMIT 10;
product      total
Widget Pro   125430.50
Gadget Plus   98210.00
...

执行查询并显示结果：

dataql run -f data.csv -d "," -q "SELECT * FROM data WHERE amount > 100 LIMIT 10"

导出到JSONL：

dataql run -f input.csv -d "," \
  -q "SELECT id, name, value FROM input WHERE status = 'active'" \
  -e output.jsonl -t jsonl

导出到CSV：

dataql run -f input.csv -d "," \
  -q "SELECT * FROM input" \
  -e output.csv -t csv

多个输入文件：

dataql run -f file1.csv -f file2.csv -d "," \
  -q "SELECT a.*, b.extra FROM file1 a JOIN file2 b ON a.id = b.id"

查询JSON文件：

# JSON array
dataql run -f users.json -q "SELECT name, email FROM users WHERE status = 'active'"

# JSON with nested objects (automatically flattened)
# {"user": {"name": "John", "address": {"city": "NYC"}}}
# becomes columns: user_name, user_address_city
dataql run -f data.json -q "SELECT user_name, user_address_city FROM data"

查询JSONL/NDJSON文件：

# JSONL is ideal for large datasets (streaming, low memory)
dataql run -f logs.jsonl -q "SELECT level, message, timestamp FROM logs WHERE level = 'ERROR'"

# Works with .ndjson extension too
dataql run -f events.ndjson -q "SELECT COUNT(*) as total FROM events"

自定义表名称：

# Use --collection to specify a custom table name
dataql run -f data.json -c my_table -q "SELECT * FROM my_table"

坚持使用DuckDB文件：

dataql run -f data.csv -d "," -s ./database.duckdb

从URL查询：

dataql run -f "https://raw.githubusercontent.com/datasets/population/main/data/population.csv" \
  -q "SELECT Country_Name, Value FROM population WHERE Year = 2020 LIMIT 10"

S3查询：

dataql run -f "s3://my-bucket/data/sales.csv" \
  -q "SELECT product, SUM(amount) as total FROM sales GROUP BY product"

PostgreSQL查询：

dataql run -f "postgres://user:pass@localhost:5432/mydb?table=orders" \
  -q "SELECT * FROM orders WHERE status = 'completed'"

查看SQS消息（不使用）：

dataql run -f "sqs://my-events-queue?region=us-east-1" \
  -q "SELECT message_id, body_event_type, timestamp FROM my_events_queue"

从stdin读取：

cat data.csv | dataql run -f - -q "SELECT * FROM stdin_data WHERE value > 100"

真实世界示例

# Download sample data
wget https://www.stats.govt.nz/assets/Uploads/Annual-enterprise-survey/Annual-enterprise-survey-2021-financial-year-provisional/Download-data/annual-enterprise-survey-2021-financial-year-provisional-csv.csv -O survey.csv

# Query and export
dataql run -f survey.csv -d "," \
  -q "SELECT Year, Industry_aggregation_NZSIOC as industry, Variable_name as metric, Value as amount FROM survey WHERE Value > 1000" \
  -e analysis.jsonl -t jsonl

SQL引用

DataQL底层使用DuckDB，支持针对分析查询优化的标准SQL语法：

-- Basic SELECT
SELECT column1, column2 FROM tablename;

-- Filtering
SELECT * FROM data WHERE amount > 100 AND status = 'active';

-- Aggregation
SELECT category, COUNT(*), SUM(value) FROM data GROUP BY category;

-- Joins (multiple files)
SELECT a.*, b.extra FROM file1 a JOIN file2 b ON a.id = b.id;

-- Ordering and Limiting
SELECT * FROM data ORDER BY created_at DESC LIMIT 100;

注：表名来源于文件名（不带扩展名）。对于 sales.csv, sales.json，或 sales.jsonl，使用 SELECT * FROM sales.使用 --collection 标志以指定自定义表名。

文档

有关详细文档，请参阅：

入门指南 -安装和Hello World示例
建筑 -系统架构和设计图
CLI参考 -完整的命令行参考
数据源 -使用S3、GCS、Azure、URL和stdin
数据库连接 -连接到PostgreSQL、MySQL、DuckDB、MongoDB
LLM集成 -与Claude、Codex、Gemini一起使用DataQL
MCP设置 -配置MCP服务器以进行LLM集成
例子 -真实世界的使用示例和自动化脚本

发展

先决条件

达到1.26或更高
GCC（用于CGO编译-DuckDB需要）
Docker和Docker Compose（用于E2E测试）

建筑

make build

测试

make test             # unit tests
make coverage         # unit tests with an HTML coverage report
make coverage-check   # enforce the coverage ratchet (what CI runs)
make e2e              # full E2E suite: provision services, run, tear down (Docker)

质量门

每个公关部门都有门，所以质量只会越来越高——看贡献.md 对于整张桌子：

门	强制
覆盖范围棘轮	总覆盖率永远不会低于 `.coverage-baseline` （上面Codecov徽章中的实时百分比）
棉绒	`golangci-lint` （政府、统计检查、错误检查……）--阻塞
漏洞扫描	`govulncheck` --调用代码中没有已知漏洞
安全扫描	`gosec` --阻塞
线下自给自足	二进制文件在禁用网络的情况下运行（没有运行时下载）
自包含的发布版本	发布二进制文件嵌入DuckDB并传递离线烟雾
Docker镜像	映像离线构建并运行查询
E2E	全套模拟后端（咨询）

E2E测试覆盖率

DataQL包括对所有数据源的全面E2E测试：

数据源	测试	状态
PostgreSQL	26	SELECT、WHERE、ORDER BY、LIMIT、聚合、导出
MySQL	26	SELECT、WHERE、ORDER BY、LIMIT、聚合、导出
MongoDB	20+	集合、查询、过滤器、导出
Kafka	10+	Peek模式，消息解析，导出
S3（LocalStack）	13	CSV、JSON、JSONL文件读取、查询、导出
SQS（LocalStack）	16	消息读取、过滤、聚合、导出
DynamoDB（本地堆栈）	✓	扫描、查询、筛选、导出
URL（HTTP）	3	CSV/JSON通过HTTP，WHERE过滤

看 e2e/COVERAGE.md 对于完整的源/特征覆盖矩阵，以及 e2e/README.md 用于E2E测试文档。

代码检查

make lint

贡献

欢迎投稿！请阅读我们的贡献指南有关我们的行为准则和提交pull请求流程的详细信息。

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

关于本项目

这是对 CSVQL文件，我在2019年做的一个早期实验。原作简单而有限。这个版本？完全在人工智能的帮助下构建（Claude Code）。我想看看人工智能辅助开发能走多远，说实话，它走得很远。代码、文档、测试——所有这些都来自与人工智能的对话。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

CSVQL文件 -启发这次重写的原始项目
克劳德代码 -帮助构建整个项目的AI助手
鸭数据库 -嵌入式分析数据库引擎
眼镜蛇 -CLI框架
go-duckdb -Go的DuckDB驱动程序

使用说明

DataQL

为什么选择DataQL？

问题

解决方案

为什么这很重要

关键利益

快速开始

特征

命令一览

LLM集成

安装

快速安装（推荐）

使用Docker运行

安装选项

来源

验证安装

更新

卸载

用法

基本用法

支持的输入格式

支持的数据源

命令行选项

例子

真实世界示例

SQL引用

文档

发展

先决条件

建筑

测试

质量门

E2E测试覆盖率

代码检查

贡献

关于本项目

许可证

致谢

相关 MCP

文件与终端管理MCP服务

图表生成MCP服务器

ECharts 图表生成 MCP 服务

Excel文件管理分析服务

DuckDB数据库交互服务

Elasticsearch/OpenSearch MCP服务器