Parquet-Dateien lesen und schreiben

Beispiele

Eine einzelne Parquet-Datei lesen:

SELECT * FROM 'test.parquet';

Herausfinden, welche Spalten/Typen in einer Parquet-Datei enthalten sind:

DESCRIBE SELECT * FROM 'test.parquet';

Eine Tabelle aus einer Parquet-Datei erzeugen:

CREATE TABLE test AS
    SELECT * FROM 'test.parquet';

Wenn die Datei nicht auf .parquet endet, die Funktion read_parquet verwenden:

SELECT *
FROM read_parquet('test.parq');

Mit einem Listenparameter drei Parquet-Dateien als eine Tabelle lesen:

SELECT *
FROM read_parquet(['file1.parquet', 'file2.parquet', 'file3.parquet']);

Alle Dateien lesen, die dem Glob-Muster entsprechen:

SELECT *
FROM 'test/*.parquet';

Alle Dateien lesen, die dem Glob-Muster entsprechen, und die virtuelle Spalte filename einbeziehen, die angibt, aus welcher Datei jede Zeile stammt (diese Spalte ist seit DuckDB v1.3.0 standardmäßig ohne Konfigurationsoption verfügbar):

SELECT *, filename
FROM read_parquet('test/*.parquet');

Mit einer Liste von Globs alle Parquet-Dateien aus zwei bestimmten Ordnern lesen:

SELECT *
FROM read_parquet(['folder1/*.parquet', 'folder2/*.parquet']);

Über HTTPS lesen:

SELECT *
FROM read_parquet('https://some.url/some_file.parquet');

Die Metadaten einer Parquet-Datei abfragen:

SELECT *
FROM parquet_metadata('test.parquet');

Die Datei-Metadaten einer Parquet-Datei abfragen:

SELECT *
FROM parquet_file_metadata('test.parquet');

Die Key-Value-Metadaten einer Parquet-Datei abfragen:

SELECT *
FROM parquet_kv_metadata('test.parquet');

Das Schema einer Parquet-Datei abfragen:

SELECT *
FROM parquet_schema('test.parquet');

Die Ergebnisse einer Abfrage mit der Standardkompression (Snappy) in eine Parquet-Datei schreiben:

COPY
    (SELECT * FROM tbl)
    TO 'result-snappy.parquet'
    (FORMAT parquet);

Die Ergebnisse einer Abfrage mit bestimmter Kompression und Row-Group-Größe in eine Parquet-Datei schreiben:

COPY
    (FROM generate_series(100_000))
    TO 'test.parquet'
    (FORMAT parquet, COMPRESSION zstd, ROW_GROUP_SIZE 100_000);

Den Tabelleninhalt der gesamten Datenbank als Parquet exportieren:

EXPORT DATABASE 'target_directory' (FORMAT parquet);

Parquet-Dateien

Parquet-Dateien sind komprimierte spaltenorientierte Dateien, die sich effizient laden und verarbeiten lassen. DuckDB unterstützt das effiziente Lesen und Schreiben von Parquet-Dateien sowie das Pushdown von Filtern und Projektionen in die Parquet-Scans.

Parquet-Datensätze unterscheiden sich nach Anzahl der Dateien, Größe der einzelnen Dateien, verwendetem Kompressionsalgorithmus, Row-Group-Größe usw. Das hat einen erheblichen Einfluss auf die Leistung. Details stehen im Leistungsleitfaden.

Funktion read_parquet

Funktion	Beschreibung	Beispiel
read_parquet(path_or_list_of_paths)	Parquet-Datei(en) lesen	SELECT * FROM read_parquet('test.parquet');
parquet_scan(path_or_list_of_paths)	Alias für read_parquet	SELECT * FROM parquet_scan('test.parquet');

Wenn Ihre Datei auf .parquet endet, ist die Funktionssyntax optional. Das System erkennt automatisch, dass Sie eine Parquet-Datei lesen:

SELECT * FROM 'test.parquet';

Mehrere Dateien lassen sich auf einmal lesen, indem Sie ein Glob oder eine Dateiliste angeben. Weitere Informationen finden Sie im Abschnitt Mehrere Dateien.

Parameter

Es gibt eine Reihe von Optionen, die an die Funktion read_parquet oder die COPY-Anweisung übergeben werden können.

