duckdb-c-extension-function-catalog

name	duckdb-c-extension-function-catalog
description	Guides machine-readable function catalogs for DuckDB extensions, including a `functions.yaml` source-of-truth pattern that can drive docs, wrappers, aliases, examples, and consistency checks. Use when an extension exposes many SQL functions or multiple wrapper surfaces.

DuckDB C Extension Function Catalog

Use this skill when the extension has enough functions that hand-maintained docs and wrappers start drifting.

Core position

Once an extension exposes more than a handful of SQL entry points, keep a machine-readable catalog. A functions.yaml-style file can become the source of truth for:

• SQL names
• kind: scalar/table/macro/aggregate
• signatures
• return types
• categories
• wrapper aliases
• docs text
• examples
• lifecycle metadata such as since or deprecated

Why this pattern helps

Without a catalog, teams often end up with inconsistent copies of the same information in:

• registration code
• README tables
• package docs
• wrapper helpers
• test fixtures

A catalog reduces drift.

Recommended metadata fields

A useful generic schema often includes:

• name
• kind
• category
• signature
• returns
• sql_aliases or wrapper aliases
• description
• examples
• since
• deprecated
• notes

Not every project needs every field, but think in that direction.

Main principles

1) Keep one canonical source of function metadata

If the extension needs generated docs or wrappers, choose one canonical catalog file and generate derivatives from it. Treat generated functions.md and functions.tsv as build artifacts, not hand-edited sources.

2) Generate human-readable outputs

Common derivatives:

• functions.md
• functions.tsv
• README tables
• R helper registration tables
• validation scripts

A good default is a small R renderer wired into make so docs can be refreshed reproducibly. Prefer the DuckHTS-style pattern where functions.yaml is stored as JSON-formatted YAML/JSON and rendered with Rscript plus jsonlite, avoiding a Python/PyYAML sidecar in R-first projects.

3) Record lifecycle metadata

The catalog is also a good place for:

• since
• experimental
• deprecated
• replacement function names

4) Keep catalog entries user-oriented

Descriptions should explain behavior, not just repeat signatures. Examples should be copyable.

5) Validate generated outputs in CI

If you generate files from the catalog, CI should detect drift. A practical workflow is:

• edit functions.yaml
• run the R renderer
• commit regenerated functions.md and functions.tsv
• have CI fail if rerendering changes tracked outputs

Good outcomes

• one source of truth
• synchronized docs and wrappers
• easier deprecation management
• cleaner README/reference tables

Anti-patterns

• hand-editing generated docs without updating the source catalog
• adding a Python/PyYAML renderer to an R-first workflow when a small Rscript renderer over JSON-formatted YAML/JSON is enough
• function names duplicated inconsistently across SQL and wrappers
• no lifecycle metadata
• examples that are not actually tested anywhere

Related skills

• DuckDB C extension API stability
• DuckDB C extension R bindings

References

• Functions YAML pattern
• Catalog generation checklist
• Example catalog source
• R generator stub