Pragmas

Die Anweisung PRAGMA ist eine von DuckDB aus SQLite übernommene SQL-Erweiterung. PRAGMA-Anweisungen können ähnlich wie reguläre SQL-Anweisungen ausgeführt werden. PRAGMA-Befehle können den internen Zustand der Datenbank-Engine ändern und die nachfolgende Ausführung oder das Verhalten der Engine beeinflussen.

PRAGMA-Anweisungen, die einer Option einen Wert zuweisen, können auch mit der SET-Anweisung ausgeführt werden; der Wert einer Option kann mit SELECT current_setting(option_name) abgefragt werden.

Die eingebauten Konfigurationsoptionen von DuckDB finden Sie in der Konfigurationsreferenz. DuckDB-Erweiterungen können zusätzliche Konfigurationsoptionen registrieren. Diese sind auf den jeweiligen Dokumentationsseiten der Erweiterungen beschrieben.

Diese Seite enthält die unterstützten PRAGMA-Einstellungen.

Metadaten

Schema-Informationen

Alle Datenbanken auflisten:

PRAGMA database_list;

Alle Tabellen auflisten:

PRAGMA show_tables;

Alle Tabellen mit zusätzlichen Informationen auflisten, ähnlich wie DESCRIBE:

PRAGMA show_tables_expanded;

Alle Funktionen auflisten:

PRAGMA functions;

Bei Abfragen auf nicht vorhandene Schemas erzeugt DuckDB Fehlermeldungen im Stil „Meinten Sie …?“. Wenn Tausende von Datenbanken angehängt sind, kann das Erzeugen dieser Fehler lange dauern. Um die Anzahl der Schemas zu begrenzen, die DuckDB durchsucht, verwenden Sie die Option catalog_error_max_schemas:

SET catalog_error_max_schemas = 10;

Tabelleninformationen

Informationen zu einer bestimmten Tabelle holen:

PRAGMA table_info('table_name');
CALL pragma_table_info('table_name');

table_info gibt Informationen über die Spalten der Tabelle mit dem Namen table_name zurück. Das genaue Format der zurückgegebenen Tabelle ist:

cid INTEGER,        -- cid of the column
name VARCHAR,       -- name of the column
type VARCHAR,       -- type of the column
notnull BOOLEAN,    -- if the column is marked as NOT NULL
dflt_value VARCHAR, -- default value of the column, or NULL if not specified
pk BOOLEAN          -- part of the primary key or not

Datenbankgröße

Datei- und Speichergröße jeder Datenbank holen:

PRAGMA database_size;
CALL pragma_database_size();

database_size gibt Informationen über Datei- und Speichergröße jeder Datenbank zurück. Die Spaltentypen der zurückgegebenen Ergebnisse sind:

database_name VARCHAR, -- database name
database_size VARCHAR, -- total block count times the block size
block_size BIGINT,     -- database block size
total_blocks BIGINT,   -- total blocks in the database
used_blocks BIGINT,    -- used blocks in the database
free_blocks BIGINT,    -- free blocks in the database
wal_size VARCHAR,      -- write ahead log size
memory_usage VARCHAR,  -- memory used by the database buffer manager
memory_limit VARCHAR   -- maximum memory allowed for the database

Speicherinformationen

Speicherinformationen holen:

PRAGMA storage_info('table_name');
CALL pragma_storage_info('table_name');

Dieser Aufruf gibt für die angegebene Tabelle die folgenden Informationen zurück:

Name	Typ	Beschreibung
`row_group_id`	`BIGINT`
`column_name`	`VARCHAR`
`column_id`	`BIGINT`
`column_path`	`VARCHAR`
`segment_id`	`BIGINT`
`segment_type`	`VARCHAR`
`start`	`BIGINT`	Die Start-Row-ID dieses Chunks
`count`	`BIGINT`	Die Anzahl der Einträge in diesem Speicher-Chunk
`compression`	`VARCHAR`	Für diese Spalte verwendeter Kompressionstyp – siehe den Blogbeitrag „Lightweight Compression in DuckDB“
`stats`	`VARCHAR`
`has_updates`	`BOOLEAN`
`persistent`	`BOOLEAN`	`false` bei temporärer Tabelle
`block_id`	`BIGINT`	Leer, sofern nicht persistent
`block_offset`	`BIGINT`	Leer, sofern nicht persistent

