DuckDB

Analytical SQL database with a CLI that queries CSV, Parquet and JSON files directly.

What is known from testing

On 2026-10-11, the headlesson operator ran all 6 steps of this lesson with DuckDB 1.5.6 (macOS26.5.2 arm64; Homebrew duckdb 1.5.6 bottle installed during this test; self-made CSV input only), and all passed. The final Next step is advice and was not run. An independent check (revision 3fadc9d) covered: An independent re-run reproduced 0 of 6 steps from the start (the install step was not re-run); the outputs of the later 5 steps were checked separately, and values matched across JSON, CSV and Parquet. Its limits: Not an independent pass of the whole lesson. The JSON sum is a string and the Parquet type is DOUBLE. This is the operator's own run, not a vendor claim.

• Test record: test:thklu3q — 2026-10-11, 1.5.6, passed

Independent check

Independent check (revision 3fadc9d6215b): An independent re-run reproduced 0 of 6 steps from the start (the install step was not re-run); the outputs of the later 5 steps were checked separately, and values matched across JSON, CSV and Parquet.

Limits: Not an independent pass of the whole lesson. The JSON sum is a string and the Parquet type is DOUBLE.

Description

DuckDB is an analytical SQL database system. Its CLI runs a single SQL command with -c and exits, and can print results as JSON or CSV with -json or -csv. Without a database file argument it uses a temporary in-memory database, and SQL can read local CSV, Parquet and JSON files by path.

Current lesson

Goal: Create a small CSV, aggregate it with SQL and get the result as JSON and CSV.

This is the current lesson. The test record above was run on the lesson as it was at its own revision; they can differ.

• 1. brew install duckdb
• 2. duckdb --version
• 3. printf 'region,product,amount\nnorth,apple,3\nnorth,pear,5\nsouth,apple,7\nsouth,apple,1\neast,pear,4\n' > sales.csv
• 4. duckdb -init /dev/null -json -c "SELECT region, count(*) AS n, sum(amount) AS total FROM 'sales.csv' GROUP BY region ORDER BY total DESC"
• 5. duckdb -init /dev/null -csv -c "SELECT product, avg(amount) AS avg_amount FROM read_csv('sales.csv') GROUP BY product ORDER BY product"
• 6. duckdb -init /dev/null -c "COPY (SELECT region, sum(amount) AS total FROM 'sales.csv' GROUP BY region) TO 'totals.parquet' (FORMAT parquet)"

Next (advice, not tested): Next: Agree with the user on the real data files and whether any output file may be written; run DESCRIBE SELECT * FROM '<file>' first to check the inferred column types, then run the aggregate with -json and compare row counts with the source.

Cautions recorded with the lesson

These notes come from the lesson. Some describe failures seen in tests; others are general cautions. Each one is not a separately tested result.

• sum() over an integer column returns HUGEINT, which -json prints as a quoted string (for example "total":"8"); CAST to BIGINT or DOUBLE when a JSON number is needed.
• The CLI runs ~/.duckdbrc on startup; pass -init /dev/null for a reproducible run.
• Column types are inferred from the CSV contents; check them with DESCRIBE before relying on numeric or date columns.
• Without a database file the CLI uses a temporary in-memory database; tables created there are lost when the command exits.
• Rows with equal ORDER BY values come back in no guaranteed order; add a tie-breaker column for stable output.
• Confirm: Check which files a query reads and writes (COPY ... TO overwrites paths) and confirm row counts and types before passing results to a downstream step.

How to start

• cli duckdb: install brew install duckdb; check duckdb --version; auth: None for local files.; docs: https://duckdb.org/docs/current/clients/cli/overview.html

Where each of these values comes from is listed per field under Sources (/interfaces/N/field).

Compared facts

• license: MIT (checked 2026-10-11, primary, official; source: https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE)
• open_source: true (checked 2026-10-11, primary, official; source: https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE)
• pricing: free (checked 2026-10-11, inferred, editorial; source: https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE)
• has_human_gui: optional (checked 2026-10-11, primary, official; source: https://duckdb.org/docs/current/core_extensions/ui.html)
• non_interactive: true (checked 2026-10-11, primary, official; source: https://duckdb.org/docs/current/clients/cli/arguments.html)
• machine_output: true (checked 2026-10-11, primary, official; source: https://duckdb.org/docs/current/clients/cli/arguments.html)
• local_mcp: unknown (not confirmed)
• remote_mcp: unknown (not confirmed)
• cli: true (checked 2026-10-11, primary, official; source: https://duckdb.org/docs/current/clients/cli/overview.html)
• rest_api: unknown (not confirmed)
• auth: none (checked 2026-10-11, inferred, editorial; source: headlesson editorial judgement)
• self_hostable: true (checked 2026-10-11, primary, editorial; source: headlesson editorial judgement)
• embeds_llm: unknown (not confirmed)
• refusal_contract: unknown (not confirmed)
• audit_log: unknown (not confirmed)
• last_release: 2026-09-28 (checked 2026-10-11, primary, official; source: https://github.com/duckdb/duckdb/releases)
• ja_support: unknown (not confirmed)

Sources

Each line names fields of this page (as JSON pointers into the .json version) and where they come from. Labels without a link are non-public sources. Fields not listed (such as test results) are the headlesson operator's own observations.

• /name, /one_liner: https://duckdb.org/ (checked 2026-10-11, primary, official)
• /description: https://duckdb.org/docs/current/clients/cli/overview.html (checked 2026-10-11, primary, editorial)
• /lesson/goal, /lesson/next_advice, /lesson/cautions/items/2, /lesson/cautions/items/4, /lesson/cautions/items/5, /axes/auth: headlesson editorial judgement (checked 2026-10-11, inferred, editorial)
• /lesson/steps/0, /interfaces/0/kind, /interfaces/0/name, /interfaces/0/install, /interfaces/0/verify, /interfaces/0/auth, /interfaces/0/docs: https://duckdb.org/install/ (checked 2026-10-11, primary, official)
• /lesson/steps/1, /lesson/steps/2, /lesson/steps/3, /lesson/steps/4, /lesson/steps/5, /lesson/cautions/items/0, /axes/self_hostable: headlesson editorial judgement (checked 2026-10-11, primary, editorial)
• /lesson/cautions/items/1, /lesson/cautions/items/3, /axes/cli: https://duckdb.org/docs/current/clients/cli/overview.html (checked 2026-10-11, primary, official)
• /axes/license, /axes/open_source: https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE (checked 2026-10-11, primary, official)
• /axes/pricing: https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE (checked 2026-10-11, inferred, editorial)
• /axes/has_human_gui: https://duckdb.org/docs/current/core_extensions/ui.html (checked 2026-10-11, primary, official)
• /axes/non_interactive, /axes/machine_output: https://duckdb.org/docs/current/clients/cli/arguments.html (checked 2026-10-11, primary, official)
• /axes/last_release: https://github.com/duckdb/duckdb/releases (checked 2026-10-11, primary, official)

Primary record

Test results here are the operator's own past lesson trials (legacy). They are not claimed to meet level L1 of run-task-contract/0.1.0.

Relations

• None published yet.

1 other relations point to records that are not published yet.

Retrieve over MCP

headlesson_get id="app:duckdb" sections ["lesson","gotchas"] on https://mcp.headlesson.com/mcp

Cite

headlesson app:duckdb: see test record test:thklu3q (https://headlesson.com/tests/thklu3q).

Page updated: 2026-10-13 (the date its content last changed).

要約（日本語）: DuckDB。運営の試用（2026-10-11、1.5.6、passed）の記録がある。詳しい条件・限界・出典は本文のとおり。