Punktbefehle

Punktbefehle sind im DuckDB-CLI-Client verfügbar. Um einen dieser Befehle zu verwenden, beginnen Sie die Zeile mit einem Punkt (.), unmittelbar gefolgt vom Namen des auszuführenden Befehls. Zusätzliche Argumente werden durch Leerzeichen getrennt nach dem Befehl eingegeben. Muss ein Argument ein Leerzeichen enthalten, können einfache oder doppelte Anführungszeichen das Parameter umschließen. Punktbefehle müssen in einer einzigen Zeile stehen, und vor dem Punkt darf kein Leerraum stehen. Am Zeilenende ist kein Semikolon erforderlich. Verfügbare Befehle zeigt der Befehl .help.

Liste der Punktbefehle

Befehl	Beschreibung
.bail ⟨on/off⟩{:.language-sql .highlight}	Nach einem Fehler anhalten. Standard: off
.binary ⟨on/off⟩{:.language-sql .highlight}	Binärausgabe on oder off schalten. Standard: off
.cd ⟨DIRECTORY⟩{:.language-sql .highlight}	Arbeitsverzeichnis auf DIRECTORY ändern
.changes ⟨on/off⟩{:.language-sql .highlight}	Anzahl der durch SQL geänderten Zeilen anzeigen
.columns{:.language-sql .highlight}	Spaltenweise Darstellung der Abfrageergebnisse
.constant ⟨COLOR⟩{:.language-sql .highlight}	Setzt die Farbe der Syntaxhervorhebung für Konstanten
.constantcode ⟨CODE⟩{:.language-sql .highlight}	Setzt den Terminalcode der Syntaxhervorhebung für Konstanten
.databases{:.language-sql .highlight}	Namen und Dateien angehängter Datenbanken auflisten
.dump ⟨TABLE⟩{:.language-sql .highlight}	Datenbankinhalt als SQL ausgeben. TABLE ist ein LIKE-Muster für die auszugebenden Tabellen
.echo ⟨on/off⟩{:.language-sql .highlight}	Befehls-Echo on oder off schalten
.exit ⟨CODE⟩{:.language-sql .highlight}	Dieses Programm mit Rückgabecode CODE beenden
.headers ⟨on/off⟩{:.language-sql .highlight}	Anzeige der Kopfzeilen on oder off schalten. Gilt nicht für den duckbox-Modus
.help ⟨-all⟩ ⟨PATTERN⟩{:.language-sql .highlight}	Hilfetext für PATTERN anzeigen. Mit .help shortcuts Tastaturkürzel anzeigen
.highlight ⟨on/off⟩{:.language-sql .highlight}	Syntaxhervorhebung in der Shell on / off schalten. Siehe den Abschnitt Syntaxhervorhebung für Abfragen
.highlight_colors ⟨COMPONENT⟩ ⟨COLOR⟩{:.language-sql .highlight}	Farbe jeder Komponente konfigurieren (nur duckbox). Siehe den Abschnitt Syntaxhervorhebung für Ergebnisse
.highlight_mode ⟨mixed/dark/light⟩{:.language-sql .highlight}	Highlight-Modus umschalten. Siehe den Abschnitt Dunkler/Heller Modus
.highlight_results ⟨on/off⟩{:.language-sql .highlight}	Hervorhebung in Ergebnistabellen on / off schalten (nur duckbox). Siehe den Abschnitt Syntaxhervorhebung für Ergebnisse
.import ⟨FILE⟩ ⟨TABLE⟩{:.language-sql .highlight}	Daten aus FILE in TABLE importieren. Unterstützt die Optionen --csv, --json, --parquet
.indexes ⟨TABLE⟩{:.language-sql .highlight}	Namen der Indizes anzeigen
.keyword ⟨COLOR⟩{:.language-sql .highlight}	Setzt die Farbe der Syntaxhervorhebung für Schlüsselwörter
.keywordcode ⟨CODE⟩{:.language-sql .highlight}	Setzt den Terminalcode der Syntaxhervorhebung für Schlüsselwörter
.large_number_rendering ⟨all/footer/off⟩{:.language-sql .highlight}	Lesbare Darstellung großer Zahlen umschalten (nur duckbox, Standard: footer)
.last{:.language-sql .highlight}	Letztes Ergebnis ohne Kürzen darstellen. Nützlich zur Navigation mit dem Pager
.log ⟨FILE/off⟩{:.language-sql .highlight}	Protokollierung on oder off schalten. FILE kann stderr / stdout sein
.maxrows ⟨COUNT⟩{:.language-sql .highlight}	Setzt die maximale Anzahl darzustellender Zeilen. Nur für den duckbox-Modus
.maxwidth ⟨COUNT⟩{:.language-sql .highlight}	Setzt die maximale Breite in Zeichen. 0 entspricht der Terminalbreite. Nur für den duckbox-Modus
.mode ⟨MODE⟩ ⟨TABLE⟩{:.language-sql .highlight}	Ausgabemodus setzen
.multiline{:.language-sql .highlight}	Mehrzeilenmodus setzen (Standard)
.nullvalue ⟨STRING⟩{:.language-sql .highlight}	STRING anstelle von NULL-Werten verwenden. Standard: NULL
.once ⟨OPTIONS⟩ ⟨FILE⟩{:.language-sql .highlight}	Ausgabe nur für den nächsten SQL-Befehl nach FILE
.open ⟨OPTIONS⟩ ⟨FILE⟩{:.language-sql .highlight}	Bestehende Datenbank schließen und FILE erneut öffnen. Optionen: --new, --nofollow, --readonly, --sql
.output ⟨FILE⟩{:.language-sql .highlight}	Ausgabe nach FILE senden oder nach stdout, wenn FILE weggelassen wird
.pager ⟨OPTIONS⟩{:.language-sql .highlight}	Pager-Nutzung für die Ausgabe steuern. Siehe den Abschnitt Paging
.print ⟨STRING...⟩{:.language-sql .highlight}	Literalen STRING ausgeben
.progress_bar ⟨COMPONENT⟩ {:.language-sql .highlight}	Stile der Fortschrittsbalken-Komponenten setzen
.prompt ⟨OPTIONS⟩ ⟨CONTINUE⟩{:.language-sql .highlight}	Die Standard-Eingabeaufforderungen ersetzen
.quit{:.language-sql .highlight}	Dieses Programm beenden
.read ⟨FILE⟩{:.language-sql .highlight}	Eingabe aus FILE lesen
.rows{:.language-sql .highlight}	Zeilenweise Darstellung der Abfrageergebnisse (Standard)
.safe_mode{:.language-sql .highlight}	Aktiviert den abgesicherten Modus
.schema ⟨PATTERN⟩{:.language-sql .highlight}	Die zu PATTERN passenden CREATE-Anweisungen anzeigen
.separator ⟨COL⟩ ⟨ROW⟩{:.language-sql .highlight}	Spalten- und Zeilentrennzeichen ändern
.shell ⟨CMD⟩ ⟨ARGS...⟩{:.language-sql .highlight}	CMD mit ARGS... in einer System-Shell ausführen
.show{:.language-sql .highlight}	Aktuelle Werte verschiedener Einstellungen anzeigen
.singleline{:.language-sql .highlight}	Einzeilenmodus setzen
.startup_text ⟨none/version/all⟩{:.language-sql .highlight}	Steuert den Starttext beim Öffnen der CLI. Als erste Zeile in ~/.duckdbrc setzen
.system ⟨CMD⟩ ⟨ARGS...⟩{:.language-sql .highlight}	CMD mit ARGS... in einer System-Shell ausführen
.tables ⟨TABLE⟩{:.language-sql .highlight}	Tabellen passend zum LIKE-Muster TABLE mit Spaltennamen, Typen und Zeilenzahlen auflisten, gruppiert nach Datenbank und Schema
.timer ⟨on/off⟩{:.language-sql .highlight}	SQL-Timer on oder off schalten. Durch ; getrennte, aber nicht durch Zeilenumbruch getrennte SQL-Anweisungen werden zusammen gemessen
.width ⟨NUM1⟩ ⟨NUM2⟩ ...{:.language-sql .highlight}	Minimale Spaltenbreiten für spaltenweise Ausgabe setzen

