3分钟上手！DataHub元数据Excel/CSV导入完全指南

你是否还在为元数据导入格式错误而反复调试？是否因字段不匹配导致导入失败？本文将系统讲解DataHub元数据导入模板的Excel与CSV格式规范，帮你避开90%的常见问题，实现元数据高效管理。读完本文你将掌握：标准模板下载、字段含义解析、格式校验技巧、错误排查方法四大核心技能。

模板基础架构与获取方式

DataHub提供两种元数据导入模板：Excel（.xlsx/.xlsm）和CSV（逗号分隔值）格式，分别通过ExcelSource和CSVEnricherSource模块处理。模板文件可通过以下两种方式获取：

1. 官方示例库：从项目仓库的metadata-ingestion/examples/目录下载标准模板，包含字段说明和示例数据
2. 自动生成：通过CLI命令datahub init --template excel或datahub init --template csv生成最新模板

支持的文件类型在源码中有明确定义，Excel支持.xlsx、.xlsm等格式，CSV仅支持标准逗号分隔格式：

# Excel支持格式定义
ALLOWED_EXTENSIONS = [".xlsx", ".xlsm", ".xltx", ".xltm"]
# CSV支持格式定义
SUPPORTED_FILE_TYPES: List[str] = ["csv", "tsv", "json", "parquet", "avro"]

Excel格式规范详解

工作表结构要求

Excel模板需遵循严格的工作表结构，每个工作表代表一类元数据实体（如数据集、字段、标签）。系统默认读取所有工作表，可通过active_sheet_only配置仅读取活动工作表：

# 配置示例：仅处理活动工作表
source:
  type: excel
  config:
    active_sheet_only: true
    path: ./metadata.xlsx

必选字段说明

Excel模板包含三类核心字段，在ExcelSource源码中定义了字段类型映射关系：

字段名	数据类型	描述	示例值
urn	string	实体唯一标识	urn:li:dataset:(urn:li:dataPlatform:hive,db.table,PROD)
name	string	实体名称	用户画像表
description	string	描述信息	包含用户基础属性和行为标签
type	string	实体类型	DATASET
owner	string	负责人邮箱	[e-mail]

字段类型映射逻辑通过field_type_mapping字典实现，确保Excel中的数据类型正确转换为DataHub内部类型：

field_type_mapping: Dict[str, Type] = {
    "int64": NumberTypeClass,
    "bool": BooleanTypeClass,
    "object": StringTypeClass,
    "datetime64[ns]": DateTypeClass,
    # 更多类型映射...
}

格式校验规则

导入前需通过以下规则校验Excel文件：

1. 首行必须为字段名，与模板完全一致
2. 日期字段需使用YYYY-MM-DD格式
3. 布尔值仅支持TRUE/FALSE或1/0
4. 单元格不能包含合并单元格或公式
5. 单个工作表数据量不超过10万行

CSV格式规范详解

文件结构要求

CSV文件采用纯文本格式，通过CSVEnricherSource模块处理，每个文件代表一类元数据实体。配置示例：

source:
  type: csv-enricher
  config:
    path: ./metadata.csv
    delimiter: ','
    quotechar: '"'

字段分隔与引用规则

CSV文件必须使用逗号作为分隔符，字符串字段需用双引号包裹，在csv_enricher.py中定义了读取逻辑：

# CSV文件读取代码
rows = list(csv.DictReader(f, delimiter=self.config.delimiter))

特殊字符处理示例：

• 包含逗号的字段："上海, 北京"（需用双引号包裹）
• 换行符处理：保留原始换行符，系统会自动处理
• 空值表示：使用空字符串而非NULL或NA

编码与格式要求

• 文件编码必须为UTF-8
• 行尾需使用Unix格式（\n）而非Windows格式（\r\n）
• 不支持注释行，所有行均视为数据行
• 字段顺序可任意调整，但字段名必须完整

导入流程与最佳实践

完整导入步骤

1. 准备模板：从metadata-ingestion/examples/下载最新模板
2. 填写数据：按照字段说明填写元数据，确保符合格式要求
3. 格式校验：使用Excel/CSV校验工具检查格式合法性
4. 执行导入：通过CLI命令执行导入

   datahub ingest -c ./import-recipe.yml
   

5. 验证结果：在DataHub UI中检查导入的元数据

常见问题解决

类型转换错误

错误表现：日期字段导入后显示为字符串
解决方法：确保日期格式为YYYY-MM-DD，检查Excel单元格格式是否设为"日期"类型而非"文本"类型

字段缺失错误

错误表现：Missing required field 'urn'
解决方法：检查首行字段名是否与模板完全一致，特别注意大小写和空格

编码错误

错误表现：中文显示乱码
解决方法：将CSV文件另存为UTF-8编码，Excel中需使用"UTF-8带BOM"格式

高级配置与扩展

自定义字段扩展

通过修改元数据模型支持自定义字段，在metadata-models-custom/目录下扩展实体模型：

# 自定义字段配置示例
entities:
  dataset:
    aspects:
      - name: customProperties
        fields:
          - name: sensitivity_level
            type: string
            description: 数据敏感级别

批量导入优化

对于大规模元数据导入（10万行以上），建议：

1. 拆分多个小文件（每个文件不超过5万行）
2. 使用chunk_size配置分批处理
3. 禁用实时校验提高导入速度

# 批量导入优化配置
source:
  type: excel
  config:
    path: ./large-metadata.xlsx
    chunk_size: 10000
    skip_validation: false

模板下载与资源

• 标准模板文件：metadata-ingestion/examples/metadata-template.xlsx
• CSV示例文件：metadata-ingestion/examples/metadata-sample.csv
• 完整配置指南：metadata-ingestion/recipe_overview.md
• 错误码参考：docs/troubleshooting/ingestion-errors.md

通过遵循本文档的格式规范，你可以轻松实现DataHub元数据的批量导入与管理。如有复杂场景需求，可参考源码中的ExcelSource和CSVEnricherSource模块实现自定义扩展。