CSV-Import

Beispiele

Die folgenden Beispiele verwenden die Datei flights.csv.

CSV-Datei vom Datenträger lesen, Optionen automatisch erkennen:

SELECT * FROM 'flights.csv';

Die Funktion read_csv mit eigenen Optionen verwenden:

SELECT *
FROM read_csv('flights.csv',
    delim = '|',
    header = true,
    columns = {
        'FlightDate': 'DATE',
        'UniqueCarrier': 'VARCHAR',
        'OriginCityName': 'VARCHAR',
        'DestCityName': 'VARCHAR'
    });

CSV von stdin lesen, Optionen automatisch erkennen:

cat flights.csv | duckdb -c "SELECT * FROM read_csv('/dev/stdin')"

CSV-Datei in eine Tabelle einlesen:

CREATE TABLE ontime (
    FlightDate DATE,
    UniqueCarrier VARCHAR,
    OriginCityName VARCHAR,
    DestCityName VARCHAR
);
COPY ontime FROM 'flights.csv';

Alternativ eine Tabelle ohne manuelles Schema mit einer CREATE TABLE ... AS SELECT-Anweisung anlegen:

CREATE TABLE ontime AS
    SELECT * FROM 'flights.csv';

Mit der FROM-first-Syntax können Sie SELECT * weglassen.

CREATE TABLE ontime AS
    FROM 'flights.csv';

CSV-Laden

CSV-Laden, also das Importieren von CSV-Dateien in die Datenbank, ist eine sehr häufige und dennoch überraschend knifflige Aufgabe. CSVs wirken oberflächlich einfach, enthalten aber oft Unstimmigkeiten, die das Laden erschweren. CSV-Dateien kommen in vielen Varianten vor, sind oft beschädigt und haben kein Schema. Der CSV-Reader muss mit all diesen Situationen zurechtkommen.

Der DuckDB-CSV-Reader kann die zu verwendenden Konfigurationsflags automatisch ableiten, indem er die CSV-Datei mit dem CSV-Sniffer analysiert. Das funktioniert in den meisten Fällen korrekt und sollte der erste Versuch sein. In seltenen Fällen, in denen der CSV-Reader die richtige Konfiguration nicht findet, können Sie den Reader manuell so einstellen, dass die CSV-Datei korrekt geparst wird. Weitere Informationen finden Sie auf der Seite zur Autoerkennung.

Parameter

Unten stehen Parameter, die Sie an die Funktion read_csv übergeben können. Wo sinnvoll, lassen sich dieselben Parameter auch an die COPY-Anweisung übergeben.

