适用于采用高性能架构的 Snowpipe Streaming 的错误日志¶

Snowpipe Streaming 的错误日志功能基于 Snowflake 现有的 DML 错误日志特性，为管理和恢复数据引入错误提供了稳健的解决方案。此功能可防止无提示数据丢失，并提高对错误数据行的可见性。打开错误日志记录后，无错误的数据会继续加载到目标表中，而处理失败的行会自动路由到专用的错误表中进行审查和恢复。

重要

错误表中存储的数据是原始载荷，即这些数据在应用任何管道转换之前，就已经发送到了 API 或 SDK。即使您的管道会丢弃或转换某些字段，完整的原始载荷仍会保留在错误表中。

概述¶

使用 Snowpipe Streaming 高性能架构时，数据处理在 Snowflake 中的服务器端进行。该高性能架构隐式地以 ON_ERROR = CONTINUE 模式运行，这意味着有效行会被接入，而有问题的行则会被跳过。

错误处理选项¶

您可以通过以下方式监控和处理引入错误：

没有错误表：

使用 getChannelStatus() 监控汇总错误计数、上次错误消息和上次错误时间戳。
查询 SNOWPIPE_STREAMING_CHANNEL_HISTORY 视图以了解历史错误趋势和模式。

这些方法能告诉您是否发生了错误以及 有多少 错误，但不会告知您 哪些行 失败了以及它们的负载。

使用错误表：

处理失败的行会自动捕获到专用错误表中。
每个错误行都包含完整的原始有效负载和详细的错误元数据。
您可以使用标准 SQL 查询、分析和重新处理失败的行。

错误表则补全了这最后一环，让您能精确地看到哪些行失败以及失败原因，从而进行全面调试和恢复。

开启错误日志记录¶

要为 Snowpipe Streaming 开启错误日志记录，请设置目标表上的 ERROR_LOGGING 属性。有关开启和配置错误日志的完整详情，请参阅为表配置 DML 错误日志。

-- For a new table:
CREATE TABLE my_streaming_table (...) ERROR_LOGGING = TRUE;

-- For an existing table:
ALTER TABLE my_streaming_table SET ERROR_LOGGING = TRUE;

启用错误日志后，同一张错误表会同时捕获来自 DML 语句和 Snowpipe Streaming 接入工作负载的错误。

查询错误表¶

要查询基表的错误表，请使用 ERROR_TABLE 表函数。有关错误表架构、访问控制和支持的操作的完整详细信息，请参阅错误日志记录和错误表。

SELECT * FROM ERROR_TABLE(my_streaming_table) ORDER BY timestamp;

结果包含引入流中每个错误行的一行。

Snowpipe Streaming 错误字段¶

Snowpipe Streaming 的错误与 DML 错误的存储方式相同，都使用同一张错误表，并包含相同的列 <label-data_load_overview_dml_error_logging>`（例如 ``timestamp`、query_id、error_code、error_metadata、error_data 等）。error_metadata 和 error_data 对象包括 Snowpipe Streaming 的其他字段，如以下部分所述。

识别 Snowpipe Streaming 错误¶

对于来自 Snowpipe Streaming 的错误，error_metadata:service 字段会填充为 snowpipe_streaming。使用此字段按来源筛选错误：

SELECT * FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming';

错误元数据详细信息¶

对于 Snowpipe Streaming 错误，error_metadata:details 对象包含以下附加字段：


字段	描述
`pipe_name`	用于引入错误行的管道的名称。
`channel_name`	用于引入错误行的通道的名称。
`offset_token_upper_bound`	包含错误行的上限偏移令牌。该行会以此偏移量令牌或更早的偏移量出现在有效负载中。
`error_data_truncated`	指示原始有效负载是否被截断以适合错误表（最大 128 MB）。
`error_data_content_type`	指示存储在 `error_data` 列中的内容类型。请参阅错误数据内容类型。

错误数据格式¶

对于 Snowpipe Streaming 错误，error_data:$1 字段包含表示错误行的原始有效负载。

如果有效负载包含无效的 UTF-8 字符，原始有效负载存储为 base64 编码的二进制字符串。

错误数据内容类型¶

