{
 "kind": "app",
 "id": "app:duckdb",
 "url": "https://headlesson.com/apps/duckdb",
 "name": "DuckDB",
 "one_liner": "Analytical SQL database with a CLI that queries CSV, Parquet and JSON files directly.",
 "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.",
 "made_by_headlesson_operator": false,
 "interfaces": [
  {
   "kind": "cli",
   "name": "duckdb",
   "install": "brew install duckdb",
   "verify": "duckdb --version",
   "auth": "None for local files.",
   "docs": "https://duckdb.org/docs/current/clients/cli/overview.html"
  }
 ],
 "tests": [
  {
   "record_id": "test:thklu3q",
   "url": "https://headlesson.com/tests/thklu3q",
   "date": "2026-10-11",
   "version": "1.5.6",
   "status": "passed"
  }
 ],
 "latest_test_conclusion": "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: The installation step was not performed during the independent check, so 0 of 6 steps were verified consecutively from the start of the lesson. The outputs of the later five 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.",
 "independent_check": {
  "state": "recorded",
  "revision": "3fadc9d6215b5a823c490dfc86f16d93dac683b2",
  "scope": "The installation step was not performed during the independent check, so 0 of 6 steps were verified consecutively from the start of the lesson. The outputs of the later five 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."
 },
 "lesson": {
  "goal": "Create a small CSV, aggregate it with SQL and get the result as JSON and CSV.",
  "steps": [
   "brew install duckdb",
   "duckdb --version",
   "printf 'region,product,amount\\nnorth,apple,3\\nnorth,pear,5\\nsouth,apple,7\\nsouth,apple,1\\neast,pear,4\\n' > sales.csv",
   "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\"",
   "duckdb -init /dev/null -csv -c \"SELECT product, avg(amount) AS avg_amount FROM read_csv('sales.csv') GROUP BY product ORDER BY product\"",
   "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": "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": {
   "note": "These notes come from the lesson. Some describe failures seen in tests; others are general cautions. Each one is not a separately tested result.",
   "items": [
    "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."
   ]
  },
  "note": "This is the current lesson. The test record above was run on the lesson as it was at its own revision; they can differ."
 },
 "mcp_get": "headlesson_get id=\"app:duckdb\" sections [\"lesson\",\"gotchas\"]",
 "axes": {
  "license": {
   "value": "MIT",
   "checked": "2026-10-11",
   "certainty": "primary",
   "source": "https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE",
   "by": "official"
  },
  "open_source": {
   "value": true,
   "checked": "2026-10-11",
   "certainty": "primary",
   "source": "https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE",
   "by": "official"
  },
  "pricing": {
   "value": "free",
   "checked": "2026-10-11",
   "certainty": "inferred",
   "source": "https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE",
   "by": "editorial"
  },
  "has_human_gui": {
   "value": "optional",
   "checked": "2026-10-11",
   "certainty": "primary",
   "source": "https://duckdb.org/docs/current/core_extensions/ui.html",
   "by": "official"
  },
  "non_interactive": {
   "value": true,
   "checked": "2026-10-11",
   "certainty": "primary",
   "source": "https://duckdb.org/docs/current/clients/cli/arguments.html",
   "by": "official"
  },
  "machine_output": {
   "value": true,
   "checked": "2026-10-11",
   "certainty": "primary",
   "source": "https://duckdb.org/docs/current/clients/cli/arguments.html",
   "by": "official"
  },
  "local_mcp": {
   "value": "unknown",
   "checked": null,
   "certainty": null,
   "source": null,
   "by": null
  },
  "remote_mcp": {
   "value": "unknown",
   "checked": null,
   "certainty": null,
   "source": null,
   "by": null
  },
  "cli": {
   "value": true,
   "checked": "2026-10-11",
   "certainty": "primary",
   "source": "https://duckdb.org/docs/current/clients/cli/overview.html",
   "by": "official"
  },
  "rest_api": {
   "value": "unknown",
   "checked": null,
   "certainty": null,
   "source": null,
   "by": null
  },
  "auth": {
   "value": "none",
   "checked": "2026-10-11",
   "certainty": "inferred",
   "source": "headlesson editorial judgement",
   "by": "editorial"
  },
  "self_hostable": {
   "value": true,
   "checked": "2026-10-11",
   "certainty": "primary",
   "source": "headlesson editorial judgement",
   "by": "editorial"
  },
  "embeds_llm": {
   "value": "unknown",
   "checked": null,
   "certainty": null,
   "source": null,
   "by": null
  },
  "refusal_contract": {
   "value": "unknown",
   "checked": null,
   "certainty": null,
   "source": null,
   "by": null
  },
  "audit_log": {
   "value": "unknown",
   "checked": null,
   "certainty": null,
   "source": null,
   "by": null
  },
  "last_release": {
   "value": "2026-09-28",
   "checked": "2026-10-11",
   "certainty": "primary",
   "source": "https://github.com/duckdb/duckdb/releases",
   "by": "official"
  },
  "ja_support": {
   "value": "unknown",
   "checked": null,
   "certainty": null,
   "source": null,
   "by": null
  }
 },
 "sources": [
  {
   "fields": [
    "/name",
    "/one_liner"
   ],
   "source": "https://duckdb.org/",
   "checked": "2026-10-11",
   "certainty": "primary",
   "by": "official"
  },
  {
   "fields": [
    "/description"
   ],
   "source": "https://duckdb.org/docs/current/clients/cli/overview.html",
   "checked": "2026-10-11",
   "certainty": "primary",
   "by": "editorial"
  },
  {
   "fields": [
    "/lesson/goal",
    "/lesson/next_advice",
    "/lesson/cautions/items/2",
    "/lesson/cautions/items/4",
    "/lesson/cautions/items/5",
    "/axes/auth"
   ],
   "source": "headlesson editorial judgement",
   "checked": "2026-10-11",
   "certainty": "inferred",
   "by": "editorial"
  },
  {
   "fields": [
    "/lesson/steps/0",
    "/interfaces/0/kind",
    "/interfaces/0/name",
    "/interfaces/0/install",
    "/interfaces/0/verify",
    "/interfaces/0/auth",
    "/interfaces/0/docs"
   ],
   "source": "https://duckdb.org/install/",
   "checked": "2026-10-11",
   "certainty": "primary",
   "by": "official"
  },
  {
   "fields": [
    "/lesson/steps/1",
    "/lesson/steps/2",
    "/lesson/steps/3",
    "/lesson/steps/4",
    "/lesson/steps/5",
    "/lesson/cautions/items/0",
    "/axes/self_hostable"
   ],
   "source": "headlesson editorial judgement",
   "checked": "2026-10-11",
   "certainty": "primary",
   "by": "editorial"
  },
  {
   "fields": [
    "/lesson/cautions/items/1",
    "/lesson/cautions/items/3",
    "/axes/cli"
   ],
   "source": "https://duckdb.org/docs/current/clients/cli/overview.html",
   "checked": "2026-10-11",
   "certainty": "primary",
   "by": "official"
  },
  {
   "fields": [
    "/axes/license",
    "/axes/open_source"
   ],
   "source": "https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE",
   "checked": "2026-10-11",
   "certainty": "primary",
   "by": "official"
  },
  {
   "fields": [
    "/axes/pricing"
   ],
   "source": "https://raw.githubusercontent.com/duckdb/duckdb/main/LICENSE",
   "checked": "2026-10-11",
   "certainty": "inferred",
   "by": "editorial"
  },
  {
   "fields": [
    "/axes/has_human_gui"
   ],
   "source": "https://duckdb.org/docs/current/core_extensions/ui.html",
   "checked": "2026-10-11",
   "certainty": "primary",
   "by": "official"
  },
  {
   "fields": [
    "/axes/non_interactive",
    "/axes/machine_output"
   ],
   "source": "https://duckdb.org/docs/current/clients/cli/arguments.html",
   "checked": "2026-10-11",
   "certainty": "primary",
   "by": "official"
  },
  {
   "fields": [
    "/axes/last_release"
   ],
   "source": "https://github.com/duckdb/duckdb/releases",
   "checked": "2026-10-11",
   "certainty": "primary",
   "by": "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": [],
 "relations_not_published": 1,
 "cite": "headlesson app:duckdb: see test record test:thklu3q (https://headlesson.com/tests/thklu3q).",
 "page_updated": "2026-10-13"
}