企业官网建设流程全解析

DataHub DynamoDB 元数据摄取进阶配置指南：schema_sampling_size 与 include_table_item 实战解析

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub

本指南围绕 DataHub 的dynamodb摄取模块（type: dynamodb）展开，重点讲解官方文档中两个用于提升表结构（Schema）推断质量的高级配置项——schema_sampling_size与include_table_item，并给出完整的 Recipe 示例、底层源码实现原理与排障建议。读完本文，你将掌握如何通过调整采样规模、指定代表性数据项，让 DataHub 从 DynamoDB 表中抽取到更全面、更准确的字段级元数据，并理解这些配置在 dynamodb.py 中的真实执行逻辑。

模块能力一览

在深入配置之前，先明确dynamodb模块的整体能力边界。官方文档指出：请以上方 "Important Capabilities"（重要能力）表格作为判断功能支持情况及是否需要额外配置的唯一依据（对应 dynamodb_post.md）。

结合 README.md，该模块覆盖以下核心元数据实体：

• Data Platform："dynamodb"映射为 DataHub 的 dataPlatform 实体；
• DynamoDB Table：映射为 DataHub 的 Dataset 实体，包含表名、所在区域、Schema 字段（属性名与类型）；
• 同时支持容器（Container）概念、标签（Tags）提取以及有状态摄取（Stateful Ingestion）下的陈旧实体删除检测。

从源码能力声明（dynamodb.py）可以看到两个附加能力：

• Platform Instance：默认以 AWS 账户 ID（Account ID）作为 platform instance；
• Tags：通过extract_table_tags可选开启，将 DynamoDB 表标签提取为 DataHub 标签。

前提条件与 IAM 权限

使用本模块前，请先确认满足 dynamodb_pre.md 中的前提：

1. 在 AWS 账户中为用户附加AmazonDynamoDBReadOnlyAccess策略，并创建 API Access Key 与 Secret；
2. 所需的最小权限集合如下：

dynamodb:ListTables dynamodb:DescribeTable dynamodb:Scan dynamodb:ListTagsOfResource

其中：

• dynamodb:Scan为必需：因为 DynamoDB 的DescribeTable不返回 Schema 信息，连接器必须通过扫描表并采样部分数据来推断 Schema；
• dynamodb:ListTagsOfResource仅当启用extract_table_tags时才需要，用于提取 DynamoDB 表标签。

重要变更提醒（Breaking Change）

自v0.13.3起，aws_region为必填项。连接器不再遍历所有 AWS 区域，而只使用 Recipe 中指定的区域。因此每个region对应一次摄取运行。

基础 Recipe 骨架

dynamodb_recipe.yml 给出了一个可直接运行的基线配置：

source: type: dynamodb config: aws_access_key_id: "${AWS_ACCESS_KEY_ID}" aws_secret_access_key: "${AWS_SECRET_ACCESS_KEY}" aws_region: "${AWS_REGION}" sink: # sink configs

AWS 凭证通过环境变量注入，避免明文写入配置文件。在此基础上，接下来围绕两个 Schema 推断相关的高级配置展开。

使用schema_sampling_size控制采样规模

配置说明

DynamoDB 是 NoSQL 数据库，同一张表的不同 Item（行）可能拥有不同的属性（列）。为了推断表的 Schema，连接器默认对每张表采样 100 个 Item。如果你需要更全面的 Schema 覆盖，可以通过schema_sampling_size调整采样数量：

source: type: dynamodb config: aws_access_key_id: "${AWS_ACCESS_KEY_ID}" aws_secret_access_key: "${AWS_SECRET_ACCESS_KEY}" aws_region: "${AWS_REGION}" # Sample 500 items instead of default 100 schema_sampling_size: 500

源码级原理

在 dynamodb.py 中，schema_sampling_size的类型为PositiveInt，默认值100，语义为"从每张表采样的 Item 数量，用于 Schema 推断，决定扫描多少数据来确定表结构"。

实际的扫描逻辑在construct_schema_from_dynamodb（dynamodb.py）中实现，其核心机制为：

1. 通过 boto3 的scanPaginator 对表执行分页扫描；
2. PaginationConfig中MaxItems取schema_sampling_size的值，PageSize固定为常量PAGE_SIZE = 100（dynamodb.py）；
3. 逐页取出 Item，交给construct_schema_from_items→append_schema累积出属性路径（field path）与类型统计。