Name	Beschreibung	Typ	Standard
all_varchar	Typerkennung überspringen und annehmen, dass alle Spalten den Typ VARCHAR haben. Diese Option wird nur von der Funktion read_csv unterstützt.	BOOL	false
allow_quoted_nulls	Die Umwandlung gequoteter Werte in NULL-Werte zulassen	BOOL	true
auto_detect	CSV-Parameter automatisch erkennen.	BOOL	true
auto_type_candidates	Typen, die der Sniffer bei der Erkennung von Spaltentypen verwendet. Der Typ VARCHAR ist immer als Fallback enthalten. Siehe Beispiel.	TYPE[]	Standardtypen
buffer_size	Größe der Puffer zum Lesen von Dateien, in Bytes. Muss groß genug sein, um vier Zeilen zu fassen, und kann die Leistung deutlich beeinflussen.	BIGINT	16 * max_line_size
columns	Spaltennamen und -typen als Struct (z. B. {'col1': 'INTEGER', 'col2': 'VARCHAR'}). Diese Option deaktiviert die automatische Schemaerkennung.	STRUCT	(leer)
comment	Zeichen, das Kommentare einleitet. Zeilen, die mit einem Kommentarzeichen beginnen (optional nach Leerzeichen), werden vollständig ignoriert; andere Zeilen mit einem Kommentarzeichen werden nur bis zu diesem Punkt geparst.	VARCHAR	(leer)
compression	Verfahren zum Komprimieren von CSV-Dateien. Standardmäßig wird das anhand der Dateiendung erkannt (z. B. verwendet t.csv.gz gzip, t.csv verwendet none). Optionen sind none, gzip, zstd.	VARCHAR	auto
dateformat	Datumsformat, das beim Parsen und Schreiben von Daten verwendet wird.	VARCHAR	(leer)
date_format	Alias für dateformat; nur in der COPY-Anweisung verfügbar.	VARCHAR	(leer)
decimal_separator	Dezimaltrennzeichen für Zahlen.	VARCHAR	.
delim	Trennzeichen zwischen Spalten innerhalb einer Zeile, z. B. , ; \t. Das Trennzeichen kann bis zu 4 Bytes lang sein, z. B. 🦆. Alias für sep.	VARCHAR	,
delimiter	Alias für delim; nur in der COPY-Anweisung verfügbar.	VARCHAR	,
escape	Zeichenkette zum Escapen des quote-Zeichens innerhalb gequoteter Werte.	VARCHAR	"
encoding	Kodierung der CSV-Datei. Optionen sind utf-8, utf-16, latin-1. Nicht in der COPY-Anweisung verfügbar (die immer utf-8 verwendet).	VARCHAR	utf-8
filename	Pfad der enthaltenden Datei als Zeichenketten-Spalte namens filename zu jeder Zeile hinzufügen. Relativ- oder Absolutpfade werden je nach dem an read_csv übergebenen Pfad oder Glob-Muster zurückgegeben, nicht nur Dateinamen. Seit DuckDB v1.3.0 wird die Spalte filename automatisch als virtuelle Spalte ergänzt; diese Option bleibt nur aus Kompatibilitätsgründen.	BOOL	false
files_to_sniff	Anzahl der Dateien, die der CSV-Sniffer zur Schemaerkennung beim Lesen mehrerer Dateien verwendet. Setzen Sie den Wert auf -1, um alle Dateien zu sniffen.	BIGINT	10
force_not_null	Werte in den angegebenen Spalten nicht mit der NULL-Zeichenkette abgleichen. Ist die NULL-Zeichenkette leer (Standard), werden leere Werte als Zeichenketten der Länge null statt als NULL gelesen.	VARCHAR[]	[]
header	Die erste Zeile jeder Datei enthält die Spaltennamen.	BOOL	false
hive_partitioning	Den Pfad als Hive-partitionierten Pfad interpretieren.	BOOL	(automatisch erkannt)
ignore_errors	Alle aufgetretenen Parsefehler ignorieren.	BOOL	false
max_line_size oder maximum_line_size. Nicht in der COPY-Anweisung verfügbar.	Maximale Zeilengröße in Bytes.	BIGINT	2000000
names oder column_names	Spaltennamen als Liste. Siehe Beispiel.	VARCHAR[]	(leer)
new_line	Zeilenumbruchzeichen. Optionen sind '\r','\n' oder '\r\n'. Der CSV-Parser unterscheidet nur zwischen ein- und zweizeichenigen Zeilentrennern. Daher wird zwischen '\r' und '\n' nicht differenziert.	VARCHAR	(leer)
normalize_names	Spaltennamen normalisieren. Dabei werden alle nicht-alphanumerischen Zeichen entfernt. Spaltennamen, die reservierte SQL-Schlüsselwörter sind, erhalten den Unterstrich (_) als Präfix.	BOOL	false
null_padding	Fehlende Spalten rechts mit NULL-Werten auffüllen, wenn einer Zeile Spalten fehlen.	BOOL	false
nullstr oder null	Zeichenketten, die einen NULL-Wert darstellen.	VARCHAR oder VARCHAR[]	(leer)
parallel	Den parallelen CSV-Reader verwenden.	BOOL	true
quote	Zeichenkette zum Quoten von Werten.	VARCHAR	"
rejects_scan	Name der temporären Tabelle, in der Informationen zu fehlerhaften Scans gespeichert werden.	VARCHAR	reject_scans
rejects_table	Name der temporären Tabelle, in der Informationen zu fehlerhaften Zeilen gespeichert werden.	VARCHAR	reject_errors
rejects_limit	Obere Grenze der fehlerhaften Zeilen pro Datei, die in der Rejects-Tabelle erfasst werden. 0 bedeutet, dass kein Limit gilt.	BIGINT	0
sample_size	Anzahl der Stichprobenzeilen für die automatische Parametererkennung.	BIGINT	20480
sep	Trennzeichen zwischen Spalten innerhalb einer Zeile, z. B. , ; \t. Das Trennzeichen kann bis zu 4 Bytes lang sein, z. B. 🦆. Alias für delim.	VARCHAR	,
skip	Anzahl der Zeilen, die am Anfang jeder Datei übersprungen werden.	BIGINT	0
store_rejects	Zeilen mit Fehlern überspringen und in der Rejects-Tabelle speichern.	BOOL	false
strict_mode	Legt die Striktheit des CSV-Readers fest. Bei true wirft der Parser bei Problemen einen Fehler. Bei false versucht der Parser, strukturell fehlerhafte Dateien zu lesen. Das Lesen strukturell fehlerhafter Dateien kann Mehrdeutigkeiten verursachen; verwenden Sie diese Option daher mit Vorsicht.	BOOL	true
thousands	Zeichen zur Kennzeichnung von Tausendertrennzeichen in numerischen Werten. Es muss ein einzelnes Zeichen sein und sich von der Option decimal_separator unterscheiden.	VARCHAR	(leer)
timestampformat	Zeitstempelformat, das beim Parsen und Schreiben von Zeitstempeln verwendet wird.	VARCHAR	(leer)
timestamp_format	Alias für timestampformat; nur in der COPY-Anweisung verfügbar.	VARCHAR	(leer)
types oder dtypes oder column_types	Spaltentypen, entweder als Liste (nach Position) oder als Struct (nach Name). Siehe Beispiel.	VARCHAR[] oder STRUCT	(leer)
union_by_name	Spalten aus verschiedenen Dateien nach Spaltenname statt nach Position ausrichten. Diese Option erhöht den Speicherverbrauch.	BOOL	false