Name	Beschreibung	Typ	Standard
binary_as_string	Von älteren Writern erzeugte Parquet-Dateien setzen das UTF8-Flag für Zeichenketten nicht korrekt, sodass String-Spalten als BLOB geladen werden. Auf true setzen, um Binärspalten als Zeichenketten zu laden.	BOOL	false
can_have_nan	Ob FLOAT- und DOUBLE-Spalten NaN-Werte enthalten dürfen. Ist die Option true, berücksichtigt der Reader NaN bei der Nutzung der Min-/Max-Statistiken einer Spalte für Filter-Pushdown, da NaN nicht geordnet vergleichbar ist.	BOOL	false
encryption_config	Konfiguration für Parquet-Verschlüsselung.	STRUCT	-
filename	Ob eine zusätzliche Spalte filename ins Ergebnis aufgenommen werden soll. Seit DuckDB v1.3.0 wird die Spalte filename automatisch als virtuelle Spalte hinzugefügt; diese Option bleibt nur aus Kompatibilitätsgründen erhalten.	BOOL	false
file_row_number	Ob die Spalte file_row_number einbezogen werden soll.	BOOL	false
hive_partitioning	Ob der Pfad als Hive-partitionierter Pfad interpretiert werden soll.	BOOL	(automatisch erkannt)
union_by_name	Ob die Spalten mehrerer Schemas nach Namen zusammengeführt werden sollen statt nach Position.	BOOL	false
schema	Ermöglicht das Lesen einer Parquet-Datei so, als hätte sie das angegebene Schema. Field IDs sind erforderlich.	MAP	NULL

Den Parameter schema verwenden

Der Parameter schema erlaubt das Lesen der Parquet-Datei mit einem bestimmten Schema. Das ist nützlich, um beim Lesen von Parquet-Dateien Spalten umzubenennen, hinzuzufügen, zu löschen, umzusortieren oder zu casten.

Für den Parameter schema sind Field IDs erforderlich. Damit sie beim Erzeugen der Parquet-Datei mit DuckDB verfügbar sind, verwenden Sie:

COPY (SELECT 42::INTEGER AS i) TO 'integers.parquet' (FIELD_IDS {i: 0});

Parquet-Dateien lesen:

SELECT *
FROM read_parquet('integers.parquet', schema = MAP {
                    0: {name: 'renamed_i', type: 'BIGINT', default_value: NULL},
                    1: {name: 'new_column', type: 'UTINYINT', default_value: 43}
                  });

┌───────────┬────────────┐
│ renamed_i │ new_column │
│   int64   │   uint8    │
├───────────┼────────────┤
│        42 │         43 │
└───────────┴────────────┘

Der Parameter schema lässt sich nicht mit union_by_name = true kombinieren.

Partielles Lesen

DuckDB unterstützt Projektions-Pushdown in die Parquet-Datei selbst. Beim Abfragen einer Parquet-Datei werden also nur die für die Abfrage benötigten Spalten gelesen. So lesen Sie nur den Teil der Parquet-Datei, der Sie interessiert. DuckDB erledigt das automatisch.

DuckDB unterstützt außerdem Filter-Pushdown in den Parquet-Reader. Wenn Sie einen Filter auf eine Spalte anwenden, die aus einer Parquet-Datei gescannt wird, wird der Filter in den Scan geschoben und kann sogar Teile der Datei mithilfe der eingebauten Zonemaps überspringen. Das hängt davon ab, ob Ihre Parquet-Datei Zonemaps enthält.

Filter- und Projektions-Pushdown bringen deutliche Leistungsvorteile. Mehr dazu im Blogbeitrag „Querying Parquet with Precision Using DuckDB“.

Einfügen und Sichten

Sie können die Daten auch in eine Tabelle einfügen oder direkt eine Tabelle aus der Parquet-Datei erzeugen. Dabei werden die Daten aus der Parquet-Datei geladen und in die Datenbank eingefügt:

Die Daten aus der Parquet-Datei in die Tabelle einfügen:

INSERT INTO people
    SELECT * FROM read_parquet('test.parquet');

Eine Tabelle direkt aus einer Parquet-Datei erzeugen:

CREATE TABLE people AS
    SELECT * FROM read_parquet('test.parquet');

Wenn die Daten in der Parquet-Datei bleiben sollen, Sie die Datei aber direkt abfragen möchten, können Sie eine Sicht über die Funktion read_parquet anlegen. Anschließend können Sie die Parquet-Datei wie eine eingebaute Tabelle abfragen:

