Repository navigation
Make the example functions self-documenting in duckdb_functions() - #173
Open
rustyconover wants to merge 1 commit into
Open
rustyconover wants to merge 1 commit into
rustyconover wants to merge 1 commit into
Conversation
Register the example scalar functions through CreateScalarFunctionInfo with a FunctionDescription attached, so that duckdb_functions() reports a description, real parameter names, a runnable example and a category for each one. The plain RegisterFunction(ScalarFunction) overload has nowhere to put this metadata, so every extension copied from this template starts out undocumented in the catalog. Also assert the metadata in the SQL test and document the pattern in the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
rustyconover
marked this pull request as ready for review
September 20, 2026 16:16
Tmonster
added a commit
to samansmink/extension-template
that referenced
this pull request
Sep 22, 2026
Install an AWS SDK HttpClientFactory (modeled on duckdb-aws PR duckdb#173) whose client forwards every request to HTTPUtil, so Glue API calls use DuckDB's proxy / certificate settings and appear in the HTTP log (CALL enable_logging('HTTP')). Requests go through HTTPUtil::Request so DuckDB's retry and logging apply, and the calling ClientContext is passed via a thread-local scope around each Glue API call so the log lands on the right connection. The 'glue_network_calls_via_duckdb' setting (session aware) switches back to the SDK's own transport. Aws::InitAPI and the factory registration now happen at extension load. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AoxZFk3q1KdM3vWEaMuDn5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
I loaded all 346 extensions in the community-extensions catalog and diffed
duckdb_functions()before and afterLOAD:descriptioncol0,col1rather than real namesThat last row is the interesting one. Settings hit 100% not because their authors are more diligent, but because
DBConfig::AddExtensionOption(name, description, ...)takes the description as a required positional argument — you cannot register an undocumented setting. Meanwhileloader.RegisterFunction(ScalarFunction), the overload this template uses and therefore the one nearly every extension uses, has nowhere to put a description at all.The template is the highest-leverage place to fix this: it's what almost every extension author starts from.
What changed
RegisterFunction(ScalarFunction)becomesRegisterFunction(CreateScalarFunctionInfo)with aFunctionDescriptionattached.on_conflictis set explicitly because that's whatRegisterFunction(ScalarFunction)does internally; without it the registration would default toERROR_ON_CONFLICTand the template's behaviour would quietly change.Three files, no submodule pin changes:
src/waddle_extension.cpp— both example functions now register with a description, parameter names, an example and a category.test/sql/waddle.test— asserts the metadata reaches the catalog, including thatparameters[1]isnameand notcol0.docs/README.md— a short### Documenting your functionssubsection.CreateAggregateFunctionInfoandCreateTableFunctionInfocarry the samedescriptionsfield; the README says so, though the template has no aggregate or table function example to convert.Payoff
duckdb_functions()stops being a list of names and becomes a usable interface. Anything introspecting a DuckDB instance to discover what it can call — a user who just ranINSTALL foo FROM community, tooling, or an agent — gets parameter names, a one-line summary and a runnable example instead ofcol0andNULL.