在 Snowflake 中使用 Apache Iceberg™ 表和 Snowflake Open Catalog 时进行故障排除

以下场景可以帮助您排查在 Snowflake 中使用 Apache Iceberg™ 表与 Snowflake Open Catalog 时可能发生的问题。

您无法为 Open Catalog 创建目录集成

本部分描述了在为 Open Catalog 创建目录集成时，如何进行故障排除。

要进行故障排除，请识别在目录集成创建失败时您在 SQL 输出中收到的错误消息。

错误

 
SQL Execution Error: Cannot create catalog integration <catalog_integration_name> due to error: Unable to process: Unable to find
warehouse <catalog_name>. Check the REST configuration and ensure the warehouse name '<catalog_name>' matches the Polaris catalog
name.

原因

您在目录集成中为 CATALOG_NAME 参数指定的 <open_catalog_name> 与您为 CATALOG_URI 参数指定的 <polaris_account_url> 中 Open Catalog 账户中的任何外部目录名称不匹配。

解决方案

为 CATALOG_NAME 参数更新 <open_catalog_name>，以完全匹配 Open Catalog 中外部目录的名称，然后尝试再次创建目录集成。如果您还没有创建外部目录，请按照 创建目录 中的说明进行操作。

重要

<open_catalog_name> 区分大小写。

错误

 
SQL Execution Error: User provided authentication credentials are invalid for catalog integration <catalog_integration_name> due
to error: Malformed request: unauthorized_client: The client is not authorized.

原因

您在目录集成中指定的 OAuth 令牌无效。

解决方案

确保您在目录集成中为 OAUTH_CLIENT_ID 和 OAUTH_CLIENT_SECRET 指定的值是现有服务连接的有效值。要验证，请将这些值与您在 配置服务连接 时保存的服务凭据值进行比较。如果它们不匹配，请更新值以使其匹配。

您无法创建 Snowflake 管理的表

本部分描述了在创建 Snowflake 管理的表时，如何进行故障排除。

要进行故障排除，请识别在创建表时失败时您在 SQL 输出中收到的错误消息。

错误

 
SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The Snowflake service
connection associated with the Polaris catalog integration does not have the required privileges to send notifications. The
minimum required privileges are TABLE_CREATE, TABLE_WRITE_PROPERTIES, TABLE_DROP, NAMESPACE_CREATE, and NAMESPACE_DROP.

原因

您要连接到的外部目录的目录角色没有必要的权限，无法向 Open Catalog 发送通知。

解决方案

向外部目录的目录角色授予以下所有权限，以更新目录角色：

  • TABLE_CREATE

  • TABLE_WRITE_PROPERTIES

  • TABLE_DROP

  • NAMESPACE_CREATE

  • NAMESPACE_DROP

目录角色的更新位置取决于是在目录、命名空间还是在表级别应用授权。请参阅适用于您的目录角色的过程：

错误

 
SQL Execution Error: Failed to access the REST endpoint of catalog integration <catalog_integration_name> with error: Unable to
process: Failed to get subscoped credentials: Error assuming AWS_ROLE:
User: <IAM_user_arn> is not authorized to perform: sts:AssumeRole on resource: <S3_role_arn>. Check the accessibility of the REST
catalog URI or warehouse.

原因

外部目录的 AWS IAM 用户无法承担具有 S3 访问权限的角色。

解决方案

修改 AWS 中的策略文档，以允许 Open Catalog 账户的 IAM 用户承担具有 S3 桶访问权限的角色。要修改策略文档，您需要更新 AWS 中的 IAM 角色。有关详细信息，请参阅 检索 Snowflake Open Catalo 账户的 AWS IAM 用户，然后 向 IAM 用户授予桶对象访问权限。

请记住，策略文档必须包括外部卷和 Open Catalog 中外部目录的 IAM 用户 ARN 和外部 ID。在以下示例策略文档中，请注意以下值：

  • arn:aws:iam::111111111111:user/----0000-s 是外部卷的 STORAGE_AWS_IAM_USER_ARN。

  • arn:aws:iam::222222222222:user/----0000-s 是 Snowflake Open Catalog 中外部目录的 IAM 用户 ARN。

  • Iceberg_table_external_id 是外部卷的 STORAGE_AWS_EXTERNAL_ID，也是 Open Catalog 中外部目录的外部 ID。

    {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": [
               "arn:aws:iam::111111111111:user/----0000-s",
               "arn:aws:iam::222222222222:user/----0000-s"
            ]
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "iceberg_table_external_id"
           }
         }
       }
     ]
   }

错误

 
SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The associated Polaris
catalog cannot be of type INTERNAL.

原因

您正在尝试将 Snowflake 管理的表同步到 Open Catalog 中的内部目录。您只能将 Snowflake 管理的表同步到 Open Catalog 中的外部目录。

解决方案

