# csv-query-tool

**Repository Path**: leonda/csv-query-tool

## Basic Information

- **Project Name**: csv-query-tool
- **Description**: CSV查询工具是一款基于Python GUI开发的桌面应用程序，旨在为开发人员和数据分析师提供一个轻量级的数据查询解决方案。该工具允许用户直接对CSV和Excel文件执行SQL查询，无需将数据导入数据库，从而大幅提高数据提取和分析的效率。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2025-03-17
- **Last Updated**: 2025-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CSV查询工具

CSV查询工具是一款基于Python GUI开发的桌面应用程序，旨在为开发人员和数据分析师提供一个轻量级的数据查询解决方案。该工具允许用户直接对CSV和Excel文件执行SQL查询，无需将数据导入数据库，从而大幅提高数据提取和分析的效率。

## 功能特点

### 文件管理
- **文件导入**：支持导入CSV和Excel(.xlsx, .xls)格式文件
- **多文件管理**：同时管理多个数据文件，支持文件的添加、移除和刷新
- **文件预览**：快速预览导入文件的内容和结构
- **文件元数据**：显示文件的行数、列数、列名和数据类型等信息
- **最近文件记录**：记录最近打开的文件，方便快速访问
- **文件组合**：创建和管理文件组合，一键加载多个相关文件
- **批量操作**：支持批量加载多个文件组合
- **导入/导出组合**：支持将文件组合配置导出和导入，方便在不同设备间共享

### 查询功能
- **SQL查询**：支持标准SQL语法进行数据查询
- **多表关联**：支持JOIN操作实现多文件数据关联查询
- **聚合函数**：支持COUNT, SUM, AVG, MAX, MIN等聚合函数
- **条件筛选**：支持WHERE子句进行条件筛选
- **排序分组**：支持ORDER BY和GROUP BY操作
- **查询历史**：保存历史查询语句，方便重复使用
- **查询模板**：提供常用查询模板，加速查询构建
- **查询管理**：支持保存、编辑和重命名常用查询
- **查询描述**：为保存的查询添加详细描述，便于理解查询目的

### 结果处理
- **结果展示**：以表格形式展示查询结果
- **结果排序**：支持点击列头对结果进行排序
- **结果筛选**：支持在结果表格中进行二次筛选
- **结果导出**：将查询结果导出为CSV、Excel或JSON格式
- **结果可视化**：支持基本的图表可视化功能（柱状图、折线图、饼图等）
- **交互式图表**：使用Plotly提供交互式数据可视化体验

### 用户体验
- **直观界面**：清晰简洁的用户界面，操作流程直观
- **拖拽支持**：支持文件拖拽导入和组合管理
- **自动补全**：SQL编辑器支持语法高亮和自动补全
- **错误提示**：提供友好的错误提示和修复建议
- **主题切换**：支持明暗主题切换
- **快捷键**：支持常用操作的快捷键
- **异常处理**：全局异常捕获，确保系统稳定性
- **上下文菜单**：右键菜单提供丰富的上下文操作

## 安装说明

### 系统要求
- Windows 7/8/10/11
- 无需安装Python环境（独立可执行文件）
- 至少2GB内存
- 100MB可用磁盘空间

### 安装步骤