当MaxItems大于PageSize时，分页迭代器会返回MaxItems / PageSize个页面，直到采满指定数量。也就是说，schema_sampling_size本质上是"最多扫描多少个 Item 用于 Schema 推断"的上限。

性能权衡警告

源码在schema_sampling_size > PAGE_SIZE时会写入一条报告信息（dynamodb.py）：

"High schema_sampling_size increases DynamoDB read capacity consumption and ingestion time."

即：过大的采样值会显著增加 DynamoDB 读取容量（RCU）消耗并拖慢摄取耗时。因此建议根据表数据的属性多样性与规模合理取值，不要盲目调大。

使用include_table_item注入代表性数据

配置说明

如果表中存在一些最具代表性字段的 Item，可以使用include_table_item选项，以 DynamoDB 格式提供这些 Item 的主键列表。连接器在扫描表时，会在基于schema_sampling_size（默认 100）采样的 Item 之外，额外将这些指定 Item 纳入 Schema 推断。

官方文档以 AWS DynamoDB 开发者指南示例表与数据 为例：假设账户在us-west-2区域有一张Reply表，使用由Id与ReplyDateTime组成的复合主键，则可通过include_table_item纳入 2 个指定 Item：

source: type: dynamodb config: aws_access_key_id: "${AWS_ACCESS_KEY_ID}" aws_secret_access_key: "${AWS_SECRET_ACCESS_KEY}" aws_region: "${AWS_REGION}" # The table name should be in the format of region.table_name # The primary keys should be in the DynamoDB format include_table_item: us-west-2.Reply: [ { "ReplyDateTime": { "S": "2015-09-22T19:58:22.947Z" }, "Id": { "S": "Amazon DynamoDB#DynamoDB Thread 1" }, }, { "ReplyDateTime": { "S": "2015-10-05T19:58:22.947Z" }, "Id": { "S": "Amazon DynamoDB#DynamoDB Thread 2" }, }, ]

配置要点：

• 键名格式：region.table_name，与模块生成的 dataset 命名规则一致（见下文"表名与过滤"）；
• 主键格式：必须使用 DynamoDB 的 AttributeValue 格式（{ "属性类型": "值" }，如"S"表示字符串、"N"表示数值）；
• 复合主键：若表使用分区键 + 排序键的复合主键，则每个 Item 需同时提供分区键与排序键；
• 数量上限：每个region.table的主键列表最多 100 条（Recipe 注释与源码常量MAX_PRIMARY_KEYS_SIZE = 100一致）。

源码级原理

include_table_item在 dynamodb.py 中定义为Optional[Dict[str, List[Dict]]]，语义为"用户希望纳入 Schema 的、以 DynamoDB 格式表示的表 Item 主键列表，若为复合主键则分区键与排序键均需提供"。

其执行路径为include_table_item_to_schema（dynamodb.py），且在分页扫描之前调用：

1. 在配置字典中查找region.table_name是否存在；
2. 若主键列表长度超过MAX_PRIMARY_KEYS_SIZE（100），只处理前 100 个并输出日志提示；
3. 通过dynamodb_client.batch_get_item按主键批量取回 Item；
4. 将取回的 Item 并入 Schema 累积结构，后续扫描到的采样 Item 会继续叠加统计。

这意味着include_table_item与schema_sampling_size是叠加关系：指定主键的 Item 是"确定性纳入"，采样的 Item 是"统计性纳入"，两者共同决定最终推断出的字段集合。

使用场景

• 表中大部分 Item 字段稀疏，仅有少数 Item 携带了"稀有但重要"的属性，直接随机采样容易漏掉这些字段；
• 需要确保某些关键列（如Null值、嵌套 Map/List 结构）稳定出现在 Schema 中；
• 复合主键表希望显式指定多组主键值来覆盖不同字段形态。

Schema 推断与类型映射的底层机制

理解上面两个配置项后，有必要了解 Schema 最终如何生成，以便判断采样结果对元数据质量的实际影响。

属性类型 → DataHub 字段类型映射

在 dynamodb.py 中定义了两张映射表：

DynamoDB 类型 → 原生类型名称（native data type）：

DynamoDB 类型 → DataHub SchemaFieldDataType：

嵌套结构处理

