DuckDB 交互式数据查询工具

DuckDB 交互式数据查询工具

基于 DuckDB 和 Streamlit 构建的轻量级数据查询与分析工具，支持多种文件格式的直接 SQL 查询以及远程数据库（PostgreSQL/MySQL）的无缝对接。

项目概述

本项目提供两个核心功能模块：

1. 文件查询工具 (file_util.py) - 本地文件的 SQL 查询分析
2. 数据库查询工具 (duckdb_util.py) - 远程关系型数据库的查询分页

技术栈

组件	用途
DuckDB	高性能嵌入式 OLAP 数据库引擎
Streamlit	Web 交互界面框架
Pandas	数据处理与展示
Python 3.x	开发语言

功能特性

file_util.py - 文件查询工具

支持的文件格式

文件类型	说明
CSV	直接 SQL 查询
Excel (.xlsx/.xls)	自动转换为 CSV，支持多 sheet
JSON	直接 SQL 查询
Parquet	列式存储格式查询
SQL/TXT/BLOB	文本内容读取查询

核心能力

• 多文件上传：支持单次上传多个文件进行对比分析
• Excel 智能转换：自动识别多 sheet 并分别转换
• 自定义 SQL：用户可输入任意 SQL 语句进行数据筛选
• 内存优化：使用 DuckDB 内存模式，查询完成即释放

# 核心查询逻辑示例
def csv_query(file_path: str, sql_query: str, header_number: int = 0):
    with duckdb.connect(":memory:", config={"threads": 10}) as conn:
        query = f"select * from '{file_path}'"
        if sql_query:
            query = sql_query
        return conn.execute(query).fetchdf()

duckdb_util.py - 数据库查询工具

支持的数据库类型

• PostgreSQL
• MySQL

核心能力

• Federation 联邦查询：通过 DuckDB Extensions 直接连接远程数据库
• 分页浏览：内置分页机制，每页 100 条记录
• 条件过滤：支持 WHERE 子句快速筛选
• 只读模式：默认 READ_ONLY 连接，保障数据安全

# 数据库连接示例
conn.sql(f"""
    CREATE SECRET db_secret(
        TYPE '{SQL_DATABASE_TYPE}',
        HOST '{SQL_DATABASE_HOST}',
        PORT {SQL_DATABASE_PORT},
        DATABASE '{SQL_DATABASE_DATABASE}',
        USER '{SQL_DATABASE_USER}',
        PASSWORD '{SQL_DATABASE_PASSWORD}'
    );
""")

安装部署

依赖安装

pip install -r requirements.txt

requirements.txt

python-dotenv
streamlit
pandas
duckdb
xlrd
openpyxl

环境变量配置

复制 .env.example 为 .env 并填写配置：

SQL_DATABASE_HOST=localhost
SQL_DATABASE_USER=your_user
SQL_DATABASE_PORT=5432
SQL_DATABASE_DATABASE=your_db
SQL_DATABASE_PASSWORD=your_password
SQL_DATABASE_TYPE=postgres  # 或 mysql

启动运行

文件查询工具

streamlit run file_util.py

数据库查询工具

streamlit run duckdb_util.py

Streamlit 配置

项目包含 .streamlit/config.toml 配置文件：

[server]
headless = true
runOnSave = true
address="0.0.0.0"

[theme]
base="light"

[client]
toolbarMode = "viewer"

架构设计

┌─────────────────────────────────────────────────────────┐
│                    Streamlit UI Layer                   │
│  ┌──────────────────┐       ┌──────────────────────┐   │
│  │  文件上传组件     │       │  SQL 输入框           │   │
│  │  分页选择器      │       │  结果展示表格        │   │
│  └──────────────────┘       └──────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────┐
│                  Business Logic Layer                   │
│  ┌──────────────────┐       ┌──────────────────────┐   │
│  │ excel_to_csv()   │       │ exec_query()         │   │
│  │ csv_query()      │       │ (Postgres/MySQL)     │   │
│  │ file_query()     │       │                      │   │
│  │ blob_query()     │       │                      │   │
│  └──────────────────┘       └──────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   Data Engine Layer                     │
│  ┌──────────────────────────────────────────────────┐  │
│  │              DuckDB In-Memory Engine             │  │
│  │  - 多线程配置 (threads: 10/100)                  │  │
│  │  - PostgreSQL Extension                          │  │
│  │  - MySQL Extension                               │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

使用场景

数据分析人员

• 无需编写 ETL 脚本，直接用 SQL 分析 Excel/CSV 数据
• 快速验证数据质量，排查异常记录

开发人员

• 调试数据库查询语句，可视化验证结果
• 跨数据库联合查询测试

运维人员

• 生产数据库只读查询，避免误操作风险
• 日志文件（JSON/Parquet）快速检索

性能优化

1. 多线程处理：DuckDB 配置 threads=10~100 充分利用 CPU
2. 内存管理：:memory: 模式避免磁盘 IO 开销
3. 列式存储：Parquet 格式支持列裁剪，减少数据传输

安全注意事项

1. 敏感数据请使用 .env 文件存储，不要硬编码
2. 数据库连接默认只读模式（READ_ONLY）
3. 临时文件定期清理（界面提供 Clear 按钮）
4. 生产环境建议启用 Streamlit 认证中间件

扩展方向

• 添加查询历史保存功能
• 支持结果导出（CSV/PDF）
• 集成图表可视化（Plotly/Altair）
• 支持更多数据源（Redis/MongoDB）
• 添加 SQL 语法高亮和自动补全

许可证

MIT License

---