chat2duckdb

Analyze CSV, JSON, Parquet, and Excel files with DuckDB SQL queries.

8|2|Updated Apr 29, 2026
One-click install
npx skills add https://github.com/luojiaaoo/xpeech --skill chat2duckdb-luojiaaoo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: chat2duckdb
Source: https://github.com/luojiaaoo/xpeech/tree/main/xpeech/agent/skills/buildin/chat2duckdb
Command: npx skills add https://github.com/luojiaaoo/xpeech --skill chat2duckdb-luojiaaoo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires duckdb, pandas, numpy, openpyxl, and includes scripts (resource) and references (resource) components.

What problem does it solve? Analyzing data files often requires writing boilerplate code to load files, inspect schemas, and debug SQL errors. This Skill registers CSV, JSON, Parquet, and Excel files as DuckDB tables, generates descriptive statistics, and executes SQL queries with automatic error correction and retry. ## Core Features & Use Cases - Data Exploration: Describe mode reports row counts, column types, numeric/categorical/date statistics, and missing-value quality checks. - SQL Query with Auto-Correction: Executes natural-language-derived SQL with up to 3 retries, automatically fixing syntax errors, quoting Chinese column names, and matching misspelled columns via edit distance. - Sampling, Export & Persistence: Validate queries on data samples, export results to CSV/Excel/JSON/Parquet, or persist tables into a DuckDB database file for later joins. - Use Case: Given a sales_data.csv file, first run describe mode to learn the schema, then query revenue by category and export the aggregated result to an Excel report. ## Quick Start Ask the agent to analyze the attached sales CSV file with DuckDB, first describing its structure and then querying total revenue grouped by product category.

Frequently Asked Questions about chat2duckdb

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run SQL queries on a CSV file with DuckDB?▼

Register the CSV as a table using read_csv_auto, then execute standard DuckDB SQL against it. This Skill wraps that flow in a script: pass --file_path with --mode query and your --sql statement to get results with execution time and row counts.

How to explore data structure before writing SQL queries?▼

Run the analyzer in describe mode, which reports row counts, column types, numeric statistics like mean and median, categorical value distributions, date ranges, and missing-value percentages. This helps you write accurate queries on the first attempt.

Does DuckDB support Excel files with Chinese column names?▼

Yes. Excel files are read via pandas and registered into DuckDB, with a specific sheet selectable via --excel_sheet. Chinese column names are automatically wrapped in double quotes during query correction so DuckDB can parse them.

Why does my SQL query fail and how is it auto-corrected?▼

Common failures include trailing semicolons, Chinese punctuation, and misspelled column names. The correction engine fixes syntax patterns, converts Chinese punctuation, and matches wrong column names to the closest real column using prefix matching and edit distance up to 2.

How to handle large datasets that cause memory issues?▼

Use --sample_fraction to validate queries on a fraction of the data first, add LIMIT to cap result rows, and prefer aggregate queries over full-table scans. The connection sets a 4GB memory limit by default.

Can I save DuckDB query results for later analysis?▼

Yes. Export results directly to CSV, Excel, JSON, or Parquet via --output, or use --persist_db_path with --persist_table to write tables into a DuckDB database file for cross-batch accumulation and multi-table joins later.