#### 方法一：使用可执行文件（推荐）
1. 下载最新的发布版本：[CSV查询工具v0.3.0](https://github.com/leonda123/csv-query-tool/releases/latest)
2. 双击`CSVQueryTool.exe`直接运行，无需安装

#### 方法二：从源代码运行
1. 克隆仓库到本地
```bash
git clone https://github.com/leonda123/csv-query-tool.git
cd csv-query-tool
```

2. 安装依赖包
```bash
pip install -r requirements.txt
```

3. 运行程序
```bash
python main.py
```

## 使用指南
### 主界面截图：
![主界面截图](https://github.com/leonda123/csv-query-tool/blob/main/image/%E4%B8%BB%E7%95%8C%E9%9D%A2.png?raw=true)
### 关联查询截图：
![关联查询截图](https://github.com/leonda123/csv-query-tool/blob/main/image/%E5%85%B3%E8%81%94%E6%9F%A5%E8%AF%A2.png?raw=true)
### 可视化截图：
![可视化截图](https://github.com/leonda123/csv-query-tool/blob/main/image/%E5%8F%AF%E8%A7%86%E5%8C%96%E6%95%B0%E6%8D%AE.png?raw=true)
### 导入文件
1. 点击工具栏中的"打开文件"按钮
2. 选择CSV或Excel文件
3. 文件将显示在左侧文件列表中
4. 也可以通过"最近文件"菜单快速访问之前打开过的文件
5. 支持将文件直接拖放到应用程序窗口中导入

### 使用文件组合
1. 点击工具栏中的"文件组合"按钮或文件管理器中的"文件组合"按钮
2. 选择"创建新组合"选项
3. 在对话框中输入组合名称和描述
4. 点击"添加文件"按钮选择要包含在组合中的CSV或Excel文件
5. 也可以直接将CSV或Excel文件拖放到对话框中
6. 点击"保存"按钮创建组合
7. 之后可以通过"文件组合"菜单一键加载整个组合中的所有文件

### 管理文件组合
1. 点击"文件组合"按钮，选择"管理组合"选项
2. 在弹出的菜单中选择要管理的组合
3. 可以选择"加载"、"编辑"或"删除"操作
4. 编辑组合时可以添加或移除文件，修改组合名称和描述

### 批量操作文件组合
1. 点击"文件组合"按钮，选择"批量加载"选项
2. 在对话框中选择要加载的一个或多个文件组合
3. 点击"确定"按钮批量加载所选组合中的所有文件

### 导入/导出文件组合
1. 点击"文件组合"按钮，选择"导出组合"选项将文件组合保存为JSON文件
2. 点击"导入组合"选项从JSON文件导入文件组合
3. 这样可以在不同设备间共享文件组合配置

### 执行查询
1. 在查询编辑器中输入SQL查询语句
2. 可以使用查询模板快速生成常用查询
3. 点击"执行查询"按钮运行查询
4. 查询结果将显示在下方的结果表格中
5. 如果查询有语法错误，会显示友好的错误提示

### 管理查询
1. 编写有用的查询后，点击"保存查询"按钮
2. 输入查询名称和可选的描述
3. 通过"管理查询"菜单可以加载、编辑、重命名或删除保存的查询
4. 也可以从"保存的查询"下拉框中快速选择查询
5. 右键点击查询编辑器可以快速访问查询管理功能

### 可视化数据
1. 执行查询后，切换到"数据可视化"选项卡
2. 选择图表类型、X轴和Y轴列
3. 点击"创建图表"按钮生成可视化图表
4. 支持柱状图、折线图、饼图、散点图和直方图
5. 交互式图表支持缩放、平移和数据点悬停查看

### 导出结果
1. 在结果表格下方选择导出格式（CSV、Excel或JSON）
2. 点击相应的导出按钮
3. 选择保存位置并确认
4. 导出完成后会显示成功提示

### 主题切换
- 点击工具栏中的"切换主题"按钮在明暗主题之间切换
- 主题设置会被保存，下次启动时自动应用

### 错误处理
- 当遇到错误时，系统会显示友好的错误对话框
- 对话框包含错误描述和详细信息
- 即使发生错误，应用程序也会继续运行，不会崩溃

## 快捷键

| 功能 | 快捷键 |
|------|--------|
| 打开文件 | Ctrl+O |
| 执行查询 | F5 或 Ctrl+Enter |
| 保存查询 | Ctrl+S |
| 清除查询 | Ctrl+L |
| 切换主题 | Ctrl+T |
| 显示帮助 | F1 |
| 退出程序 | Alt+F4 |

## 示例查询

### 基本查询
```sql
SELECT * FROM sales LIMIT 10
```

### 条件筛选
```sql
SELECT * FROM employees 
WHERE department = 'Marketing' 
AND salary > 50000
```

### 多表连接
```sql
SELECT o.order_id, c.customer_name, p.product_name, o.quantity
FROM orders o
JOIN customers c ON o.customer_id = c.id
JOIN products p ON o.product_id = p.id
WHERE o.order_date >= '2025-01-01'
```

### 分组统计
```sql
SELECT region, product_category, SUM(sales_amount) as total_sales
FROM sales
GROUP BY region, product_category
ORDER BY total_sales DESC
```

## 项目结构

## 许可证

本项目采用MIT许可证 - 详情请参见 [LICENSE](LICENSE) 文件

Copyright (c) 2025 leonda123

## 联系方式

项目维护者：leonda123 <dadajiu45@gmail.com>

项目链接：[https://github.com/leonda123/csv-query-tool](https://github.com/leonda123/csv-query-tool)