name: chat2duckdb description: 基於 DuckDB 引擎的高效資料分析工具；當用戶需要對 CSV/JSON/Parquet/Excel 等資料檔案進行 SQL 查詢、資料分析、資料抽樣或需要自動糾錯的查詢執行時使用 dependency: python: - duckdb>=1.5.0 - pandas>=2.0.0 - numpy>=1.24.0 - openpyxl>=3.1.0

Chat2DuckDB 資料分析

任務目標

• 本技能用於對資料檔案進行快速、高效的 SQL 查詢和分析
• 能力包含：資料檔案註冊為表、自然語言轉 SQL、查詢執行、資料抽樣、錯誤校正、分析結論生成
• 觸發條件：使用者需要分析資料檔案、執行 SQL 查詢、探索資料結構、生成資料分析報告

前置準備

• 依賴說明：安裝 DuckDB 和 pandas duckdb>=1.5.0 pandas>=2.0.0

核心功能

1. 資料探索（Describe 模式）

• 基本資訊：總行數、列數、表結構
• 數值列統計：平均值、中位數、標準差、最大/最小值
• 分類列統計：唯一值數量、最常見值、Top 值分佈
• 日期列統計：最早/最晚日期、唯一日期數
• 資料質量：缺失值統計、完整性分析

2. SQL 查詢執行

• 智慧 SQL 生成：根據自然語言描述自動生成 SQL
• 自動重試機制：最多 3 次智慧重試
• SQL 校正引擎：
• 語法錯誤自動修復（移除多餘分號、逗號等）
• 列名錯誤智慧糾正（基於編輯距離匹配）
• 引號規範化（雙引號轉單引號）
• SQL 關鍵字大小寫規範化
• 資料抽樣：支援按比例抽樣查詢，快速驗證邏輯

3. 結果分析

• 查詢結果格式化輸出
• 執行時間和效能統計
• 資料洞察和業務建議生成

操作步驟

步驟 1：資料準備

確認資料檔案路徑（CSV/JSON/Parquet/Excel 等格式）

步驟 2：資料探索

# 完整統計模式（推薦）
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode describe

# 簡單模式（僅基本資訊）
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode describe --simple

# 匯出分析報告
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode describe --output report.json

# Excel 檔案（預設讀取第一個工作表）
python scripts/duckdb_analyzer.py --file_path ./data.xlsx --mode describe

# Excel 檔案（指定工作表）
python scripts/duckdb_analyzer.py --file_path ./data.xlsx --excel_sheet "sheetTitle" --mode describe

步驟 3：SQL 查詢

# 基礎查詢
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode query \
  --sql "SELECT * FROM data LIMIT 10"

# 聚合查詢
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode query \
  --sql "SELECT category, SUM(price * quantity) as total_sales FROM data GROUP BY category"

# 抽樣驗證（先在小樣本上測試）
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode query \
  --sql "SELECT * FROM data WHERE price > 100" --sample_fraction 0.1

# 匯出查詢結果（支援 CSV/Excel/JSON/Parquet）
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode query \
  --sql "SELECT * FROM data" --output result.csv

python scripts/duckdb_analyzer.py --file_path ./data.csv --mode query \
  --sql "SELECT * FROM data" --output result.xlsx

# 持久化到 DuckDB 檔案（後續可直接關聯查詢）
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode query \
  --persist_db_path ./analysis.duckdb --persist_table \
  --sql "SELECT category, SUM(price * quantity) as total_sales FROM data GROUP BY category"

步驟 4：結果分析

• 檢視查詢結果和資料預覽
• 分析執行時間和重試次數
• 根據結果生成業務洞察

步驟 5：資料持久化（可選）

• --persist_db_path：指定 DuckDB 資料庫檔案路徑
• --persist_table：將登錄檔持久化為普通表（預設是臨時表）
• 典型用途：跨批次積累結果、後續多表關聯查詢、沉澱分析基表

資源索引

• 核心指令碼：scripts/duckdb_analyzer.py（DuckDB 操作核心，支援資料註冊、查詢執行、抽樣、錯誤處理）
• 資料格式參考：references/data-formats.md（支援的檔案格式和最佳實踐）

