JSON laden

Der JSON-Reader von DuckDB kann die Konfigurationsflags automatisch ableiten, indem er die JSON-Datei analysiert. Das funktioniert in den meisten Fällen und sollte zuerst versucht werden. In seltenen Fällen, in denen der JSON-Reader die richtige Konfiguration nicht erkennt, können Sie den Reader manuell so einstellen, dass die Datei korrekt geparst wird.

Die Funktion read_json

read_json ist die einfachste Methode, JSON-Dateien zu laden: Die Funktion versucht automatisch, die richtige Konfiguration des JSON-Readers zu finden. Außerdem leitet sie die Spaltentypen automatisch ab. Im folgenden Beispiel verwenden wir die Datei todos.json,

SELECT *
FROM read_json('todos.json')
LIMIT 5;

userId	id	title	completed
1	1	delectus aut autem	false
1	2	quis ut nam facilis et officia qui	false
1	3	fugiat veniam minus	false
1	4	et porro tempora	true
1	5	laboriosam mollitia et enim quasi adipisci quia provident illum	false

Mit read_json können Sie auch eine persistente Tabelle erzeugen:

CREATE TABLE todos AS
    SELECT *
    FROM read_json('todos.json');
DESCRIBE todos;

column_name	column_type	null	key	default	extra
userId	UBIGINT	YES	NULL	NULL	NULL
id	UBIGINT	YES	NULL	NULL	NULL
title	VARCHAR	YES	NULL	NULL	NULL
completed	BOOLEAN	YES	NULL	NULL	NULL

Wenn wir Typen für eine Teilmenge der Spalten angeben, schließt read_json nicht angegebene Spalten aus:

SELECT *
FROM read_json(
        'todos.json',
        columns = {userId: 'UBIGINT', completed: 'BOOLEAN'}
    )
LIMIT 5;

Beachten Sie, dass nur die Spalten userId und completed angezeigt werden:

userId	completed
1	false
1	false
1	false
1	true
1	false

Mehrere Dateien können gleichzeitig gelesen werden, indem Sie ein Glob-Muster oder eine Dateiliste angeben. Weitere Informationen finden Sie im Abschnitt Mehrere Dateien.

Funktionen zum Lesen von JSON-Objekten

Die folgenden Tabellenfunktionen dienen zum Lesen von JSON:

Funktion	Beschreibung
read_json_objects(filename)	Liest ein JSON-Objekt aus filename, wobei filename auch eine Dateiliste oder ein Glob-Muster sein kann.
read_ndjson_objects(filename)	Alias für read_json_objects mit dem Parameter format auf newline_delimited.
read_json_objects_auto(filename)	Alias für read_json_objects mit dem Parameter format auf auto.

Parameter

Diese Funktionen haben die folgenden Parameter:

Name	Beschreibung	Typ	Standard
compression	Der Kompressionstyp der Datei. Standardmäßig wird er automatisch aus der Dateiendung erkannt (z. B. verwendet t.json.gz gzip, t.json none). Optionen sind none, gzip, zstd und auto_detect.	VARCHAR	auto_detect
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 ergänzt; diese Option bleibt nur aus Kompatibilitätsgründen erhalten.	BOOL	false
format	Kann eines von auto, unstructured, newline_delimited und array sein.	VARCHAR	array
hive_partitioning	Ob der Pfad als Hive-partitionierter Pfad interpretiert werden soll.	BOOL	(automatisch erkannt)
ignore_errors	Ob Parse-Fehler ignoriert werden sollen (nur möglich, wenn format newline_delimited ist).	BOOL	false
maximum_sample_files	Die maximale Anzahl von JSON-Dateien, die für die automatische Erkennung abgetastet werden.	BIGINT	32
maximum_object_size	Die maximale Größe eines JSON-Objekts (in Bytes).	UINTEGER	16777216

Der Parameter format legt fest, wie das JSON aus einer Datei gelesen wird. Mit unstructured wird das JSON der obersten Ebene gelesen, z. B. für birds.json:

{
  "duck": 42
}
{
  "goose": [1, 2, 3]
}

FROM read_json_objects('birds.json', format = 'unstructured');

werden zwei Objekte gelesen:

┌──────────────────────────────┐
│             json             │
│             json             │
├──────────────────────────────┤
│ {\n    "duck": 42\n}         │
│ {\n    "goose": [1, 2, 3]\n} │
└──────────────────────────────┘

Mit newline_delimited wird NDJSON gelesen, wobei jedes JSON durch einen Zeilenumbruch (\n) getrennt ist, z. B. für birds-nd.json:

{"duck": 42}
{"goose": [1, 2, 3]}

FROM read_json_objects('birds-nd.json', format = 'newline_delimited');

werden ebenfalls zwei Objekte gelesen:

┌──────────────────────┐
│         json         │
│         json         │
├──────────────────────┤
│ {"duck": 42}         │
│ {"goose": [1, 2, 3]} │
└──────────────────────┘

