Solução de problemas usando tabelas Apache Iceberg™ com o Snowflake Open Catalog no Snowflake¶

Os cenários a seguir podem ajudar você a solucionar problemas que podem ocorrer ao usar tabelas Apache Iceberg™ com o Snowflake Open Catalog no Snowflake.

Não é possível criar uma integração de catálogo para o Open Catalog¶

Esta seção descreve como solucionar problemas na criação de uma integração de catálogo para o Open Catalog.

Para solucionar o problema, identifique a mensagem de erro que você recebeu na saída SQL quando a criação da integração de catálogo falhou.


Erro	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.
Causa	O `<open_catalog_name>` que você especificou para o parâmetro `CATALOG_NAME` na sua integração de catálogo não corresponde ao nome de nenhum catálogo externo na conta Open Catalog no `<polaris_account_url>` que você especificou para o parâmetro `CATALOG_URI`.
Solução	Atualize `<open_catalog_name>` para o parâmetro `CATALOG_NAME` para corresponder exatamente ao nome do catálogo externo no Open Catalog e tente criar a integração do catálogo novamente. Se você ainda não criou o catálogo externo, siga as instruções em Criar um catálogo. Importante `<open_catalog_name>` diferencia maiúsculas de minúsculas.


Erro	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.
Causa	O token OAuth que você especificou na integração do catálogo não é válido.
Solução	Certifique-se de que os valores especificados para `OAUTH_CLIENT_ID` e `OAUTH_CLIENT_SECRET` na integração do seu catálogo sejam valores válidos para uma conexão de serviço existente. Para validar, compare esses valores com os valores de credencial de serviço que você salvou quando configurou a conexão de serviço. Se não corresponderem, atualize os valores para corresponder.

Não é possível criar uma tabela gerenciada pelo Snowflake¶

Esta seção descreve como solucionar problemas ao criar uma tabela gerenciada pelo Snowflake.

Para solucionar o problema, identifique a mensagem de erro que recebeu na saída SQL quando a criação da tabela falhou.


Erro	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.
Causa	A função de catálogo do catálogo externo ao qual você deseja se conectar não tem os privilégios necessários para enviar notificações ao Open Catalog.
Solução	Atualize a função de catálogo concedendo todos os seguintes privilégios à função de catálogo para seu catálogo externo: TABLE_CREATE TABLE_WRITE_PROPERTIES TABLE_DROP NAMESPACE_CREATE NAMESPACE_DROP O local onde você atualiza a função de catálogo depende se as concessões que ela possui são aplicadas no nível do catálogo, namespace ou tabela. Veja o procedimento aplicável para sua função de catálogo: Atualizar os privilégios concedidos a uma função de catálogo no nível do catálogo Atualizar os privilégios concedidos a uma função de catálogo no nível do namespace Atualizar os privilégios concedidos a uma função de catálogo no nível da tabela


Erro	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.
Causa	O usuário AWS IAM de seu catálogo externo não pode assumir a função que tem permissão para acessar o S3.
Solução	Modifique o documento de política no AWS para permitir que o usuário IAM de sua conta Open Catalog assuma a função com permissão para acessar o bucket S3. Para modificar o documento de política, você precisa atualizar a função de IAM na AWS. Para obter detalhes, consulte Recuperar o usuário AWS IAM da sua conta do Snowflake Open Catalog e, em seguida, Conceder ao usuário de IAM permissões para acessar objetos do bucket. Lembre-se de que o documento de política deve incluir o ARN de usuário IAM e ID externo para o volume externo e catálogo externo no Open Catalog. No documento de política de exemplo a seguir, observe os seguintes valores: `arn:aws:iam::111111111111:user/----0000-s` é o STORAGE_AWS_IAM_USER_ARN para o volume externo. `arn:aws:iam::222222222222:user/----0000-s` é o ARN do usuário de IAM do catálogo externo no Snowflake Open Catalog. `Iceberg_table_external_id` é o STORAGE_AWS_EXTERNAL_ID de seu volume externo e também o ID externo de seu catálogo externo no Open Catalog. { "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" } } } ] }


Erro	SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The associated Polaris catalog cannot be of type INTERNAL.
Causa	Você está tentando sincronizar uma tabela gerenciada pelo Snowflake com um catálogo interno no Open Catalog. Você só pode sincronizar uma tabela gerenciada pelo Snowflake com um catálogo externo no Open Catalog.
Solução	Você não pode atualizar um catálogo interno existente para um catálogo externo, então você deve criar um novo catálogo externo: Siga as instruções em Criar um catálogo para criar um catálogo externo na sua conta do Open Catalog. Ao criar o catálogo, certifique-se de que o botão External esteja habilitado. Atualize `<open_catalog_name>` para o parâmetro `CATALOG_NAME` na sua integração de catálogo para o nome do catálogo externo que você criou.


