Tutorial: Crie sua primeira tabela Apache Iceberg™¶

O que você aprenderá¶

Neste tutorial, você aprenderá a:

• Criar e configurar um volume externo para tabelas Iceberg gerenciadas pelo Snowflake. Para fins de demonstração, o tutorial cria um volume externo para o Amazon S3.

• Crie duas tabelas Iceberg que usam o Snowflake como catálogo Iceberg (tabelas gerenciadas pelo Snowflake).

• Insira os dados nas tabelas Iceberg.

• Consulte as tabelas Iceberg.

• Exclua linhas de uma tabela Iceberg.

Pré-requisitos¶

Antes de começar, você deve estar familiarizado com o seguinte:

• Identificadores de objetos Snowflake e seus requisitos.

• Apache Iceberg e tabelas Iceberg no Snowflake. Para obter mais informações, consulte Tabelas Apache Iceberg™.

• Armazenamento de objetos na nuvem.

• Se estiver usando o S3, você deve estar familiarizado com o gerenciamento de identidade e acesso (IAM) da AWS e os elementos de política IAM.

Você precisa de:

• Um usuário Snowflake com uma função tem privilégios para executar as seguintes ações:

  • CREATE WAREHOUSE

  • CREATE DATABASE

  • CREATE EXTERNAL VOLUME

  • CREATE ICEBERG TABLE

  Se estiver usando uma conta de avaliação de 30 dias, você pode fazer login como o usuário criado para a conta. Este usuário tem a função com os privilégios necessários para criar os objetos.

  Se você não tiver um usuário com as permissões necessárias, peça para alguém que tenha criar um para você. Usuários com a função ACCOUNTADMIN podem criar novos usuários e conceder a eles os privilégios necessários.

• Acesso de administrador para seu provedor de armazenamento em nuvem para configurar um volume externo.

• Um bucket de armazenamento (ou contêiner) com o mesmo provedor de nuvem, na mesma região que hospeda sua conta Snowflake.

• Acesso ao banco de dados SNOWFLAKE_SAMPLE_DATA em sua conta. O Snowflake cria o banco de dados de amostra em novas contas por padrão. Se o banco de dados não foi criado em sua conta, consulte Uso do banco de dados de amostra.

Criação de um IAM política que conceda acesso ao seu local S3¶

Para configurar permissões de acesso para Snowflake no AWS Management Console, faça o seguinte:

1. Faça login no AWS Management Console.

2. No painel inicial, pesquise e selecione IAM.

3. Selecione Account settings no painel de navegação à esquerda.

4. Em Security Token Service (STS), na lista Endpoints, encontre a região do Snowflake onde sua conta está localizada. Se o STS status estiver inativo, mude o seletor para Active.

5. Selecione Policies no painel de navegação à esquerda.

6. Selecione Create Policy.

   

7. Para Policy editor, selecione JSON.

8. Adicione uma política para fornecer ao Snowflake as permissões necessárias para ler e gravar dados em seu local S3.

   O exemplo de política a seguir concede acesso a todos os locais no bucket especificado.

   Nota

   • Substitua my_bucket com o nome real de seu bucket. Você também pode especificar um caminho no bucket; por exemplo, my_bucket/path.

   • Definir a condição "s3:prefix": para ["*"] concede acesso a todos os prefixos no bucket especificado; defini-lo como ["path/*"] concede acesso a um caminho especificado no bucket.

   • Para buckets em regiões governamentais, os ARNs de bucket usam o prefixo arn:aws-us-gov:s3:::.

   {
      "Version": "2012-10-17",
      "Statement": [
            {
               "Effect": "Allow",
               "Action": [
                  "s3:PutObject",
                  "s3:GetObject",
                  "s3:GetObjectVersion",
                  "s3:DeleteObject",
                  "s3:DeleteObjectVersion"
               ],
               "Resource": "arn:aws:s3:::<my_bucket>/*"
            },
            {
               "Effect": "Allow",
               "Action": [
                  "s3:ListBucket",
                  "s3:GetBucketLocation"
               ],
               "Resource": "arn:aws:s3:::<my_bucket>",
               "Condition": {
                  "StringLike": {
                        "s3:prefix": [
                           "*"
                        ]
                  }
               }
            }
      ]
   }
   

   Copy

9. Selecione Next.

10. Insira um Policy name (por exemplo, snowflake_access) e uma Description opcional.

11. Selecione Create policy.

Crie uma função IAM¶

Crie uma função AWS IAM para conceder privilégios ao bucket S3 com seus arquivos de dados.

1. Na seção de navegação à esquerda do painel de gerenciamento de identidade e acesso (IAM), selecione Roles.

2. Selecione Create role.

3. Para o tipo de entidade de confiança, selecione AWS account.

4. Em An AWS account, selecione This account. Em uma etapa posterior, você modifica a relação de confiança e concede acesso ao Snowflake.

5. Selecione a opção Require external ID. Insira um ID externo de sua escolha. Por exemplo, iceberg_table_external_id.

   Um ID externo é usado para conceder acesso aos seus recursos AWS (como buckets S3) a terceiros, como o Snowflake.

   

6. Selecione Next.

7. Selecione a política que você criou para o volume externo e selecione Next.

8. Insira um Role name e uma descrição para a função e selecione Create role.

   Agora você criou uma política IAM para um local S3, criou uma função IAM e anexou a política à função.

9. Selecione View role para exibir a página de resumo da função. Localize e registre o valor do nome de recurso da Amazon (ARN) para a função.

   

Criação de um volume externo no Snowflake¶

Crie um volume externo usando o comando CREATE EXTERNAL VOLUME. O exemplo a seguir cria um volume externo nomeado iceberg_external_volume, que define um local de armazenamento único do Amazon S3 com criptografia.

CREATE OR REPLACE EXTERNAL VOLUME iceberg_external_volume
   STORAGE_LOCATIONS =
      (
         (
            NAME = 'my-s3-us-west-2'
            STORAGE_PROVIDER = 'S3'
            STORAGE_BASE_URL = 's3://<my_bucket>/'
            STORAGE_AWS_ROLE_ARN = '<arn:aws:iam::123456789012:role/myrole>'
            STORAGE_AWS_EXTERNAL_ID = 'iceberg_table_external_id'
         )
      );

O exemplo especifica o ID externo (iceberg_table_external_id) associado à função IAM que você criou para o volume externo. Especificar um ID externo permite que você use a mesma função IAM (e ID externo) em vários volumes externos.

Recuperação do usuário AWS IAM para sua conta Snowflake¶

1. Recupere o ARN do usuário AWS IAM criado automaticamente para sua conta Snowflake, usando o comando DESCRIBE EXTERNAL VOLUME. Especifique o nome do seu volume externo.

   O exemplo a seguir descreve um volume externo nomeado iceberg_external_volume.

   DESC EXTERNAL VOLUME iceberg_external_volume;
   

   Copy

2. Registre o valor para a propriedade STORAGE_AWS_IAM_USER_ARN, que é o usuário AWS IAM criado para sua conta Snowflake; por exemplo, arn:aws:iam::123456789001:user/abc1-b-self1234.

   O Snowflake fornece um único usuário IAM para toda a sua conta Snowflake. Todos os volumes externos S3 da sua conta usam esse usuário IAM.

   Nota

   Se você não especificou um ID externo (STORAGE_AWS_EXTERNAL_ID) ao criar um volume externo, o Snowflake gerará um ID para você usar. Registre o valor para que você possa atualizar sua política de confiança da função IAM com o ID externo gerado.

Concessão de permissões ao usuário IAM para acessar objetos bucket¶

Nesta etapa, você configura permissões que permitem que o usuário IAM da sua conta Snowflake acesse objetos no seu bucket S3.

1. Faça login no AWS Management Console.

2. No painel inicial, pesquise e selecione IAM.

3. Selecione Roles no painel de navegação à esquerda.

4. Selecione a função IAM que você criou para seu volume externo.

5. Selecione a guia Trust relationships.

6. Selecione Edit trust policy.

7. Modifique o documento de política com valores de saída DESC EXTERNAL VOLUME que você registrou.

   

   Documento de política da função IAM

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<snowflake_user_arn>"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "<iceberg_table_external_id>"
           }
         }
       }
     ]
   }
   

   Copy

   Onde:

   • snowflake_user_arn é o valor STORAGE_AWS_IAM_USER_ARN que você registrou.

   • iceberg_table_external_id é seu ID externo. Se você já especificou um ID externo ao criar a função e usou o mesmo ID para criar seu volume externo, deixe o valor como está. Caso contrário, atualize sts:ExternalId com o valor que você registrou.

   Nota

   Você deverá atualizar este documento de política se criar um novo volume externo (ou recriar um volume externo existente usando a sintaxe CREATE OR REPLACE EXTERNAL VOLUME) e não fornecer seu próprio ID externo. Por motivos de segurança, um volume externo novo ou recriado tem um ID externo diferente e não pode resolver a relação de confiança, a menos que você atualize esta política de confiança.

8. Selecione Update policy para salvar suas alterações.

Criar uma tabela usando a sintaxe padrão¶

Primeiro, crie uma tabela Iceberg usando a sintaxe padrão CREATE ICEBERG TABLE.

Especifique CATALOG = 'SNOWFLAKE' para que a tabela use Snowflake como catálogo Iceberg.

Para informar ao Snowflake onde gravar os dados da tabela e os metadados, especifique um valor para o parâmetro BASE_LOCATION. O exemplo define o nome da tabela (customer_iceberg) como o BASE_LOCATION. Dessa forma, o Snowflake grava dados e metadados em um diretório com o mesmo nome de tabela no local de seu volume externo.

CREATE OR REPLACE ICEBERG TABLE customer_iceberg (
    c_custkey INTEGER,
    c_name STRING,
    c_address STRING,
    c_nationkey INTEGER,
    c_phone STRING,
    c_acctbal INTEGER,
    c_mktsegment STRING,
    c_comment STRING
)
    CATALOG = 'SNOWFLAKE'
    EXTERNAL_VOLUME = 'iceberg_external_volume'
    BASE_LOCATION = 'customer_iceberg';

Mais adiante no tutorial, você carregará dados nesta tabela a partir da tabela snowflake_sample_data.tpch_sf1.customer no banco de dados SNOWFLAKE_SAMPLE_DATA. As definições de coluna na instrução CREATE ICEBERG TABLE correspondem à tabela de exemplo.

Definir a integração do catálogo e o volume externo para o banco de dados¶

Em seguida, defina os parâmetros de CATALOG e EXTERNAL_VOLUME para o iceberg_tutorial_db que você criou neste tutorial. A definição dos parâmetros informa ao Snowflake para usar o catálogo específico e o volume externo que você escolher para todas as tabelas Iceberg criadas após a alteração.

ALTER DATABASE iceberg_tutorial_db SET CATALOG = 'SNOWFLAKE';
ALTER DATABASE iceberg_tutorial_db SET EXTERNAL_VOLUME = 'iceberg_external_volume';

Para verificar, confira os parâmetros do banco de dados atual (iceberg_tutorial_db):

SHOW PARAMETERS IN DATABASE ;

Criar uma tabela usando CTAS¶

Por fim, crie uma segunda tabela Iceberg chamada nation_iceberg usando a sintaxe CREATE ICEBERG TABLE … AS SELECT. Basearemos a nova tabela na tabela snowflake_sample_data.tpch_sf1.nation no banco de dados de exemplo Snowflake.

CREATE OR REPLACE ICEBERG TABLE nation_iceberg (
  n_nationkey INTEGER,
  n_name STRING
)
  BASE_LOCATION = 'nation_iceberg'
  AS SELECT
    N_NATIONKEY,
    N_NAME
  FROM snowflake_sample_data.tpch_sf1.nation;