Mit array wird jedes Array-Element gelesen, z. B. für birds-array.json:

[
    {
        "duck": 42
    },
    {
        "goose": [1, 2, 3]
    }
]

FROM read_json_objects('birds-array.json', format = 'array');

werden wiederum zwei Objekte gelesen:

┌──────────────────────────────────────┐
│                 json                 │
│                 json                 │
├──────────────────────────────────────┤
│ {\n        "duck": 42\n    }         │
│ {\n        "goose": [1, 2, 3]\n    } │
└──────────────────────────────────────┘

Funktionen zum Lesen von JSON als Tabelle

DuckDB unterstützt auch das Lesen von JSON als Tabelle mit den folgenden Funktionen:

Funktion	Beschreibung
read_json(filename)	Liest JSON aus filename, wobei filename auch eine Dateiliste oder ein Glob-Muster sein kann.
read_json_auto(filename)	Alias für read_json.
read_ndjson(filename)	Alias für read_json mit dem Parameter format auf newline_delimited.
read_ndjson_auto(filename)	Alias für read_json mit dem Parameter format auf newline_delimited.

Parameter

Neben maximum_object_size, format, ignore_errors und compression haben diese Funktionen weitere Parameter:

Name	Beschreibung	Typ	Standard
auto_detect	Ob die Namen der Schlüssel und die Datentypen der Werte automatisch erkannt werden sollen	BOOL	true
columns	Ein Struct, der die Schlüsselnamen und Wertetypen in der JSON-Datei angibt (z. B. {key1: 'INTEGER', key2: 'VARCHAR'}). Ist auto_detect aktiviert, werden sie abgeleitet	STRUCT	(empty)
dateformat	Gibt das Datumsformat beim Parsen von Datumsangaben an. Siehe Datumsformat	VARCHAR	iso
maximum_depth	Maximale Verschachtelungstiefe, bis zu der die automatische Schemaerkennung Typen erkennt. Auf -1 setzen, um geschachtelte JSON-Typen vollständig zu erkennen	BIGINT	-1
records	Kann eines von auto, true, false sein	VARCHAR	auto
sample_size	Anzahl der Stichprobenobjekte für die automatische JSON-Typerkennung. Auf -1 setzen, um die gesamte Eingabedatei zu scannen	UBIGINT	20480
timestampformat	Gibt das Datumsformat beim Parsen von Zeitstempeln an. Siehe Datumsformat. Bei iso (Standard) werden ISO-8601-Zeitstempel mit Zeitzonenoffset (z. B. 2024-01-01T12:00:00+05:00) und Sekundenbruchteilen (z. B. 2024-01-01T12:00:00.123Z) automatisch als TIMESTAMP erkannt.	VARCHAR	iso
union_by_name	Ob die Schemas mehrerer JSON-Dateien vereinheitlicht werden sollen	BOOL	false
map_inference_threshold	Schwellenwert für die Anzahl der Spalten, deren Schema automatisch erkannt wird; würde die JSON-Schemaerkennung für ein Feld mit mehr Unterfeldern als diesem Schwellenwert einen Typ STRUCT ableiten, wird stattdessen ein Typ MAP abgeleitet. Auf -1 setzen, um die MAP-Ableitung zu deaktivieren.	BIGINT	200
field_appearance_threshold	Der JSON-Reader teilt die Anzahl der Vorkommen jedes JSON-Felds durch die Stichprobengröße der automatischen Erkennung. Liegt der Durchschnitt über die Felder eines Objekts unter diesem Schwellenwert, wird standardmäßig ein Typ MAP mit dem zusammengeführten Feldtyp als Wertetyp verwendet.	DOUBLE	0.1

Beachten Sie, dass DuckDB JSON-Arrays direkt in den internen Typ LIST umwandeln kann und fehlende Schlüssel zu NULL werden:

SELECT *
FROM read_json(
    ['birds1.json', 'birds2.json'],
    columns = {duck: 'INTEGER', goose: 'INTEGER[]', swan: 'DOUBLE'}
);

duck	goose	swan
42	[1, 2, 3]	NULL
43	[4, 5, 6]	3.3

DuckDB kann die Typen automatisch so erkennen:

SELECT goose, duck FROM read_json('*.json.gz');
SELECT goose, duck FROM '*.json.gz'; -- equivalent

DuckDB kann eine Vielzahl von Formaten lesen (und automatisch erkennen), angegeben mit dem Parameter format. Eine JSON-Datei, die ein array enthält, z. B.:

[
  {
    "duck": 42,
    "goose": 4.2
  },
  {
    "duck": 43,
    "goose": 4.3
  }
]

kann genauso abgefragt werden wie eine JSON-Datei mit unstructured JSON, z. B.:

{
    "duck": 42,
    "goose": 4.2
}
{
    "duck": 43,
    "goose": 4.3
}

Beide können als Tabelle gelesen werden:

