DuckDB 的 JSON 读取器可以通过分析 JSON 文件自动推断要使用的配置标志。这在大多数情况下都能正常工作，并且应该是首先尝试的选项。在极少数情况下，如果 JSON 读取器无法确定正确的配置，则可以手动配置 JSON 读取器以正确解析 JSON 文件。

The read_json 函数

The read_json 是加载 JSON 文件最简单的方法：它会自动尝试找出 JSON 读取器的正确配置。它还会自动推断列的类型。在以下示例中，我们使用 todos.json 文件，

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

我们也可以使用 read_json 来创建持久表

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

如果我们为列的子集指定类型，read_json 会排除我们未指定的列

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

请注意，此处仅显示 userId 和 completed 列

可以通过提供 glob 或文件列表一次读取多个文件。有关更多信息，请参阅多文件部分。

用于读取 JSON 对象的函数

以下表函数用于读取 JSON

参数

这些函数具有以下参数

format 参数指定如何从文件中读取 JSON。使用 unstructured 时，将读取顶层 JSON，例如对于 birds.json

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

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

将导致读取两个对象

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

使用 newline_delimited 时，将读取 NDJSON，其中每个 JSON 都由换行符 (\n) 分隔，例如对于 birds-nd.json

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

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

也将导致读取两个对象

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

使用 array 时，将读取每个数组元素，例如对于 birds-array.json

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

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

也将再次导致读取两个对象

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

将 JSON 作为表读取的函数

DuckDB 还支持使用以下函数将 JSON 作为表读取

参数

除了 maximum_object_size、format、ignore_errors 和 compression 之外，这些函数还有其他参数

请注意，DuckDB 可以将 JSON 数组直接转换为其内部 LIST 类型，并且缺失的键将变为 NULL。

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

DuckDB 可以像这样自动检测类型

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

DuckDB 可以读取（并自动检测）各种格式，这些格式由 format 参数指定。查询包含 array 的 JSON 文件，例如：

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

可以与包含 unstructured JSON 的文件以完全相同的方式进行查询，例如：

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

两者都可以作为表读取

SELECT
FROM read_json('birds.json');

如果您的 JSON 文件不包含“记录”（即除了对象之外的任何其他类型的 JSON），DuckDB 仍然可以读取它。这由 records 参数指定。records 参数指定 JSON 是否包含应解包为单独列的记录。DuckDB 也会尝试自动检测这一点。例如，以下文件 birds-records.json

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

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

查询结果是两列

您可以将 records 设置为 false 来读取相同的文件，从而获得一个单列，该列是一个包含数据的 STRUCT。

有关读取更复杂数据的其他示例，请参阅“逐向量粉碎深度嵌套 JSON”博客文章。

使用 COPY 语句和 FORMAT json 加载

当安装了 json 扩展时，COPY FROM、IMPORT DATABASE 以及 COPY TO 和 EXPORT DATABASE 都支持 FORMAT json。请参阅 COPY 语句 和 IMPORT / EXPORT 子句。

默认情况下，COPY 期望使用换行符分隔的 JSON。如果您希望将数据复制到/从 JSON 数组，可以指定 ARRAY true，例如：

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

将创建以下文件

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

可以按如下方式读回 DuckDB

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

格式可以像这样自动检测

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

我们还可以从自动检测的模式创建表

CREATE TABLE numbers AS
    FROM 'numbers.json';

参数