Dokumentation

Eine Community-Erweiterung einreichen

Community-Erweiterungen müssen öffentlich, Open Source und auf GitHub gehostet sein. Nutzer solcher Erweiterungen sind eingeladen, das jeweilige Erweiterungs-Repository zu prüfen, Feedback zu geben, die Implementierung anzusehen und Probleme zu melden.

Um eine Community-Erweiterung einzureichen, öffnen Sie bitte einen Pull Request im Community-Extensions-Repository mit einer einzelnen Datei description.yml im Ordner extensions/⟨name_of_the_extension⟩{:.language-sql .highlight}.

YAML-Deskriptor

Die Struktur des YAML-Deskriptors ist wie folgt:

Feld	Beschreibung
`extension.name`	Name der Erweiterung. Erweiterungsnamen unterscheiden nicht zwischen Groß- und Kleinschreibung, daher sind nur Kleinbuchstaben, Ziffern sowie `-` oder `_` erlaubt
`extension.description`	Kurze Beschreibung der Erweiterung
`extension.version`	Semantische Versionierung der Erweiterung
`extension.language`	`C++`, `Rust & C++`, `C++ & SQL` oder jede andere Sprachkombination, auf der der Erweiterungscode basiert
`extension.build`	Build-System, das die Erweiterung verwendet; derzeit wird nur `cmake` unterstützt
`extension.licence`	Lizenz, die für die Erweiterung gilt
`extension.maintainers`	Eine Liste der Maintainer der Erweiterung
`extension.excluded_platforms`	Optional, erlaubt anzugeben, ob bestimmte Plattformen nicht unterstützt werden
`extension.requires_toolchains`	Optional, erlaubt anzugeben, ob zusätzliche Build-Zeit-Abhängigkeiten erforderlich sind
`repo.github`	Organisationsname ‘/’ Repository-Name des öffentlichen, auf GitHub gehosteten Repositorys
`repo.ref`	Git-Ref für die Erweiterung

Diese Felder werden verwendet, um die Erweiterung zu bauen, zu testen und bereitzustellen, und können sich auch in der Dokumentation widerspiegeln.

Maintainer von Erweiterungen werden ermutigt, zwei optionale Felder im Deskriptor anzugeben, die nur in der automatisch erzeugten Dokumentation verwendet werden:

Feld	Beschreibung
`docs.hello_world`	Ein `Hello, World!`-Codebeispiel, also ein in sich geschlossenes Beispiel der Fähigkeiten einer Erweiterung
`docs.extended_description`	Zusätzlicher Kontext zur Erweiterung, relevante Links oder ein Rundgang durch die Fähigkeiten der Erweiterung

Gehostete Dokumentationsseite der Erweiterung

Jede Community-Erweiterung hat eine Dokumentationsseite unter https://duckdb.org/community_extensions/extensions/⟨extension_name⟩{:.language-sql .highlight}. Das ist zum Beispiel die Seite für h3.

Dokumentationsseiten werden aus den Feldern in der YAML-Deskriptordatei erzeugt, die Teil des Community-Extensions-Repositorys ist, sowie aus den automatisch erkannten Änderungen, die eine gegebene Erweiterung in DuckDB einführt.

Der Ablauf ist grob wie folgt:

CREATE TABLE functions_pre AS SELECT ... FROM duckdb_functions();
LOAD extension_name;
CREATE TABLE functions_post AS SELECT ... FROM duckdb_functions();
SELECT * FROM functions_post EXCEPT (FROM functions_pre) ORDER BY ...;

Das funktioniert gut, um neue Funktionen, Funktionsüberladungen, neue Einstellungen und neue Typen zu erkennen.

Die Erkennung anderer Änderungen am System (z. B. ob ein zusätzlicher Parser- oder Optimizer-Callback registriert wurde) ist machbar, aber noch nicht implementiert. Solche Angaben sollten im Feld docs.extended_description bereitgestellt werden.

Liste der Erweiterungen

Alle verfügbaren Community-Erweiterungen sind auf der Seite „Liste der Community-Erweiterungen“ aufgeführt.