Profiling

Profiling ist entscheidend, um zu verstehen, warum bestimmte Abfragen bestimmte Leistungseigenschaften zeigen. DuckDB enthält mehrere eingebaute Funktionen für das Query-Profiling; diese Seite beschreibt sie. Ein übergeordnetes Beispiel zur Verwendung von EXPLAIN finden Sie auf der Seite „Abfragepläne untersuchen“.

Anweisungen

Die Anweisung `EXPLAIN`

Ein erster Schritt beim Profiling einer Abfrage kann die Betrachtung des Abfrageplans sein. Die Anweisung EXPLAIN zeigt den Abfrageplan und beschreibt, was intern geschieht.

Die Anweisung `EXPLAIN ANALYZE`

Der Abfrageplan hilft Entwicklern, die Leistungseigenschaften der Abfrage zu verstehen. Häufig müssen jedoch auch die Leistungszahlen einzelner Operatoren und die Kardinalitäten betrachtet werden, die sie durchlaufen. Die Anweisung EXPLAIN ANALYZE liefert genau das: Sie gibt den Abfrageplan formatiert aus und führt die Abfrage zusätzlich aus. So erhalten Sie die tatsächlichen Laufzeitwerte.

Die Option `FORMAT`

Die Anweisung EXPLAIN [ANALYZE] erlaubt den Export in mehrere Formate:

text – standardmäßige ASCII-Art-Ausgabe
graphviz – erzeugt eine DOT-Ausgabe, die mit Graphviz gerendert werden kann
html – erzeugt eine HTML-Ausgabe, die mit treeflex gerendert werden kann
json – erzeugt eine JSON-Ausgabe
mermaid – erzeugt ein Mermaid-Flowchart

Um ein Format festzulegen, verwenden Sie das Tag FORMAT:

EXPLAIN (FORMAT html) SELECT 42 AS x;

Pragmas

DuckDB unterstützt mehrere Pragmas, um Profiling ein- und auszuschalten und den Detailgrad der Profiling-Ausgabe zu steuern.

Die folgenden Pragmas sind verfügbar und können mit PRAGMA oder SET gesetzt werden. Sie können auch mit RESET und dem jeweiligen Setting-Namen zurückgesetzt werden. Weitere Informationen finden Sie im Abschnitt „Profiling“ der Pragma-Seite.

Setting	Beschreibung	Standard	Optionen
`enable_profiling`, `enable_profile`	Profiling einschalten	`query_tree`	`query_tree`, `json`, `query_tree_optimizer`, `no_output`
`profiling_coverage`	Die zu profilierenden Operatoren festlegen	`SELECT`	`SELECT`, `ALL`
`profiling_output`	Eine Profiling-Ausgabedatei festlegen	Konsole	Ein Dateipfad
`profiling_mode`	Zusätzliche Optimizer- und Planner-Metriken	`standard`	`standard`, `detailed`, `all`
`configure_profiling`	Bestimmte Metriken ein- oder ausschalten	Alle Metriken außer denen des detaillierten Profilings	Ein JSON-Objekt der Form: `{"METRIC_NAME": "boolean", ...}`. (Liste aller verfügbaren Metriken)
`disable_profiling`, `disable_profile`	Profiling ausschalten

Tabellenfunktionen

Diese Tabellenfunktionen wurden in DuckDB v1.5.0 eingeführt.

DuckDB stellt Tabellenfunktionen bereit, um Profiling ein- und auszuschalten und mehrere Einstellungen in einem Aufruf zusammenzufassen.

`enable_profiling()`

Die Funktion enable_profiling() konfiguriert Profiling mit den angegebenen Optionen.

CALL enable_profiling(
    format := 'json',
    save_location := '/path/to/output.json',
    coverage := 'select',
    mode := 'standard',
    metrics := ['QUERY_NAME', 'LATENCY', 'OPERATOR_TIMING']
);

Parameter	Typ	Beschreibung
`metrics`	`LIST`, `STRUCT` oder JSON	Gibt an, welche Metriken aktiviert werden
`mode`	`VARCHAR`	Profiling-Stufe: `'standard'` oder `'detailed'`
`save_location`	`VARCHAR`	Dateipfad für die Profiling-Ausgabe
`coverage`	`VARCHAR`	Abfrageabdeckung: `'select'` oder `'all'`
`format`	`VARCHAR`	Ausgabeformat: `'query_tree'`, `'json'`, `'query_tree_optimizer'`, `'no_output'`

Alle Parameter sind optional und benannt. Sie können Metriken auch als unbenannten Parameter übergeben:

CALL enable_profiling(['LATENCY', 'RESULT_SET_SIZE']);

`disable_profiling()`

Die Funktion disable_profiling() schaltet Profiling aus.

CALL disable_profiling();

Metriken

DuckDB unterstützt eine große Zahl von Metriken, die unabhängig ein- oder ausgeschaltet werden können. Weitere Informationen und die vollständige Liste der verfügbaren Metriken finden Sie in der Metriken-Dokumentation.

Detailliertes Profiling

Wenn profiling_mode auf detailed gesetzt ist, wird ein zusätzlicher Satz Metriken aktiviert, der nur im Knoten QUERY_ROOT verfügbar ist. Dazu gehören alle Metriken der Metrikgruppe Phase timing. Jede dieser zusätzlichen Metriken kann einzeln ein- und ausgeschaltet werden.

Query-Graphen

Die Profiling-Ausgabe kann auch als Query-Graph dargestellt werden. Der Query-Graph visualisiert den Abfrageplan und zeigt die Operatoren sowie ihre Beziehungen. Der Abfrageplan muss im Format json ausgegeben und in einer Datei gespeichert werden. Nachdem die Profiling-Ausgabe in die vorgesehene Datei geschrieben wurde, kann das Python-Skript sie als Query-Graph rendern. Das Skript setzt das Python-Modul duckdb voraus. Es erzeugt eine HTML-Datei und öffnet sie in Ihrem Webbrowser.

python -m duckdb.query_graph /path/to/file.json

Notation in Abfrageplänen

In Abfrageplänen folgen die Hash-Join-Operatoren folgender Konvention: Die Probe-Seite des Joins ist der linke Operand, die Build-Seite der rechte Operand.

Join-Operatoren im Abfrageplan zeigen den verwendeten Join-Typ:

Innere Joins werden als INNER bezeichnet.
Left-Outer-Joins und Right-Outer-Joins werden als LEFT bzw. RIGHT bezeichnet.
Full-Outer-Joins werden als FULL bezeichnet.

Tip Zur Visualisierung von Abfrageplänen können Sie den DuckDB-Ausführungsplan-Visualizer der Database Systems Research Group der Universität Tübingen verwenden.