append_schema（dynamodb.py）会递归展开 Map 类型：Map 内的每个键会以父字段.子字段的形式（分隔符FIELD_DELIMITER = "."）生成扁平化字段路径。若同一字段路径在不同 Item 中出现不同 DynamoDB 类型，该字段会被标记为mixed；若某个 Item 中该属性为Null，字段会被标记为可空（nullable）。

集成测试（test_dynamodb.py）中的Location表数据即覆盖了复合主键、List（contactNumbers）与多层嵌套 Map（services.hours.open）等场景，用于验证嵌套结构推断的正确性。

字段数量上限与降采样

采样得到的字段可能很多，源码提供了第三个相关配置max_schema_size（默认300，dynamodb.py）：当推断出的字段数超过该阈值时，连接器会按字段出现频率降序排序并截断到 300 个，同时在 dataset 的自定义属性中写入schema.downsampled=True与schema.totalFields=<实际总数>，便于在 DataHub UI 中识别降采样发生（dynamodb.py）。若你的表字段极度稀疏且大量字段低频出现，适当调大schema_sampling_size或借助include_table_item提升高频字段占比，有助于避免关键字段被截断。

主键标注

construct_schema_metadata（dynamodb.py）从DescribeTable的KeySchema中提取主键信息：分区键（HASH）标注为Partition Key，排序键（RANGE）标注为Sort Key，写入 dataset 自定义属性；对应字段的nullable被强制设为false，并汇总到 Schema 的primaryKeys列表。

表名格式、过滤与附带元数据

表名（dataset 命名）规则

在 dynamodb.py 中，dataset 名称统一为region.table_name（例如us-west-2.Reply）。这解释了为什么include_table_item与table_pattern都使用region.table格式。

表过滤

table_pattern（dynamodb.py）基于正则的AllowDenyPattern，用于过滤要摄取的表，匹配对象同样是region.table格式；被过滤的表会记录在报告中（report_dropped）。

附带元数据

每个被摄取的 Dataset 会携带以下信息：

• 自定义属性：table.arn（表 ARN）与table.totalItems（ItemCount），取自DescribeTable响应（dynamodb.py）；
• 平台实例：默认取 Table ARN 中的 AWS 账户 ID 作为platform_instance（dynamodb.py）；
• 域（Domain）：通过domain配置以正则模式为表分配 domain；
• AWS 标签：启用extract_table_tags后，通过list_tags_of_resource读取表标签并转换为Key:Value形式的 DataHub 标签。注意源码明确提示：标签以OVERWRITE（覆盖）模式写入，会替换掉包括 UI 手工添加或修改在内的既有标签，请谨慎使用（dynamodb.py）。若list_tags_of_resource失败（如缺少 IAM 权限），摄取不会中断，仅产生一条 warning 报告（dynamodb.py）。

限制说明（Limitations）

模块行为受 DynamoDB 源 API、权限及平台暴露的元数据约束。具体而言：

• Schema 依赖扫描采样而非元数据 API：由于DescribeTable不提供属性清单，Schema 推断结果取决于采样数据，天然可能遗漏低频字段——这正是schema_sampling_size与include_table_item存在的意义；
• 区域必填且单次摄取仅覆盖一个区域（v0.13.3 起），多区域需多次运行或并行 Pipeline；
• 主键列表数量上限：每个表通过include_table_item最多指定 100 个主键；
• 对于不支持的或需要条件开启的功能，请参考能力表格中的说明。

故障排查（Troubleshooting）

官方文档给出了排障的基本路线：若摄取失败，首先验证凭证、权限、连通性与范围过滤（scope filters），然后查看摄取日志中的源相关错误，并据此调整配置（dynamodb_post.md）。

结合源码可进一步细化排查清单：

报告（Report）中除了标准的有状态摄取与分类报告外，还包括filtered（被table_pattern过滤的表）与各类 warning（类型无法映射、Schema 过大降采样、标签提取失败等），可作为日志之外的结构化排障入口（dynamodb.py）。

总结

schema_sampling_size与include_table_item是 DataHub DynamoDB 连接器中控制 Schema 推断质量的两个互补手段：前者决定随机采样的规模上限，后者保证指定主键的代表性 Item 一定被纳入。二者叠加，再配合max_schema_size上限与table_pattern过滤，即可在摄取成本与字段覆盖之间取得平衡。相关实现细节可进一步查阅 dynamodb.py、data_reader.py 以及集成测试 test_dynamodb.py 与单元测试 test_dynamodb.py，官方文档完整版位于 dynamodb 文档目录。

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub