How-to guides

Focused guides that each walk through one task end to end. Each assumes you’ve finished the tutorial and can already build and run a worker.

Not sure which function shape you need? Start with Function patterns — a runnable worker for each of the five shapes — then come back here for specific tasks.

Guides

• Function patterns — scalar, table, table-in-out, aggregate and buffering, with a complete worker for each. (Start here.)
• Argument tags — the complete vgi:"..." grammar: every key, the Go-type inference table, and the constraints DuckDB enforces.
• Report errors well — the typed errors, panic recovery, cancellation, and the wrapping mistake that silently loses a type.
• Expose a catalog — surface schemas, tables and views to DuckDB via ATTACH.
• Persist state across workers — the execution and attach scopes, and which primitive to reach for.
• Call a worker from code — drive one through DuckDB or with the Python client. (vgi-go is worker-side only.)
• Settings, secrets, and global functions — the capabilities a worker declares on itself.
• Serve over HTTP — run a worker as a network service, and the signing key every multi-process deployment needs.
• Authenticate callers — bearer tokens, mTLS and OAuth on the HTTP transport, and reading the caller’s identity in a function.
• Integrate with the optimizer — accept pushed-down filters and report column statistics.
• Cache results on the client — advertise TTLs and validators so repeat queries skip the worker entirely.
• Add a custom COPY format — implement COPY … FROM and COPY … TO for your own format or sink.

Next steps

• New here? Start with the tutorial.
• Want the “why” behind the API? See Concepts — shared across every SDK.
• Need exact signatures? See the API Reference.