Weitere Informationen finden Sie unter Storage.

Datenbanken anzeigen

Die folgende Anweisung entspricht der Anweisung SHOW DATABASES:

PRAGMA show_databases;

Ressourcenverwaltung

Speicherlimit

Das Speicherlimit für den Buffer Manager setzen:

SET memory_limit = '1GB';

Warning Das angegebene Speicherlimit gilt nur für den Buffer Manager. Bei den meisten Abfragen verarbeitet der Buffer Manager den Großteil der Daten. Bestimmte In-Memory-Datenstrukturen wie Vektoren und Abfrageergebnisse werden jedoch außerhalb des Buffer Managers allokiert. Außerdem verwenden Aggregatfunktionen mit komplexem Zustand (z. B. list, mode, quantile, string_agg und approx-Funktionen) Speicher außerhalb des Buffer Managers. Der tatsächliche Speicherverbrauch kann daher höher sein als das angegebene Speicherlimit.

Threads

Die Anzahl der Threads für die parallele Abfrageausführung setzen:

SET threads = 4;

Kollationen

Alle verfügbaren Kollationen auflisten:

PRAGMA collations;

Die Standardkollation auf eine der verfügbaren setzen:

SET default_collation = 'nocase';

Standard-Sortierung für NULLs

Die Standard-Sortierung für NULLs auf NULLS_FIRST, NULLS_LAST, NULLS_FIRST_ON_ASC_LAST_ON_DESC oder NULLS_LAST_ON_ASC_FIRST_ON_DESC setzen:

SET default_null_order = 'NULLS_FIRST';
SET default_null_order = 'NULLS_LAST_ON_ASC_FIRST_ON_DESC';

Die Standard-Sortierrichtung der Ergebnismenge auf ASCENDING oder DESCENDING setzen:

SET default_order = 'ASCENDING';
SET default_order = 'DESCENDING';

Sortierung nach Nicht-Integer-Literalen

Standardmäßig ist die Sortierung nach Nicht-Integer-Literalen nicht erlaubt:

SELECT 42 ORDER BY 'hello world';

-- Binder Error: ORDER BY non-integer literal has no effect.

Um dieses Verhalten zu erlauben, verwenden Sie die Option order_by_non_integer_literal:

SET order_by_non_integer_literal = true;

Implizites Casting nach `VARCHAR`

Vor Version 0.10.0 erlaubte DuckDB automatisch, dass jeder Typ beim Funktionsbinden implizit nach VARCHAR gecastet wurde. Dadurch war es z. B. möglich, den Substring einer Ganzzahl ohne expliziten Cast zu berechnen. Ab Version v0.10.0 ist stattdessen ein expliziter Cast erforderlich. Um zum alten Verhalten mit implizitem Casting zurückzukehren, setzen Sie die Variable old_implicit_casting auf true:

SET old_implicit_casting = true;

Python: Alle DataFrames scannen

Vor Version 1.1.0 durchsuchte der Replacement-Scan-Mechanismus von DuckDB in Python den globalen Python-Namespace. Um zu diesem alten Verhalten zurückzukehren, verwenden Sie die folgende Einstellung:

SET python_scan_all_frames = true;

Informationen zu DuckDB

Version

DuckDB-Version anzeigen:

PRAGMA version;
CALL pragma_version();

Plattform

platform gibt eine Kennung für die Plattform zurück, für die die aktuelle DuckDB-Executable kompiliert wurde, z. B. osx_arm64. Das Format dieser Kennung entspricht dem Plattformnamen, wie im Erklärtext zum Laden von Erweiterungen beschrieben:

PRAGMA platform;
CALL pragma_platform();

User Agent

Die folgende Anweisung gibt die User-Agent-Informationen zurück, z. B. duckdb/v0.10.0(osx_arm64):

PRAGMA user_agent;

