dataql (Adrianolaselva)

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

为什么这很重要

主要优势

• 代币高效：LLM获取查询结果，而不是原始数据。代币使用量减少99%。
• 通用格式支持：CSV、JSON、Parquet、Excel、XML、YAML、Avro、ORC——所有这些都可以用SQL查询。
• 任何数据源：本地文件、URL、S3、GCS、Azure、PostgreSQL、MySQL、MongoDB。
• LLM本地：为Claude、Codex、Gemini内置MCP服务器。克劳德代码的技能。
• 零设置：单个二进制文件，无依赖关系，无配置文件。
• 熟悉语法如果你知道SQL，你就知道DataQL。

快速开始

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

# 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）
• 消息队列（SQS、Kafka、RabbitMQ-在不消费的情况下偷看）

数据库连接器：

• PostgreSQL
• MySQL
• DuckDB
• MongoDB
• DynamoDB

关键能力：

• 使用DuckDB语法执行SQL查询（OLAP优化）
• 将结果导出为CSV、JSONL、JSON、Excel、Parquet、XML、YAML格式
• 具有命令历史记录的交互式REPL模式
• 大文件操作的进度条
• 多输入并行文件处理
• 嵌套JSON对象的自动扁平化
• 连接来自多个来源的数据

LLM集成：

• 用于Claude Code、OpenAI Codex、Google Gemini的MCP服务器
• 自动激活克劳德代码技能
• AI助手的令牌高效数据处理

LLM集成

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

# Install skills for Claude Code
dataql skills install

# Or start MCP server for any LLM
dataql mcp serve

为什么在LLM中使用DataQL？

看 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

安装选项

具体版本：

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

支持的输入格式

支持的数据源

命令行选项

例子

交互模式：

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.24或更高
• GCC（用于CGO编译-DuckDB需要）
• Docker和Docker Compose（用于E2E测试）

建筑

make build

测试

# Unit tests
make test

# E2E tests (requires Docker)
make e2e-up           # Start infrastructure (PostgreSQL, MySQL, MongoDB, Kafka, LocalStack)
make e2e-wait         # Wait for services to be healthy
make e2e-test-scripts # Run all E2E tests
make e2e-down         # Stop infrastructure

E2E测试覆盖率

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

看 e2e/README.md 获取详细的E2E测试文档。

代码检查

make lint

贡献

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

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

关于本项目

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

许可证

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

致谢

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