Datenimport

Diese Seite enthält Beispiele für den Datenimport nach Python mit DuckDB. Importieren Sie zuerst das DuckDB-Paket:

import duckdb

Fahren Sie anschließend mit einem der folgenden Abschnitte fort.

CSV-Dateien

CSV-Dateien können mit der Funktion read_csv gelesen werden, entweder aus Python heraus oder direkt aus SQL. Standardmäßig versucht read_csv, die CSV-Einstellungen automatisch zu erkennen, indem aus der angegebenen Datei eine Stichprobe genommen wird.

Aus einer Datei mit vollständig automatisch erkannten Einstellungen lesen:

duckdb.read_csv("example.csv")

Mehrere CSV-Dateien aus einem Ordner lesen:

duckdb.read_csv("folder/*.csv")

Optionen festlegen, wie die CSV intern formatiert ist:

duckdb.read_csv("example.csv", header = False, sep = ",")

Typen der ersten beiden Spalten überschreiben:

duckdb.read_csv("example.csv", dtype = ["int", "varchar"])

Eine CSV-Datei direkt aus SQL lesen:

duckdb.sql("SELECT * FROM 'example.csv'")

read_csv aus SQL aufrufen:

duckdb.sql("SELECT * FROM read_csv('example.csv')")

Weitere Informationen finden Sie auf der Seite CSV-Import.

Parquet-Dateien

Parquet-Dateien können mit der Funktion read_parquet gelesen werden, entweder aus Python heraus oder direkt aus SQL.

Aus einer einzelnen Parquet-Datei lesen:

duckdb.read_parquet("example.parquet")

Mehrere Parquet-Dateien aus einem Ordner lesen:

duckdb.read_parquet("folder/*.parquet")

Eine Parquet-Datei über https lesen:

duckdb.read_parquet("https://some.url/some_file.parquet")

Eine Liste von Parquet-Dateien lesen:

duckdb.read_parquet(["file1.parquet", "file2.parquet", "file3.parquet"])

Eine Parquet-Datei direkt aus SQL lesen:

duckdb.sql("SELECT * FROM 'example.parquet'")

read_parquet aus SQL aufrufen:

duckdb.sql("SELECT * FROM read_parquet('example.parquet')")

Weitere Informationen finden Sie auf der Seite Parquet laden.

JSON-Dateien

JSON-Dateien können mit der Funktion read_json gelesen werden, entweder aus Python heraus oder direkt aus SQL. Standardmäßig erkennt read_json automatisch, ob eine Datei Newline-delimited JSON oder reguläres JSON enthält, und erkennt das Schema der in der JSON-Datei gespeicherten Objekte.

Aus einer einzelnen JSON-Datei lesen:

duckdb.read_json("example.json")

Mehrere JSON-Dateien aus einem Ordner lesen:

duckdb.read_json("folder/*.json")

Eine JSON-Datei direkt aus SQL lesen:

duckdb.sql("SELECT * FROM 'example.json'")

read_json aus SQL aufrufen:

duckdb.sql("SELECT * FROM read_json('example.json')")

Direkter Zugriff auf DataFrames und Arrow-Objekte

DuckDB kann bestimmte Python-Variablen automatisch abfragen, indem Sie deren Variablennamen verwenden (als wäre es eine Tabelle). Zu diesen Typen gehören: Pandas DataFrame, Polars DataFrame, Polars LazyFrame, NumPy-Arrays, Relationen und Arrow-Objekte.

Nur Variablen, die an der Stelle des Aufrufs von sql() oder execute() für den Python-Code sichtbar sind, können auf diese Weise verwendet werden. Der Zugriff auf diese Variablen wird durch Replacement Scans ermöglicht. Um Replacement Scans vollständig zu deaktivieren, verwenden Sie:

SET python_enable_replacements = false;

DuckDB unterstützt das Abfragen mehrerer Typen von Apache-Arrow-Objekten, darunter Tables, Datasets, RecordBatchReaders und Scanner. Weitere Beispiele finden Sie in den Python-Anleitungen.

import duckdb
import pandas as pd

test_df = pd.DataFrame.from_dict({"i": [1, 2, 3, 4], "j": ["one", "two", "three", "four"]})
print(duckdb.sql("SELECT * FROM test_df").fetchall())

[(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]

DuckDB unterstützt auch das „Registrieren“ eines DataFrame- oder Arrow-Objekts als virtuelle Tabelle, vergleichbar mit einer SQL-VIEW. Das ist nützlich, wenn Sie ein DataFrame-/Arrow-Objekt abfragen, das auf andere Weise gespeichert ist (als Klassenvariable oder als Wert in einem Dictionary). Unten ein Pandas-Beispiel:

Wenn Ihr Pandas DataFrame an einem anderen Ort gespeichert ist, hier ein Beispiel für die manuelle Registrierung:

import duckdb
import pandas as pd

my_dictionary = {}
my_dictionary["test_df"] = pd.DataFrame.from_dict({"i": [1, 2, 3, 4], "j": ["one", "two", "three", "four"]})
duckdb.register("test_df_view", my_dictionary["test_df"])
print(duckdb.sql("SELECT * FROM test_df_view").fetchall())

[(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]

Sie können auch eine persistente Tabelle in DuckDB aus dem Inhalt des DataFrames (oder der View) erstellen:

# create a new table from the contents of a DataFrame
con.execute("CREATE TABLE test_df_table AS SELECT * FROM test_df")
# insert into an existing table from the contents of a DataFrame
con.execute("INSERT INTO test_df_table SELECT * FROM test_df")

Die Vorrangreihenfolge von Objekten mit demselben Namen ist wie folgt:

• Explizit über register() registrierte Objekte
• Native DuckDB-Tabellen und -Views
• Replacement Scans

Pandas DataFrames – object-Spalten

pandas.DataFrame-Spalten mit dem dtype object erfordern besondere Aufmerksamkeit, da darin Werte beliebigen Typs gespeichert werden. Um diese Spalten nach DuckDB zu konvertieren, durchlaufen wir zuerst eine Analysephase, bevor die Werte konvertiert werden. In dieser Analysephase wird eine Stichprobe aller Zeilen der Spalte analysiert, um den Zieltyp zu bestimmen. Diese Stichprobengröße ist standardmäßig auf 1000 gesetzt. Wenn der in der Analysestufe gewählte Typ falsch ist, führt das zu Invalid Input Error: Failed to cast value; in diesem Fall müssen Sie die Stichprobengröße erhöhen. Die Stichprobengröße kann über die Konfigurationsoption pandas_analyze_sample geändert werden.

# example setting the sample size to 100k
duckdb.execute("SET GLOBAL pandas_analyze_sample = 100_000")