Metadateninformationen

Die folgende Anweisung gibt Informationen zum Metadatenspeicher zurück (block_id, total_blocks, free_blocks und free_list):

PRAGMA metadata_info;

Fortschrittsbalken

Fortschrittsbalken bei laufenden Abfragen anzeigen:

PRAGMA enable_progress_bar;

Oder:

PRAGMA enable_print_progress_bar;

Keinen Fortschrittsbalken für laufende Abfragen anzeigen:

PRAGMA disable_progress_bar;

Oder:

PRAGMA disable_print_progress_bar;

EXPLAIN-Ausgabe

Die Ausgabe von EXPLAIN kann so konfiguriert werden, dass nur der physische Plan angezeigt wird.

Die Standardkonfiguration von EXPLAIN:

SET explain_output = 'physical_only';

Nur den optimierten Abfrageplan anzeigen:

SET explain_output = 'optimized_only';

Alle Abfragepläne anzeigen:

SET explain_output = 'all';

Profiling

Profiling aktivieren

Die folgende Abfrage aktiviert Profiling im Standardformat query_tree. Unabhängig vom Format ist enable_profiling zwingend, um Profiling zu aktivieren.

PRAGMA enable_profiling;
PRAGMA enable_profile;

Profiling-Abdeckung

Standardmäßig ist die Profiling-Abdeckung auf SELECT gesetzt. SELECT führt den Profiler für jeden Operator im physischen Plan einer SELECT-Anweisung aus.

SET profiling_coverage = 'SELECT';

Standardmäßig gibt der Profiler keine Profiling-Informationen für andere Anweisungstypen (INSERT INTO, ATTACH usw.) aus. Um den Profiler für alle Anweisungstypen auszuführen, ändern Sie diese Einstellung auf ALL.

SET profiling_coverage = 'ALL';

Profiling-Format

Das Format von enable_profiling kann als query_tree, json, query_tree_optimizer oder no_output angegeben werden. Jedes Format schreibt seine Ausgabe in die konfigurierte Ausgabe, außer no_output.

Das Standardformat ist query_tree. Es gibt den physischen Abfrageplan und die Metriken jedes Operators im Baum aus.

SET enable_profiling = 'query_tree';

Alternativ gibt json den physischen Abfrageplan als JSON zurück:

SET enable_profiling = 'json';

Tip Zur Visualisierung von Abfrageplänen kommt der DuckDB-Ausführungsplan-Visualizer der Database Systems Research Group der Universität Tübingen in Frage.

Um den physischen Abfrageplan einschließlich Optimizer- und Planner-Metriken zurückzugeben:

SET enable_profiling = 'query_tree_optimizer';

Datenbanktreiber und andere Anwendungen können Profiling-Informationen auch über API-Aufrufe abrufen; in diesem Fall können Benutzer jede andere Ausgabe deaktivieren. Auch wenn der Parameter no_output lautet, ist wichtig, dass dies nur das Drucken in die konfigurierbare Ausgabe betrifft. Beim Zugriff auf Profiling-Informationen über API-Aufrufe bleibt es entscheidend, Profiling zu aktivieren:

SET enable_profiling = 'no_output';

Profiling-Ausgabe

Standardmäßig gibt DuckDB Profiling-Informationen auf der Standardausgabe aus. Wenn Sie die Profiling-Informationen lieber in eine Datei schreiben möchten, können Sie mit PRAGMA profiling_output einen Dateipfad angeben.

Warning Der Dateiinhalt wird bei jeder neu ausgeführten Abfrage überschrieben. Die Datei enthält daher nur die Profiling-Informationen der zuletzt ausgeführten Abfrage:

SET profiling_output = '/path/to/file.json';
SET profile_output = '/path/to/file.json';

Profiling-Modus

Standardmäßig wird nur eine begrenzte Menge an Profiling-Informationen bereitgestellt (standard).

SET profiling_mode = 'standard';

Für mehr Details verwenden Sie den detaillierten Profiling-Modus, indem Sie profiling_mode auf detailed setzen. Die Ausgabe dieses Modus umfasst das Profiling der Planner- und Optimizer-Stufen.

