验证和错误处理¶

服务器端验证（默认）¶

snowflake.validation=server_side

使用服务器端验证时，数据会发送到 Snowflake，而不进行客户端类型检查。Snowflake 后端会执行验证和模式演化，这与 COPY 和 Snowpipe 的行为一致。

• 无效记录会被捕获到与目标表关联的 Snowflake 错误表 中。

• 在此模式下，DLQ 不用于引入验证错误。请改用错误表。但是，如果进行了配置，无法被 Kafka 转换器反序列化（在到达 Snowflake 之前）的记录仍会被路由到 DLQ。

• 通过将验证工作从连接器上卸载，从而实现最大吞吐量。

• 支持默认管道和用户定义管道两种模式。

何时使用服务器端验证：

• 您希望获得最大吞吐量。

• 您可以在 Snowflake 中管理错误表。

• 您正在使用用户自定义管道进行传输中的转换。

客户端验证¶

snowflake.validation=client_side

使用客户端验证时，连接器会在将行数据发送到 Snowflake 之前验证数据类型和模式兼容性。

• 无效记录会根据 errors.tolerance 设置进行处理（参见下文）。

• 当检测到新字段时，连接器会执行模式演化 DDL。

• 支持使用死信队列 (DLQ) 来路由无效记录。

• 仅适用于默认管道 ({tableName}-STREAMING)。如果存在用户创建的管道且客户端验证已启用，则连接器会失败并返回 ERROR_5030。

何时使用客户端验证：

• 您需要一个死信队列来处理错误。

• 您正在从 v3 迁移，希望保持熟悉的行为。

• 您需要连接器来控制验证。

错误容忍度¶

errors.tolerance 属性控制连接器对错误的响应方式：

``errors.tolerance=none``（默认）

连接器任务在遇到第一个错误时失败。如果配置了 DLQ，失败记录仍会在任务中止之前发送到 DLQ。

errors.tolerance=all

连接器继续引入数据。无效记录会被路由到 DLQ（如果已配置），或者被静默丢弃。

警告

设置 errors.tolerance=all 而不配置 DLQ 主题会导致无效记录被静默丢弃。这是一种不安全的配置，可能会导致数据丢失。

死信队列 (DLQ)¶

如需配置 DLQ，请执行以下操作：

errors.deadletterqueue.topic.name=my_topic_dlq
errors.log.enable=true

以下记录会被路由到 DLQ（如果已配置）：

• **转换器错误**（两种验证模式）：无论使用哪种验证模式，无法被 Kafka 转换器反序列化的记录都会被发送到 DLQ。这适用于 ``errors.tolerance=none``（记录被推送到 DLQ，然后任务失败）和 ``errors.tolerance=all``（记录被推送到 DLQ，任务继续）两种情况。

• 客户端验证错误：当 snowflake.validation=client_side 时，未通过客户端数据转换或模式验证的记录会被发送到 DLQ。

未通过 Snowflake 服务端引入的记录不会被路由到 DLQ。请改用 错误表。

错误表（服务器端验证）¶

使用 snowflake.validation=server_side 时，未通过服务器端引入（类型不匹配、约束冲突）的记录会被记录在错误表中，以供检查和重放。

有关错误表以及 Snowpipe Streaming 错误处理的更多信息，请参阅 Error handling in Snowpipe Streaming high-performance architecture。