注意事項

最佳實踐

1. 先探索後查詢：先用 describe 模式瞭解資料結構，再生成 SQL
2. 複雜查詢先抽樣：對於複雜查詢，先用 --sample_fraction 引數在小樣本上驗證
3. 合理使用 LIMIT：查詢結果超過 1000 行時，建議使用 LIMIT 或聚合查詢
4. 利用自動校正：SQL 錯誤時會自動重試和校正，無需手動干預

效能建議

• 大數據集使用抽樣驗證後再執行完整查詢
• 聚合查詢比全表查詢更高效
• 可以設定 --max_retries 引數調整重試次數

錯誤處理

• 語法錯誤會自動修復（多餘分號、逗號等）
• 列名錯誤會嘗試匹配最相似的列名（編輯距離≤2）
• 表名錯誤會提示檢查表名
• 所有校正操作都會在輸出中顯示

使用示例

示例 1：完整資料探索

場景：拿到新資料集，需要了解資料結構和質量

命令：

python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode describe

輸出包含： - 基本資訊：20 行，7 列 - 表結構：各欄位名稱和資料型別 - 數值列統計：price 的平均值 356.99，中位數 264.99 等 - 分類列統計：category 有 2 個唯一值，Electronics 出現 12 次 - 日期列統計：sale_date 從 2024-01-15 到 2024-02-02 - 資料質量：所有列資料完整，無缺失值

示例 2：銷售分析查詢

場景：分析各類別產品的銷售表現

命令：

python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT category, COUNT(*) as num_products, SUM(price * quantity) as total_revenue, AVG(price) as avg_price FROM data GROUP BY category ORDER BY total_revenue DESC"

輸出：

執行 SQL: SELECT category, COUNT(*) as num_products, SUM(price * quantity) as total_revenue, AVG(price) as avg_price FROM data GROUP BY category ORDER BY total_revenue DESC

【查詢結果】
執行時間：0.05 秒
重試次數：0
結果行數：2

資料預覽:
   category  num_products  total_revenue  avg_price
Electronics            12       42938.24     356.99
  Furniture             8       19949.23     356.99

業務洞察： - Electronics 類別貢獻了 68% 的總收入 - 兩個類別的平均價格相同，但 Electronics 銷量更高

示例 3：區域銷售對比

場景：分析不同區域的銷售情況

命令：

python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT region, COUNT(*) as num_orders, SUM(price * quantity) as total_sales, AVG(price) as avg_order_value FROM data GROUP BY region ORDER BY total_sales DESC"

示例 4：高價產品篩選（帶抽樣驗證）

場景：找出高價產品（price > 200），先在 10% 樣本上驗證

命令：

# 先在樣本上驗證
python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT product_name, category, price FROM data WHERE price > 200" --sample_fraction 0.1

# 驗證無誤後執行完整查詢
python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT product_name, category, price FROM data WHERE price > 200 ORDER BY price DESC"

示例 5：自動 SQL 校正

場景：SQL 有語法錯誤（多餘分號），系統自動校正

命令：

python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT * FROM data WHERE price > 100;"

輸出：

【SQL 校正記錄】
  ✓ 語法校正：;\s*$ -> 

【查詢結果】
執行時間：0.03 秒
重試次數：1
結果行數：15

示例 6：匯出查詢結果

場景：將查詢結果儲存為 CSV、Excel、JSON 或 Parquet 檔案

CSV 匯出：

7w4.net小蔥技能站，你的AI助手技能庫。

python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT category, region, SUM(price * quantity) as sales FROM data GROUP BY category, region" \
  --output sales_summary.csv

Excel 匯出：

python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT category, region, SUM(price * quantity) as sales FROM data GROUP BY category, region" \
  --output sales_summary.xlsx

JSON 匯出：

python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT category, region, SUM(price * quantity) as sales FROM data GROUP BY category, region" \
  --output sales_summary.json

Parquet 匯出：

python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT category, region, SUM(price * quantity) as sales FROM data GROUP BY category, region" \
  --output sales_summary.parquet

結果：根據副檔名自動選擇匯出格式，儲存為相應檔案

示例 7：時間序列分析

場景：分析銷售趨勢

命令：