SET profiling_mode = 'detailed';

Um auf alle verfügbaren Metriken zuzugreifen, setzen Sie profiling_mode auf all.

SET profiling_mode = 'all';

Eigene Metriken

Standardmäßig aktiviert Profiling alle Metriken außer denen, die durch detailliertes Profiling aktiviert werden.

Mit dem PRAGMA custom_profiling_settings kann jede Metrik, einschließlich der aus dem detaillierten Profiling, einzeln aktiviert oder deaktiviert werden. Dieser PRAGMA akzeptiert ein JSON-Objekt mit Metriknamen als Schlüsseln und booleschen Werten zum Ein- oder Ausschalten. Durch diesen PRAGMA festgelegte Einstellungen überschreiben das Standardverhalten.

Note Das betrifft die Metriken nur, wenn enable_profiling auf json oder no_output gesetzt ist. query_tree und query_tree_optimizer verwenden immer einen Standardssatz von Metriken.

Im folgenden Beispiel ist die Metrik CPU_TIME deaktiviert. Die Metriken EXTRA_INFO, OPERATOR_CARDINALITY und OPERATOR_TIMING sind aktiviert.

SET custom_profiling_settings = '{"CPU_TIME": "false", "EXTRA_INFO": "true", "OPERATOR_CARDINALITY": "true", "OPERATOR_TIMING": "true"}';

Die Profiling-Dokumentation enthält eine Übersicht der verfügbaren Metriken.

Profiling deaktivieren

Um Profiling zu deaktivieren:

PRAGMA disable_profiling;
PRAGMA disable_profile;

Abfrageoptimierung

Optimizer

Um den Abfrageoptimizer zu deaktivieren:

PRAGMA disable_optimizer;

Um den Abfrageoptimizer zu aktivieren:

PRAGMA enable_optimizer;

Optimizer selektiv deaktivieren

Die Option disabled_optimizers erlaubt es, Optimierungsschritte selektiv zu deaktivieren. Um beispielsweise filter_pushdown und statistics_propagation zu deaktivieren, führen Sie aus:

SET disabled_optimizers = 'filter_pushdown,statistics_propagation';

Die verfügbaren Optimierungen können mit der Tabellenfunktion duckdb_optimizers() abgefragt werden.

Um die Optimizer wieder zu aktivieren, führen Sie aus:

SET disabled_optimizers = '';

Warning Die Option disabled_optimizers sollte nur zum Debuggen von Leistungsproblemen verwendet werden und in der Produktion vermieden werden.

Logging

Einen Pfad für das Abfrage-Logging setzen:

SET log_query_path = '/tmp/duckdb_log/';

Abfrage-Logging deaktivieren:

SET log_query_path = '';

Full-Text-Search-Indizes

Die Optionen create_fts_index und drop_fts_index sind nur verfügbar, wenn die Erweiterung fts geladen ist. Ihre Verwendung ist auf der Seite zur Full-Text-Search-Erweiterung dokumentiert.

Verifikation

Verifikation externer Operatoren

Verifikation externer Operatoren aktivieren:

PRAGMA verify_external;

Verifikation externer Operatoren deaktivieren:

PRAGMA disable_verify_external;

Verifikation der Round-Trip-Fähigkeiten

Verifikation der Round-Trip-Fähigkeiten für unterstützte logische Pläne aktivieren:

PRAGMA verify_serializer;

Verifikation der Round-Trip-Fähigkeiten deaktivieren:

PRAGMA disable_verify_serializer;

Object Cache

Caching von Objekten aktivieren, z. B. für Parquet-Metadaten:

PRAGMA enable_object_cache;

Caching von Objekten deaktivieren:

PRAGMA disable_object_cache;

Checkpointing

Kompression

Beim Checkpointing werden die vorhandenen Spaltendaten plus alle neuen Änderungen komprimiert. Es gibt einige Pragmas, die beeinflussen, welche Kompressionsfunktionen berücksichtigt werden.

Kompression erzwingen

Diese Kompressionsmethode nach Möglichkeit gegenüber jeder anderen Methode bevorzugen:

PRAGMA force_compression = 'bitpacking';

Deaktivierte Kompressionsmethoden

Keine der in der kommagetrennten Liste aufgeführten Kompressionsmethoden verwenden:

PRAGMA disabled_compression_methods = 'fsst,rle';

Checkpoint erzwingen

Wenn CHECKPOINT aufgerufen wird, obwohl keine Änderungen vorliegen, trotzdem einen Checkpoint erzwingen:

PRAGMA force_checkpoint;

Checkpoint beim Beenden

Bei erfolgreichem Beenden einen CHECKPOINT ausführen und das WAL löschen, sodass nur eine einzelne Datenbankdatei übrig bleibt:

PRAGMA enable_checkpoint_on_shutdown;

Beim Beenden keinen CHECKPOINT ausführen:

PRAGMA disable_checkpoint_on_shutdown;

Temp-Verzeichnis zum Auslagern von Daten auf die Festplatte

Standardmäßig verwendet DuckDB ein temporäres Verzeichnis namens ⟨database_file_name⟩.tmp{:.language-sql .highlight} zum Auslagern auf die Festplatte, im selben Verzeichnis wie die Datenbankdatei. Um das zu ändern, verwenden Sie:

SET temp_directory = '/path/to/temp_dir.tmp/';

Fehler als JSON zurückgeben

Die Option errors_as_json kann gesetzt werden, um Fehlerinformationen im rohen JSON-Format zu erhalten. Für bestimmte Fehler werden zusätzliche oder zerlegte Informationen bereitgestellt, die die maschinelle Verarbeitung erleichtern. Zum Beispiel:

SET errors_as_json = true;

Dann erzeugt eine Abfrage, die zu einem Fehler führt, eine JSON-Ausgabe:

SELECT * FROM nonexistent_tbl;

{
   "exception_type":"Catalog",
   "exception_message":"Table with name nonexistent_tbl does not exist!\nDid you mean \"temp.information_schema.tables\"?",
   "name":"nonexistent_tbl",
   "candidates":"temp.information_schema.tables",
   "position":"14",
   "type":"Table",
   "error_subtype":"MISSING_ENTRY"
}

IEEE-Gleitkomma-Operationssemantik

DuckDB folgt der IEEE-Gleitkomma-Operationssemantik. Um das auszuschalten, führen Sie aus:

SET ieee_floating_point_ops = false;

In diesem Fall geben Gleitkommadivisionen durch null (z. B. 1.0 / 0.0, 0.0 / 0.0 und -1.0 / 0.0) alle NULL zurück.

Abfrageverifikation (für die Entwicklung)

Die folgenden PRAGMAs werden hauptsächlich für Entwicklung und interne Tests verwendet.

Abfrageverifikation aktivieren:

PRAGMA enable_verification;

Abfrageverifikation deaktivieren:

PRAGMA disable_verification;

Erzwungene parallele Abfrageverarbeitung aktivieren:

PRAGMA verify_parallelism;

Erzwungene parallele Abfrageverarbeitung deaktivieren:

PRAGMA disable_verify_parallelism;

Blockgrößen

Beim Persistieren einer Datenbank auf die Festplatte schreibt DuckDB in eine eigene Datei, die eine Liste von Blöcken mit den Daten enthält. Bei einer Datei, die nur sehr wenig Daten enthält, z. B. einer kleinen Tabelle, ist die Standard-Blockgröße von 256 kB möglicherweise nicht ideal. Daher unterstützt das Speicherformat von DuckDB unterschiedliche Blockgrößen.

Für mögliche Blockgrößen gelten einige Einschränkungen.

Muss eine Zweierpotenz sein.
Muss größer oder gleich 16384 (16 kB) sein.
Muss kleiner oder gleich 262144 (256 kB) sein.

Sie können die Standard-Blockgröße für alle neuen DuckDB-Dateien, die von einer Instanz erstellt werden, wie folgt setzen:

SET default_block_size = '16384';

Es ist auch möglich, die Blockgröße pro Datei zu setzen; Details siehe ATTACH.