DuckDB

stack: app
services:
  duckdb:
    recipe: duckdb
    # its defaults, each a field you can set:
    # image: taleshape/shaper:0.25.2
    # size: nano
    # volume: { gb: 5 }

briq_run({ recipe: "duckdb", wait: true })

curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "duckdb",
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "SHAPER_URL": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"

When to use it

• The agent has a dataset to analyse, and you would rather open charts than read a table in chat.
• You want a dashboard someone can open from a link, without an account.
• You want SQL over CSV, Parquet or JSON files, kept and run again on fresh data.

One briq: DuckDB inside Shaper, an open source dashboard tool where a dashboard is a SQL file. On first boot Shaper makes its admin account (password in SHAPER_ADMIN_PASSWORD). The data lives on the briq's volume. The full walk-through, from a CSV on the web to a shared link, is Report on a dataset.

Tips

• shp runs everything from briq_exec on the duckdb briq: shp sql, shp dashboard, shp update, shp share, shp pdf, and shp api for the rest of Shaper's API. - reads SQL from stdin.
• Load from the URL: shp sql "CREATE TABLE t AS FROM read_csv('https://…')". DuckDB downloads the file itself, so the data never goes through the agent. read_parquet and read_json too.
• Check with SQL: shp sql "SUMMARIZE t" prints each column's type, range and nulls.
• A dashboard is SQL: each SELECT is a chart, a table or a value. Casts say how to draw it: x::XAXIS, n::BARCHART, kind::CATEGORY. The full list is the dashboard SQL reference.
• Years on an x axis draw as dates: make_date(year::INT, 1, 1)::XAXIS.
• Share one dashboard: shp share <id> prints /view/<id>. Run with expose: "private" and keep the ?briq_token= on the link you send, so the link is the only way in.
• A PDF to attach: shp pdf <id> /tmp/report.pdf, then briq_files_get. For a download button on the page: SELECT 'Report'::DOWNLOAD_PDF AS "Download PDF";.
• More data, more memory: DuckDB takes half the machine and spills the rest to the volume. Use size: "small" or "medium" for a dataset bigger than the nano's memory.