error_data_content_type 字段指示遇到的错误类型并建议补救步骤。

json¶

错误行在语法上是有效的 JSON 字符串，但在将数据引入目标表时发生了逻辑错误。

常见的逻辑错误包括：

缺少不可为 null 的列：有效负载中未提供带有 NOT NULL 约束的必填列。
类型转换错误：JSON 数据类型无法转换为目标列类型。例如，字符串值 "abc" 无法转换为 NUMBER 列。
转换错误：计算管道转换表达式时出错，例如除以零。

要解决此问题，请检查 error_metadata:error_message 中的错误消息以及导致接入错误的 error_metadata:error_source 中的列名。使用 PARSE_JSON(error_data:$1) 解析有效负载，修正数据，然后将其重新插入目标表。

json-invalid¶

引入了一个语法无效的 JSON 对象。

要解决此问题，请检查 error_metadata:error_message 中的错误消息，其中包含有关语法错误的详细信息。请修正 error_data:$1 中存储的载荷，然后将其重新插入目标表。

binary-base64¶

引入了无效 UTF-8 数据。错误有效负载作为 base64 编码的二进制字符串存储在错误表中。

此错误类型通常表示上游数据源中存在格式不匹配或编码错误。

要解决此问题，请检查数据源及其生成的数据格式和编码。使用 BASE64_DECODE_STRING 函数解码 error_data:$1 中存储的载荷，以检查原始字节并识别错误的 UTF-8 序列。

错误恢复工作流程¶

以下示例演示了如何查询错误、分析错误并重新插入更正后的数据。

查询最近的错误¶

SELECT
    timestamp,
    error_code,
    error_metadata:error_message::STRING AS error_message,
    error_metadata:details:channel_name::STRING AS channel,
    error_metadata:details:pipe_name::STRING AS pipe,
    error_metadata:details:error_data_content_type::STRING AS content_type,
    error_data:"$1"::STRING AS raw_payload
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming'
  AND timestamp >= DATEADD(hour, -1, CURRENT_TIMESTAMP())
ORDER BY timestamp DESC;

分析错误分布¶

SELECT
    error_code,
    error_metadata:error_message::STRING AS error_message,
    COUNT(*) AS error_count
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming'
  AND timestamp >= DATEADD(hour, -24, CURRENT_TIMESTAMP())
GROUP BY 1, 2
ORDER BY error_count DESC;

修复并重新插入可恢复的错误¶

对于具有有效 JSON 有效负载的错误，您可以解析、修正并重新插入数据：

INSERT INTO my_streaming_table (col1, col2, col3)
SELECT
    TRY_CAST(PARSE_JSON(error_data:"$1"):col1 AS NUMBER),
    PARSE_JSON(error_data:"$1"):col2::STRING,
    TRY_CAST(PARSE_JSON(error_data:"$1"):col3 AS TIMESTAMP)
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming'
  AND error_metadata:details:error_data_content_type = 'json'
  AND timestamp >= DATEADD(hour, -24, CURRENT_TIMESTAMP());

成功重新处理错误后，您可以截断错误表：

TRUNCATE ERROR_TABLE(my_streaming_table);

计费¶

Snowpipe Streaming 引入按标准 Snowpipe Streaming 费率计费。开启错误日志记录不会改变您的引入成本。将失败的行路由到错误表不会产生额外的引入费用。

Snowflake 对错误表中存储的数据按标准存储费率收费，这与任何其他表相同。错误表存储每个失败行的原始有效负载和错误元数据。

有关 Snowpipe Streaming 成本的更多信息，请参阅 Snowpipe Streaming high-performance architecture: Understand your costs。

限制¶

错误表捕获服务器端数据处理（解析和转换）期间发生的错误。来自其他暂存区（SDK 验证、API 失败以及其他服务端异步错误）的错误不会被错误表捕获。使用 getChannelStatus() 监控服务器端异步错误。
由于存储错误信息会产生额外开销，传入行的高失败率可能会增加处理延迟。
大于 128 MB 的有效负载被截断。error_data_truncated 字段指示截断发生的时间。
错误表仅适用于 Snowpipe Streaming 高性能架构。对于经典架构，错误处理通过 SDK 在客户端进行管理。