python scripts/duckdb_analyzer.py --file_path ./sales_data.csv --mode query \
  --sql "SELECT DATE_TRUNC('month', sale_date) as month, SUM(price * quantity) as monthly_sales FROM data GROUP BY month ORDER BY month"

故障排查

常見問題

Q1: 檔案找不到？

錯誤：資料檔案不存在：./data.csv

解決：檢查檔案路徑是否正確，使用絕對路徑試試

Q2: Excel 讀取失敗？

錯誤：無法註冊資料表：...

解決： - 確認檔案為 .xlsx 或 .xls - 如工作表不在第一個，新增引數 --excel_sheet "工作表名" - 檢查是否安裝 openpyxl

Q3: SQL 執行失敗？ 系統會自動重試和校正 SQL，如果仍然失敗，檢查： - 列名是否正確（區分大小寫） - SQL 語法是否正確 - 表名是否使用了預設的 'data'

Q4: 記憶體不足？ 解決： - 使用抽樣查詢：--sample_fraction 0.1 - 新增 LIMIT 限制結果數量 - 使用聚合查詢而非全表查詢

輸出格式說明

Describe 模式輸出

• 基本資訊：資料規模概覽
• 表結構：欄位名和資料型別
• 數值列統計：描述性統計指標
• 分類列統計：分佈和頻率資訊
• 日期列統計：時間範圍資訊
• 資料質量：缺失值統計
• 資料樣本：前 5 行資料預覽

Query 模式輸出

• SQL 校正記錄：如果有自動校正，會顯示校正內容
• 查詢結果：執行時間、重試次數、結果行數
• 資料預覽：完整的查詢結果表格

高階技巧

1. 鏈式分析

先用 describe 瞭解資料，再執行多個查詢：

# 步驟 1：探索資料
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode describe

# 步驟 2：基於瞭解執行針對性查詢
python scripts/duckdb_analyzer.py --file_path ./data.csv --mode query \
  --sql "SELECT category, AVG(price) as avg_price FROM data GROUP BY category"

2. 效能最佳化

對於大數據集：

# 先用 1% 樣本快速驗證
python scripts/duckdb_analyzer.py --file_path ./large_data.csv --mode query \
  --sql "SELECT ..." --sample_fraction 0.01

# 驗證通過後再執行完整查詢
python scripts/duckdb_analyzer.py --file_path ./large_data.csv --mode query \
  --sql "SELECT ..."

3. 資料質量檢查

python scripts/duckdb_analyzer.py --file_path ./data.csv --mode describe | grep "缺失"

SQL 語法約束

• 僅使用 DuckDB SQL 方言，不使用其他資料庫的專有語法
• 欄位名支援英文和中文查詢
• 包含中文、空格、連字元、冒號等特殊字元的欄位名，必須使用雙引號
• 當中文欄位未加雙引號時，查詢引擎會自動校正並重試
• 支援中文標點自動轉換（如 ，；（） 轉 ,;()）
• 預設表名為 data
• 生成 SQL 時優先保證可執行性，再進行效能最佳化

Pandas 使用邊界

• Pandas 僅用於讀取檔案與將 DataFrame 註冊到 DuckDB
• Pandas 可用於註冊前的資料安全預處理（如 inf/-inf -> NULL）
• 不使用 Pandas 做業務聚合分析、統計計算或口徑產出
• 最終分析結果必須通過 DuckDB SQL 查詢 data 表生成

欄位名示例

SELECT "銷售渠道", SUM("售後退款-僅退貨金額") AS total_return
FROM data
GROUP BY "銷售渠道"
ORDER BY total_return DESC
LIMIT 10

SELECT 銷售渠道, SUM(售後退款-僅退貨金額) AS total_return
FROM data
GROUP BY 銷售渠道

這個 Skill 質量較好，能滿足日常資料分析和 SQL 查詢需求。它支援多種常見資料格式，可以快速瞭解資料結構和統計特徵，還具備智慧糾錯能力來自動修復 SQL 小錯誤。功能比較全面，但如果你不熟悉 SQL 可能需要一定學習成本。另外部分功能說明與實際支援情況存在小出入，使用時需要注意。總體而言是一款實用、可靠的資料分析工具。