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 problemas, identifique a mensagem de erro que você recebeu na saída SQL quando a integração do catálogo falhou ao ser criada.

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 `WAREHOUSE` 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 `WAREHOUSE` 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 problemas, identifique a mensagem de erro que você recebeu na saída SQL quando sua tabela falhou ao ser criada.

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 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:

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 consegue assumir a função que tem permissão para acessar o S3.
Solução	Modifique o documento de política na AWS para permitir que o usuário de IAM da sua conta Open Catalog tenha a capacidade de assumir a função que tem permissão para acessar 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 do Snowflake Open Catalog e, em seguida, Conceder ao usuário de IAM permissões para acessar objetos do bucket. Tenha em mente que o documento de política deve incluir o ARN do usuário de IAM e o ID externo tanto para seu volume externo quanto para seu 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 is the STORAGE_AWS_EXTERNAL_ID` para o seu volume externo e também o ID externo para o 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" } } } ] } Copy

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 consegue assumir a função que tem permissão para acessar o S3.

Solução

Modifique o documento de política na AWS para permitir que o usuário de IAM da sua conta Open Catalog tenha a capacidade de assumir a função que tem permissão para acessar 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 do Snowflake Open Catalog e, em seguida, Conceder ao usuário de IAM permissões para acessar objetos do bucket.

Tenha em mente que o documento de política deve incluir o ARN do usuário de IAM e o ID externo tanto para seu volume externo quanto para seu 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 is the STORAGE_AWS_EXTERNAL_ID para o seu volume externo e também o ID externo para o 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"
           }
         }
       }
     ]
   }

Copy

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 a opção Externo esteja habilitada. Atualize `<open_catalog_name>` para o parâmetro `WAREHOUSE` 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: 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 a opção Externo esteja habilitada.

Atualize <open_catalog_name> para o parâmetro WAREHOUSE 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 problemas, identifique a mensagem de erro que você recebeu na saída SQL quando sua tabela falhou ao ser alterada.

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 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:

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. Tenha em mente que o documento de política deve incluir o ARN do usuário de IAM e o ID externo tanto para seu volume externo quanto para seu 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 is the STORAGE_AWS_EXTERNAL_ID` para o seu volume externo e também o ID externo para o 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" } } } ] } Copy

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.

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 is the STORAGE_AWS_EXTERNAL_ID para o seu volume externo e também o ID externo para o 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"
           }
         }
       }
     ]
   }

Copy

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 `WAREHOUSE` 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: 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 WAREHOUSE 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.