Den Befehl .help verwenden

Der Text von .help kann gefiltert werden, indem eine Textzeichenkette als erstes Argument übergeben wird.

.help m

.maxrows COUNT           Sets the maximum number of rows for display (default: 40). Only for duckbox mode.
.maxwidth COUNT          Sets the maximum width in characters. 0 defaults to terminal width. Only for duckbox mode.
.mode MODE ?TABLE?       Set output mode

.output: Ergebnisse in eine Datei schreiben

Standardmäßig sendet die DuckDB-CLI Ergebnisse an die Standardausgabe des Terminals. Das lässt sich mit den Befehlen .output oder .once ändern. Übergeben Sie den gewünschten Ausgabepfad als Parameter. Der Befehl .once gibt nur die nächste Ergebnismenge aus und kehrt dann zur Standardausgabe zurück, .output leitet dagegen alle folgenden Ausgaben an diesen Dateipfad um. Beachten Sie, dass jedes Ergebnis die gesamte Datei an diesem Ziel überschreibt. Um zur Standardausgabe zurückzukehren, geben Sie .output ohne Dateiparameter ein.

In diesem Beispiel wird das Ausgabeformat auf markdown geändert, das Ziel als Markdown-Datei angegeben, und DuckDB schreibt die Ausgabe der SQL-Anweisung in diese Datei. Die Ausgabe wird anschließend mit .output ohne Parameter wieder auf die Standardausgabe zurückgesetzt.