您无法将现有的内部目录更新为外部目录，因此您必须创建一个新的外部目录：

  1. 遵循 创建目录 中的说明，在 Open Catalog 账户中创建外部目录。在创建目录时，请确保 External 切换已启用。

  2. 将目录集成中 CATALOG_NAME 参数的 <open_catalog_name> 更新为您创建的外部目录的名称。

错误

 
SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: SQL Execution Error:
Resource on the REST endpoint of catalog integration CATINT is forbidden due to error: Forbidden: Invalid locations '[<path to metadata file>]'
for identifier '<identifier>': <path to metadata file> is not in the list of allowed locations: [<list of allowed locations>].

原因

您要创建的表的元数据文件路径不在您的外部云提供商允许的位置列表中。因此，Open Catalog 无法访问表的元数据文件。

解决方案

确保元数据文件位置位于服务管理员在 Open Catalog 中所建目录的默认基本位置的文件路径下，或者如果适用，则位于任何其他允许的位置下。如需允许的位置列表，请在 Open Catalog 中选择目录，并参考 Locations 字段。

您无法在指定 CATALOG_SYNC 参数时更改 Iceberg 表

本部分描述了在更改 CATALOG_SYNC 参数时，如何进行故障排除。

要进行故障排除，请识别在表更改失败时您在 SQL 输出中收到的错误消息。

错误

 
SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The Snowflake service
connection associated with the Polaris catalog integration does not have the required privileges to send notifications. The minimum
required privileges are TABLE_CREATE, TABLE_WRITE_PROPERTIES, TABLE_DROP, NAMESPACE_CREATE, and NAMESPACE_DROP.

原因

您要连接到的外部目录的目录角色没有必要的权限，无法向 Open Catalog 发送通知。

解决方案

将以下所有权限授予外部目录的目录角色：

  • TABLE_CREATE

  • TABLE_WRITE_PROPERTIES

  • TABLE_DROP

  • NAMESPACE_CREATE

  • NAMESPACE_DROP

目录角色的更新位置取决于其授权是应用于目录、命名空间还是表级别。请参阅适用于您的目录角色的过程：

错误

 
SQL Execution Error: Failed to access the REST endpoint of catalog integration <catalog_integration_name> with error: Unable to
process: Failed to get subscoped credentials: Error assuming AWS_ROLE:
User: <IAM_user_arn> is not authorized to perform: sts:AssumeRole on resource: <S3_role_arn>. Check the accessibility of the REST
catalog URI or warehouse.

原因

外部目录的 AWS IAM 用户没有权限访问 S3 桶对象。

解决方案

修改 AWS 中的策略文档，以允许 Open Catalog 账户的 IAM 用户访问 S3 桶中的对象。要修改策略文档，您需要更新 AWS 中的 IAM 角色。有关详细信息，请参阅 检索 Polaris Open Catalog 账户的 AWS IAM 用户，然后 向 IAM 用户授予桶对象访问权限。

请记住，策略文档必须包括外部卷和 Open Catalog 中外部目录的 IAM 用户 ARN 和外部 ID。在以下示例策略文档中，请注意以下值：

  • arn:aws:iam::111111111111:user/----0000-s 是外部卷的 STORAGE_AWS_IAM_USER_ARN

  • arn:aws:iam::222222222222:user/----0000-s 是 Snowflake Open Catalog 中外部目录的 IAM 用户 ARN。

  • Iceberg_table_external_id 是外部卷的 STORAGE_AWS_EXTERNAL_ID，也是 Open Catalog 中外部目录的外部 ID。

    {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": [
               "arn:aws:iam::111111111111:user/----0000-s",
               "arn:aws:iam::222222222222:user/----0000-s"
            ]
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "iceberg_table_external_id"
           }
         }
       }
     ]
   }

错误

 
SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The associated Polaris
catalog cannot be of type INTERNAL.

原因

您正在尝试将 Snowflake 管理的 Iceberg 表同步到 Open Catalog 中内部目录的目录集成。您只能将 Snowflake 管理的 Iceberg 表同步到 Open Catalog 中的外部目录。

解决方案

您无法将现有的内部目录更新为外部目录，因此您必须创建一个新的外部目录：

  1. 遵循 创建目录 中的说明，在 Open Catalog 账户中创建外部目录。在创建目录时，请确保 External 切换已启用。

  2. 将目录集成中 CATALOG_NAME 参数的 open_catalog_name 更新为您创建的外部目录的名称。

错误

 
SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: SQL Execution Error:
Resource on the REST endpoint of catalog integration CATINT is forbidden due to error: Forbidden: Invalid locations '[<path to metadata file>]'
for identifier '<identifier>': <path to metadata file> is not in the list of allowed locations: [<list of allowed locations>].

原因

您要创建的表的元数据文件路径不在您的外部云提供商允许的位置列表中。因此，Open Catalog 无法访问表的元数据文件。

解决方案

确保元数据文件位置位于服务管理员在 Open Catalog 中所建目录的默认基本位置的文件路径下，或者如果适用，则位于任何其他允许的位置下。对于允许的位置列表，请在 Open Catalog 中选择目录，并参考 Locations 字段。