SELECT
FROM read_json('birds.json');

duck	goose
42	4.2
43	4.3

Wenn Ihre JSON-Datei keine „Datensätze“ enthält, d. h. ein anderes JSON als Objekte, kann DuckDB sie trotzdem lesen. Das wird mit dem Parameter records angegeben. Der Parameter records legt fest, ob das JSON Datensätze enthält, die in einzelne Spalten entpackt werden sollen. DuckDB versucht das auch automatisch zu erkennen. Nehmen Sie zum Beispiel die folgende Datei birds-records.json:

{"duck": 42, "goose": [1, 2, 3]}
{"duck": 43, "goose": [4, 5, 6]}

SELECT *
FROM read_json('birds-records.json');

Die Abfrage ergibt zwei Spalten:

duck	goose
42	[1,2,3]
43	[4,5,6]

Sie können dieselbe Datei mit records auf false lesen und erhalten eine einzelne Spalte, ein STRUCT mit den Daten:

json
{‘duck’: 42, ‘goose’: [1,2,3]}
{‘duck’: 43, ‘goose’: [4,5,6]}

Weitere Beispiele zum Lesen komplexerer Daten finden Sie im Blogbeitrag „Shredding Deeply Nested JSON, One Vector at a Time“.

Laden mit der COPY-Anweisung und FORMAT json

Wenn die Erweiterung json installiert ist, wird FORMAT json für COPY FROM, IMPORT DATABASE sowie COPY TO und EXPORT DATABASE unterstützt. Siehe die COPY-Anweisung und die Klauseln IMPORT / EXPORT.

Standardmäßig erwartet COPY zeilengetrenntes JSON. Wenn Sie Daten lieber in ein bzw. aus einem JSON-Array kopieren möchten, können Sie ARRAY true angeben, z. B.

COPY (SELECT * FROM range(5) r(i))
TO 'numbers.json' (ARRAY true);

erzeugt die folgende Datei:

[
  {"i":0},
  {"i":1},
  {"i":2},
  {"i":3},
  {"i":4}
]

Das kann wie folgt wieder in DuckDB eingelesen werden:

CREATE TABLE numbers (i BIGINT);
COPY numbers FROM 'numbers.json' (ARRAY true);

Das Format kann automatisch erkannt werden:

CREATE TABLE numbers (i BIGINT);
COPY numbers FROM 'numbers.json' (AUTO_DETECT true);

Wir können auch eine Tabelle aus dem automatisch erkannten Schema erzeugen:

CREATE TABLE numbers AS
    FROM 'numbers.json';

Parameter

Name	Beschreibung	Typ	Standard
auto_detect	Ob die Namen der Schlüssel und die Datentypen der Werte automatisch erkannt werden sollen	BOOL	false
columns	Ein Struct, der die Schlüsselnamen und Wertetypen in der JSON-Datei angibt (z. B. {key1: 'INTEGER', key2: 'VARCHAR'}). Ist auto_detect aktiviert, werden sie abgeleitet	STRUCT	(empty)
compression	Der Kompressionstyp der Datei. Standardmäßig wird er automatisch aus der Dateiendung erkannt (z. B. verwendet t.json.gz gzip, t.json none). Optionen sind uncompressed, gzip, zstd und auto_detect.	VARCHAR	auto_detect
convert_strings_to_integers	Ob Zeichenketten, die Ganzzahlwerte darstellen, in einen numerischen Typ umgewandelt werden sollen.	BOOL	false
dateformat	Gibt das Datumsformat beim Parsen von Datumsangaben an. Siehe Datumsformat	VARCHAR	iso
filename	Ob eine zusätzliche Spalte filename ins Ergebnis aufgenommen werden soll.	BOOL	false
format	Kann eines von auto, unstructured, newline_delimited, array sein	VARCHAR	array
hive_partitioning	Ob der Pfad als Hive-partitionierter Pfad interpretiert werden soll.	BOOL	false
ignore_errors	Ob Parse-Fehler ignoriert werden sollen (nur möglich, wenn format newline_delimited ist)	BOOL	false
maximum_depth	Maximale Verschachtelungstiefe, bis zu der die automatische Schemaerkennung Typen erkennt. Auf -1 setzen, um geschachtelte JSON-Typen vollständig zu erkennen	BIGINT	-1
maximum_object_size	Die maximale Größe eines JSON-Objekts (in Bytes)	UINTEGER	16777216
records	Kann eines von auto, true, false sein	VARCHAR	records
sample_size	Anzahl der Stichprobenobjekte für die automatische JSON-Typerkennung. Auf -1 setzen, um die gesamte Eingabedatei zu scannen	UBIGINT	20480
timestampformat	Gibt das Datumsformat beim Parsen von Zeitstempeln an. Siehe Datumsformat	VARCHAR	iso
union_by_name	Ob die Schemas mehrerer JSON-Dateien vereinheitlicht werden sollen.	BOOL	false