.mode markdown
.output my_results.md
SELECT 'taking flight' AS output_column;
.output
SELECT 'back to the terminal' AS displayed_column;

Die Datei my_results.md enthält dann:

| output_column |
| ------------- |
| taking flight |

Das Terminal zeigt dann:

| displayed_column     |
| -------------------- |
| back to the terminal |

Ein häufiges Ausgabeformat ist CSV, also kommagetrennte Werte. DuckDB unterstützt SQL-Syntax zum Export von Daten als CSV oder Parquet, die CLI-spezifischen Befehle können aber verwendet werden, wenn stattdessen eine CSV-Datei geschrieben werden soll.

.mode csv
.once my_output_file.csv
SELECT 1 AS col_1, 2 AS col_2
UNION ALL
SELECT 10 AS col1, 20 AS col_2;

Die Datei my_output_file.csv enthält dann:

col_1,col_2
1,2
10,20

Durch Übergabe besonderer Optionen (Flags) an den Befehl .once können Abfrageergebnisse auch in eine temporäre Datei geschrieben und automatisch im Standardprogramm des Benutzers geöffnet werden. Verwenden Sie das Flag -e für eine Textdatei (geöffnet im Standard-Texteditor) oder das Flag -x für eine CSV-Datei (geöffnet im Standard-Tabellenkalkulationsprogramm). Das ist nützlich für eine genauere Prüfung von Abfrageergebnissen, besonders bei relativ großen Ergebnismengen. Der Befehl .excel entspricht .once -x.

.once -e
SELECT 'quack' AS hello;

Die Ergebnisse öffnen sich dann im Standard-Texteditor des Systems, zum Beispiel:

Tipp macOS-Benutzer können die Ergebnisse mit pbcopy in die Zwischenablage kopieren, indem sie .once verwenden, um über eine Pipe nach pbcopy auszugeben: .once |pbcopy

In Kombination mit den Optionen .headers off und .mode lines ist das besonders wirksam.

Das Datenbankschema abfragen

Alle DuckDB-Clients unterstützen das Abfragen des Datenbankschemas mit SQL, die CLI hat aber zusätzliche Punktbefehle, die das Verstehen des Inhalts einer Datenbank erleichtern. Der Befehl .tables gibt eine Liste der Tabellen in der Datenbank zurück. Ein optionales Argument filtert die Ergebnisse nach einem LIKE-Muster.

CREATE TABLE swimmers AS SELECT 'duck' AS animal;
CREATE TABLE fliers AS SELECT 'duck' AS animal;
CREATE TABLE walkers AS SELECT 'duck' AS animal;
.tables

fliers    swimmers  walkers

Um zum Beispiel nur Tabellen zu filtern, die ein l enthalten, verwenden Sie das LIKE-Muster %l%.

.tables %l%

fliers   walkers

Der Befehl .schema zeigt alle SQL-Anweisungen, mit denen das Schema der Datenbank definiert wurde.

.schema

CREATE TABLE fliers (animal VARCHAR);
CREATE TABLE swimmers (animal VARCHAR);
CREATE TABLE walkers (animal VARCHAR);

Datenbankinhalt als SQL ausgeben

Der Befehl .dump gibt den Datenbankinhalt als SQL-Anweisungen aus, einschließlich Schemadefinitionen und Daten. Das ist nützlich für Sicherungen oder die Migration von Daten.

.dump

Ein optionales Argument TABLE filtert die Ausgabe mit einem LIKE-Muster. Mehrere Muster können als zusätzliche Argumente angegeben werden.

.dump %swim%

Die Option --newlines erlaubt unescapte Zeilenumbruchzeichen in der Ausgabe:

.dump --newlines

Fortschrittsbalken

Der Fortschrittsbalken des DuckDB-CLI-Clients lässt sich über Komponenten anpassen.

Der Befehl .progress_bar unterstützt die Parameter --add und --clear zum Hinzufügen und Entfernen von Komponenten.

Einzelheiten zur konkreten Verwendung finden Sie in den folgenden Beispielen.

Die Anzeige des Fortschrittsbalkens konfigurieren

Um zu prüfen, ob der Fortschrittsbalken aktiviert ist:

SELECT * FROM duckdb_settings() WHERE name = 'enable_progress_bar';

Um die aktuelle Mindestzeit (in Millisekunden) zu prüfen, die eine Abfrage dauern muss, bevor ein Fortschrittsbalken angezeigt wird:

SELECT * FROM duckdb_settings() WHERE name = 'progress_bar_time';

Um die Mindestanzeigezeit des Fortschrittsbalkens auf 100 Millisekunden zu setzen:

SET progress_bar_time = 100;

Um diese Fortschrittsbalken-Komponente auf roten Text zu setzen, der die aktuelle Uhrzeit auf dem Fortschrittsbalken anzeigt:

.progress_bar --add "{align:right}{min_size:20}{color:red}Time: {sql:select (current_time::varchar).split('.')[1]}{color:reset} "

Befehle .progress_bar --add sind additiv; mehrere --add-Aufrufe stapeln zusätzliche Komponenten auf dem Fortschrittsbalken.

Um diese Fortschrittsbalken-Komponente auf blauen Text zu setzen, der die RAM-Nutzung des Dateicaches auf dem Fortschrittsbalken anzeigt:

.progress_bar --add "{align:right}{min_size:20}{color:blue}External Cache Usage: {sql:select format_bytes(memory_usage_bytes) from duckdb_memory() where tag='EXTERNAL_FILE_CACHE'}{color:reset};

Um alle bestehenden Fortschrittsbalken-Komponenten zurückzusetzen:

.progress_bar --clear

Syntaxhervorhebungen

Der DuckDB-CLI-Client hat eine Syntaxhervorhebung für die SQL-Abfragen und eine weitere für duckbox-formatierte Ergebnistabellen.

Die Syntaxhervorhebung für Abfragen konfigurieren

Standardmäßig enthält die Shell Unterstützung für Syntaxhervorhebung. Die Syntaxhervorhebung der CLI lässt sich mit den folgenden Befehlen konfigurieren.

Um die Hervorhebung auszuschalten:

.highlight off

Um die Hervorhebung einzuschalten:

.highlight on

Um die Farbe für die Hervorhebung von Konstanten zu konfigurieren:

.constant [red|green|yellow|blue|magenta|cyan|white|brightblack|brightred|brightgreen|brightyellow|brightblue|brightmagenta|brightcyan|brightwhite]

.constantcode ⟨terminal_code⟩

Zum Beispiel:

.constantcode 033[31m

Um die Farbe für die Hervorhebung von Schlüsselwörtern zu konfigurieren:

.keyword [red|green|yellow|blue|magenta|cyan|white|brightblack|brightred|brightgreen|brightyellow|brightblue|brightmagenta|brightcyan|brightwhite]

.keywordcode ⟨terminal_code⟩

Zum Beispiel:

.keywordcode 033[31m

Die Syntaxhervorhebung für Ergebnisse konfigurieren

Standardmäßig nimmt die Ergebnishervorhebung einige kleine Anpassungen vor:

• Fettdruck der Spaltennamen.
• NULL-Werte werden ausgegraut.
• Layoutelemente werden ausgegraut.

Die Hervorhebung jeder Komponente lässt sich mit dem Befehl .highlight_colors anpassen. Zum Beispiel:

.highlight_colors layout red
.highlight_colors column_type yellow
.highlight_colors column_name yellow bold_underline
.highlight_colors numeric_value cyan underline
.highlight_colors temporal_value red bold
.highlight_colors string_value green bold
.highlight_colors footer gray

Die Ergebnishervorhebung lässt sich mit .highlight_results off deaktivieren.

Kurzformen

Die CLI von DuckDB erlaubt Kurzformen für Punktbefehle. Sobald eine Zeichenfolge eindeutig zu einem Punktbefehl oder einem Argument vervollständigt werden kann, vervollständigt die CLI sie (still). Zum Beispiel:

.mo ma

Entspricht:

.mode markdown

Tipp Vermeiden Sie Kurzformen in SQL-Skripten, um die Lesbarkeit zu verbessern und die Skripte zukunftssicher zu machen.

Daten importieren

Der Befehl .import importiert Daten aus einer Datei in eine DuckDB-Tabelle. Er verwendet die Leserfunktionen von DuckDB (read_csv, read_json, read_parquet) und unterstützt automatische Schemaerkennung. Existiert die Zieltabelle nicht, wird sie automatisch erzeugt.

Das Dateiformat kann explizit mit --csv, --json oder --parquet angegeben werden. Wird kein Format angegeben, wird es aus der Dateierweiterung abgeleitet.

.import data.csv my_table

Zusätzliche Parameter können mit der Syntax --⟨parameter⟩ ⟨value⟩{:.language-sql .highlight} an die zugrunde liegende Leserfunktion übergeben werden:

.import data.csv my_table --delimiter "|" --header false

Um eine JSON-Datei zu importieren:

.import data.json my_table --json

Um eine Parquet-Datei zu importieren:

.import data.parquet my_table