Erro	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>].
Causa	O caminho para o arquivo de metadados da tabela que você deseja criar não está incluído na lista de locais permitidos para seu provedor de nuvem externo. Como resultado, o Open Catalog não consegue acessar o arquivo de metadados da tabela.
Solução	Certifique-se de que o local do arquivo de metadados esteja no caminho do arquivo do local base padrão para o catálogo que o administrador do serviço criou no Open Catalog ou que esteja em qualquer um dos locais adicionais permitidos, se aplicável. Para obter a lista de locais permitidos, selecione o catálogo no Open Catalog e consulte o campo Locais.

Você não pode alterar uma tabela Iceberg ao especificar o parâmetro CATALOG_SYNC¶

Esta seção descreve como solucionar problemas para alterar o parâmetro CATALOG_SYNC.

Para solucionar o problema, identifique a mensagem de erro que recebeu na saída SQL quando a alteração da tabela falhou.


Erro	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.
Causa	A função de catálogo do catálogo externo ao qual você deseja se conectar não tem os privilégios necessários para enviar notificações ao Open Catalog.
Solução	Conceda todos os seguintes privilégios à função de catálogo para seu catálogo externo: TABLE_CREATE TABLE_WRITE_PROPERTIES TABLE_DROP NAMESPACE_CREATE NAMESPACE_DROP O local onde você atualiza a função de catálogo depende se as concessões são aplicadas no nível do catálogo, namespace ou tabela. Veja o procedimento aplicável para sua função de catálogo: Atualizar os privilégios concedidos a uma função de catálogo no nível do catálogo Atualizar os privilégios concedidos a uma função de catálogo no nível do namespace Atualizar os privilégios concedidos a uma função de catálogo no nível da tabela


Erro	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.
Causa	O usuário AWS IAM do seu catálogo externo não tem permissão para acessar objetos do bucket S3.
Solução	Modifique o documento de política na AWS para permitir que o usuário de IAM da sua conta Open Catalog acesse objetos no seu bucket S3. Para modificar o documento de política, você precisa atualizar a função de IAM na AWS. Para obter detalhes, consulte Recuperar o usuário AWS IAM da sua conta Polaris Open Catalog e, em seguida, Conceder ao usuário de IAM permissões para acessar objetos do bucket. Lembre-se de que o documento de política deve incluir o ARN de usuário IAM e ID externo para o volume externo e catálogo externo no Open Catalog. No documento de política de exemplo a seguir, observe os seguintes valores: `arn:aws:iam::111111111111:user/----0000-s` é o STORAGE_AWS_IAM_USER_ARN para o volume externo `arn:aws:iam::222222222222:user/----0000-s` é o ARN do usuário de IAM do catálogo externo no Snowflake Open Catalog. `Iceberg_table_external_id` é o STORAGE_AWS_EXTERNAL_ID de seu volume externo e também o ID externo de seu catálogo externo no Open Catalog. { "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" } } } ] }


Erro	SQL Execution Error: Failed to validate CATALOG_SYNC target '<catalog_integration_name>' due to error: The associated Polaris catalog cannot be of type INTERNAL.
Causa	Você está tentando sincronizar uma tabela Iceberg gerenciada pelo Snowflake com uma integração de catálogo para um catálogo interno no Open Catalog. Você só pode sincronizar uma tabela Iceberg gerenciada pelo Snowflake com um catálogo externo no Open Catalog.
Solução	Você não pode atualizar um catálogo interno existente para um catálogo externo, então você deve criar um novo catálogo externo: Siga as instruções em Criar um catálogo para criar um catálogo externo na sua conta do Open Catalog. Ao criar o catálogo, certifique-se de que o botão External esteja habilitado. Atualize `open_catalog_name` para o parâmetro `CATALOG_NAME` na integração do seu catálogo para o nome do catálogo externo que você criou.


Erro	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>].
Causa	O caminho para o arquivo de metadados da tabela que você deseja criar não está incluído na lista de locais permitidos para seu provedor de nuvem externo. Como resultado, o Open Catalog não consegue acessar o arquivo de metadados da tabela.
Solução	Certifique-se de que o local do arquivo de metadados esteja no caminho do arquivo do local base padrão para o catálogo que o administrador do serviço criou no Open Catalog ou que esteja em qualquer um dos locais adicionais permitidos, se aplicável. Para obter a lista de locais permitidos, selecione o catálogo no Open Catalog e consulte o campo Locations.