Tip Der CSV-Reader von DuckDB unterstützt die Kodierungen UTF-8 (Standard), UTF-16 und Latin-1. Für andere Kodierungen können Sie die Erweiterung encodings verwenden oder sie z. B. mit dem Kommandozeilenwerkzeug iconv umwandeln:

iconv -f ISO-8859-2 -t UTF-8 input.csv > input-utf-8.csv

auto_type_candidates im Detail

Die Option auto_type_candidates legt fest, welche Datentypen der CSV-Reader bei der Erkennung der Spaltendatentypen berücksichtigen soll. Beispiel:

SELECT * FROM read_csv('csv_file.csv', auto_type_candidates = ['BIGINT', 'DATE']);

Der Standardwert der Option auto_type_candidates ist ['NULL', 'BOOLEAN', 'BIGINT', 'DOUBLE', 'TIME', 'DATE', 'TIMESTAMP', 'VARCHAR'].

CSV-Funktionen

read_csv versucht automatisch, die richtige Konfiguration des CSV-Readers mit dem CSV-Sniffer zu ermitteln. Außerdem leitet es die Typen der Spalten automatisch ab. Hat die CSV-Datei einen Header, werden die dort gefundenen Namen als Spaltennamen verwendet. Andernfalls heißen die Spalten column0, column1, column2, .... Ein Beispiel mit der Datei flights.csv:

SELECT * FROM read_csv('flights.csv');

FlightDate	UniqueCarrier	OriginCityName	DestCityName
1988-01-01	AA	New York, NY	Los Angeles, CA
1988-01-02	AA	New York, NY	Los Angeles, CA
1988-01-03	AA	New York, NY	Los Angeles, CA

Der Pfad kann relativ (zum aktuellen Arbeitsverzeichnis) oder absolut sein.

Mit read_csv können Sie auch eine persistente Tabelle anlegen:

CREATE TABLE ontime AS
    SELECT * FROM read_csv('flights.csv');
DESCRIBE ontime;

column_name	column_type	null	key	default	extra
FlightDate	DATE	YES	NULL	NULL	NULL
UniqueCarrier	VARCHAR	YES	NULL	NULL	NULL
OriginCityName	VARCHAR	YES	NULL	NULL	NULL
DestCityName	VARCHAR	YES	NULL	NULL	NULL

SELECT * FROM read_csv('flights.csv', sample_size = 20_000);

Wenn Sie delim / sep, quote, escape oder header explizit setzen, umgehen Sie die automatische Erkennung genau dieses Parameters:

SELECT * FROM read_csv('flights.csv', header = true);

Mehrere Dateien können Sie auf einmal lesen, indem Sie ein Glob oder eine Dateiliste angeben. Weitere Informationen finden Sie im Abschnitt zu mehreren Dateien.

Schreiben mit der COPY-Anweisung

Die COPY-Anweisung lädt Daten aus einer CSV-Datei in eine Tabelle. Die Syntax entspricht der in PostgreSQL. Um die Daten mit COPY zu laden, müssen Sie zuerst eine Tabelle mit dem richtigen Schema anlegen (passend zur Reihenfolge der Spalten in der CSV-Datei und mit Typen, die zu den Werten in der CSV-Datei passen). COPY erkennt die Konfigurationsoptionen der CSV automatisch.

CREATE TABLE ontime (
    flightdate DATE,
    uniquecarrier VARCHAR,
    origincityname VARCHAR,
    destcityname VARCHAR
);
COPY ontime FROM 'flights.csv';
SELECT * FROM ontime;

flightdate	uniquecarrier	origincityname	destcityname
1988-01-01	AA	New York, NY	Los Angeles, CA
1988-01-02	AA	New York, NY	Los Angeles, CA
1988-01-03	AA	New York, NY	Los Angeles, CA

Das CSV-Format können Sie auch manuell über die Konfigurationsoptionen von COPY angeben.

CREATE TABLE ontime (flightdate DATE, uniquecarrier VARCHAR, origincityname VARCHAR, destcityname VARCHAR);
COPY ontime FROM 'flights.csv' (DELIMITER '|', HEADER);
SELECT * FROM ontime;

Fehlerhafte CSV-Dateien lesen

DuckDB unterstützt das Lesen fehlerhafter CSV-Dateien. Details finden Sie auf der Seite „Fehlerhafte CSV-Dateien lesen“.

Reihenfolgeerhaltung

Der CSV-Reader beachtet die Konfigurationsoption preserve_insertion_order, um die Einfügereihenfolge zu erhalten. Bei true (Standard) entspricht die Reihenfolge der Zeilen im Ergebnis der Reihenfolge der entsprechenden Zeilen aus der bzw. den Datei(en). Bei false ist die Reihenfolge nicht garantiert.

CSV-Dateien schreiben

DuckDB kann CSV-Dateien mit der Anweisung COPY ... TO schreiben.