ai.sql

Write a DuckDB query from a description, fitted to the tables' actual schema, for duckdb.query_file to run. The query is checked against the tables before it is emitted.

Kind: standard
Network: yes
Secrets: llm (optional) -- see Secrets

Inputs🔗

Name	Type	Required	Default	Description
`tables`	collection of file (Parquet)	yes		Tables to work from, named t0, t1, ... in order.
`description`	string	yes		What the artifact should do, in plain language.
`model`	string	yes		Model identifier, exactly as the provider names it (e.g. claude-opus-5-5).
`provider`	string	no	`anthropic`	Who serves the model. The key is the block's `llm` secret. One of `anthropic`, `openai`, `openai_compatible`.
`base_url`	string	no	blank	Endpoint for an OpenAI-compatible server (vLLM, Ollama, Azure, a gateway). Leave blank for the provider's own API.
`share`	string	no	`schema`	How much of the data the model may see. Column names are always sent; summary statistics reveal values; samples send rows. Everything sent is recorded in the provenance output. One of `schema`, `summary`, `samples`.
`max_turns`	number	no	`10`	Model calls before the block gives up.
`max_tokens`	number	no	`200000`	Input plus output tokens across all calls, billed to your key.
`nonce`	string	no	blank	Change to generate afresh with nothing else changed; the block ignores its value.

Outputs🔗

Name	Type	Description
`query`	file (SQL)	The query, with a header duckdb.query_file checks.
`provenance`	json	Every tool result sent to the model, the model and endpoint used, and token usage.

Example🔗

- id: "@sql"
  name: ai.sql
  inputs: [{block: "@pivot", output: result, as: tables}]
  args:
    description: Total biomass per plot across every species column.
    provider: anthropic
    model: claude-opus-5-5
    share: schema
  secrets:
    llm: my-anthropic-key