Python嵌套JSON列表导入ClickHouse时嵌套字段插入报错求解

问题根源 #

你遇到的KeyError: 'fields:customfield_12251'是因为ClickHouse的JSONEachRow格式默认只会解析顶级JSON字段，无法直接识别嵌套在子对象里的字段（比如fields.customfield_12251或resolution.description），除非你的表结构提前适配了嵌套结构，或者你先把数据扁平化处理。

方案1：适配嵌套结构定义ClickHouse表 #

如果想保留原始的嵌套数据结构，需要在ClickHouse中用Nested类型或带点分隔符的字段名来定义表结构，让ClickHouse能正确映射JSON中的嵌套字段：

方式A：使用点分隔的字段名（简单直接） #

创建表时，用字段名.子字段名的格式定义嵌套字段：

CREATE TABLE jira_issues
(
    key String,
    id String,
    `fields.customfield_12251` Nullable(String),
    `fields.customfield_12250` Nullable(String),
    `fields.resolution.description` Nullable(String),
    `fields.resolution.name` Nullable(String)
    -- 按需添加其他需要的字段
) ENGINE = MergeTree()
ORDER BY key;

这种方式下，JSONEachRow会自动识别点分隔的字段路径，匹配JSON中的嵌套结构，直接插入即可，无需修改Python数据。

方式B：使用Nested结构体类型（适合复杂嵌套） #

如果嵌套层级多或字段数量多，可以用Nested类型定义结构化的字段：

CREATE TABLE jira_issues
(
    key String,
    id String,
    fields Nested(
        customfield_12251 Nullable(String),
        customfield_12250 Nullable(String),
        resolution Nested(
            description String,
            name String,
            id String
        )
        -- 按需添加其他fields下的字段
    )
) ENGINE = MergeTree()
ORDER BY key;

这种方式下，插入时直接传入原始的嵌套JSON数据即可，ClickHouse会自动解析到对应的Nested结构体中。

方案2：在Python中扁平化嵌套数据 #

如果不想修改ClickHouse表结构，或者需要把嵌套字段转为顶级字段，可以先在Python中处理数据，将嵌套字段提取到顶级层级：

# 扁平化处理原始results数据
flattened_data = []
for issue in results:
    # 复制顶级字段（排除fields）
    flat_item = {k: v for k, v in issue.items() if k != 'fields'}
    # 展开fields下的所有字段
    flat_item.update(issue['fields'])
    # 展开resolution下的字段（如果存在且非空）
    if 'resolution' in flat_item and flat_item['resolution'] is not None:
        res = flat_item.pop('resolution')
        flat_item['resolution_description'] = res['description']
        flat_item['resolution_name'] = res['name']
        flat_item['resolution_id'] = res['id']
    flattened_data.append(flat_item)

# 插入处理后的数据
ch_client.execute(f'SET input_format_skip_unknown_fields=1;')
ch_client.execute(f'INSERT INTO {table} FORMAT JSONEachRow', flattened_data)

处理后的数据会把fields.customfield_12251转为顶级字段customfield_12251，resolution.description转为resolution_description，直接匹配ClickHouse表中的顶级字段即可。

注意事项 #

• input_format_skip_unknown_fields=1仅用于跳过表中不存在的字段，无法解决嵌套字段的映射问题，必须保证表结构和插入数据的字段路径/层级匹配。
• 如果嵌套字段中有Null值，需要在ClickHouse表中对应字段定义为Nullable类型，避免插入失败。

内容的提问来源于stack exchange，提问作者Dmitri