Eine Sicht über die Parquet-Datei anlegen:

CREATE VIEW people AS
    SELECT * FROM read_parquet('test.parquet');

Die Parquet-Datei abfragen:

SELECT * FROM people;

In Parquet-Dateien schreiben

DuckDB unterstützt auch das Schreiben in Parquet-Dateien mit der Syntax der COPY-Anweisung. Details einschließlich aller möglichen Parameter der COPY-Anweisung stehen auf der Seite COPY-Anweisung.

Eine Abfrage in eine Snappy-komprimierte Parquet-Datei schreiben:

COPY
    (SELECT * FROM tbl)
    TO 'result-snappy.parquet'
    (FORMAT parquet);

tbl in eine zstd-komprimierte Parquet-Datei schreiben:

COPY tbl
    TO 'result-zstd.parquet'
    (FORMAT parquet, COMPRESSION zstd);

tbl in eine zstd-komprimierte Parquet-Datei mit der niedrigsten Kompressionsstufe schreiben, die die schnellste Kompression liefert:

COPY tbl
    TO 'result-zstd.parquet'
    (FORMAT parquet, COMPRESSION zstd, COMPRESSION_LEVEL 1);

In eine Parquet-Datei mit Key-Value-Metadaten schreiben:

COPY (
    SELECT
        42 AS number,
        true AS is_even
) TO 'kv_metadata.parquet' (
    FORMAT parquet,
    KV_METADATA {
        number: 'Answer to life, universe, and everything',
        is_even: 'not ''odd''' -- single quotes in values must be escaped
    }
);

In eine Parquet-v2-Datei schreiben:

COPY tbl
    TO 'result-v2.parquet'
    (FORMAT parquet, PARQUET_VERSION 'V2');

Eine CSV-Datei in eine unkomprimierte Parquet-Datei schreiben:

COPY
    'test.csv'
    TO 'result-uncompressed.parquet'
    (FORMAT parquet, COMPRESSION uncompressed);

Eine Abfrage mit zstd-Kompression und Row-Group-Größe in eine Parquet-Datei schreiben:

COPY
    (FROM generate_series(100_000))
    TO 'row-groups-zstd.parquet'
    (FORMAT parquet, COMPRESSION zstd, ROW_GROUP_SIZE 100_000);

Daten in eine LZ4-komprimierte Parquet-Datei schreiben:

COPY
    (FROM generate_series(100_000))
    TO 'result-lz4.parquet'
    (FORMAT parquet, COMPRESSION lz4);

Oder gleichwertig:

COPY
    (FROM generate_series(100_000))
    TO 'result-lz4.parquet'
    (FORMAT parquet, COMPRESSION lz4_raw);

Daten in eine Brotli-komprimierte Parquet-Datei schreiben:

COPY
    (FROM generate_series(100_000))
    TO 'result-brotli.parquet'
    (FORMAT parquet, COMPRESSION brotli);

Um die Seitengröße der Dictionary-Pages einer Parquet-Datei festzulegen, verwenden Sie die Option STRING_DICTIONARY_PAGE_SIZE_LIMIT (Standard: 1 MB):

COPY
    lineitem
    TO 'lineitem-with-custom-dictionary-size.parquet'
    (FORMAT parquet, STRING_DICTIONARY_PAGE_SIZE_LIMIT 100_000);

Mit dem Befehl EXPORT von DuckDB lässt sich eine gesamte Datenbank in eine Reihe von Parquet-Dateien exportieren. Weitere Details stehen auf der Seite „EXPORT-Anweisung“:

Den Tabelleninhalt der gesamten Datenbank als Parquet exportieren:

EXPORT DATABASE 'target_directory' (FORMAT parquet);

Verschlüsselung

DuckDB unterstützt das Lesen und Schreiben verschlüsselter Parquet-Dateien.

Unterstützte Funktionen

Die Liste der unterstützten Parquet-Funktionen steht auf der Seite „Implementation status“ der Parquet-Dokumentation.

Die Parquet-Erweiterung installieren und laden

Die Unterstützung für Parquet-Dateien erfolgt über eine Erweiterung. Die Erweiterung parquet ist in fast allen Clients gebündelt. Wenn Ihr Client die Erweiterung parquet nicht mitbringt, muss sie separat installiert werden:

INSTALL parquet;