Introdução ao Snowflake Open Catalog¶

O que você aprenderá¶

• Como criar uma nova conta no Open Catalog.

• Como criar um novo catálogo Iceberg na conta do Open Catalog e protegê-lo usando RBAC.

• Como usar o Apache Spark™ para criar tabelas no catálogo e executar consultas.

• Como usar o Snowflake para executar consultas em tabelas no catálogo.

• Como espelhar ou publicar tabelas Iceberg gerenciadas no Snowflake para o Open Catalog.

O que você vai precisar¶

• Privilégios ORGADMIN em sua organização Snowflake (para criar uma nova conta do Open Catalog).

• Privilégios ACCOUNTADMIN em sua conta Snowflake (para conectar-se à conta Open Catalog). Esta conta Snowflake não precisa ser a mesma que a conta da organização Snowflake.

O que você vai fazer¶

Você concluirá dois casos de uso:

• Caso de uso 1: Crie um catálogo no Open Catalog, crie uma tabela usando o Apache Spark e consulte a tabela usando o Apache Spark e o Snowflake.

  

• Caso de uso 2: Crie uma tabela Apache Iceberg na conta Snowflake DB usando o Snowflake e publique-a no Open Catalog para que o Apache Spark possa executar consultas nela.

  

Instale Conda, Spark e Jupyter em seu laptop¶

Neste tutorial, é possível usar o Conda para criar facilmente um ambiente de desenvolvimento e baixar os pacotes necessários. Isso só será necessário se você seguir o caso de uso 2 para usar o Apache Spark™ para ler tabelas do Apache Iceberg™ gerenciadas pelo Snowflake. Isso não é necessário para criar ou usar tabelas Iceberg no Snowflake.

1. Para instalar o Conda, use as instruções específicas para o seu OS:

   • Mac

   • Windows

   • Linux

2. Crie um arquivo chamado environment.yml com o seguinte conteúdo:

   name: iceberg-lab
   channels:
     - conda-forge
   dependencies:
     - findspark=2.0.1
     - jupyter=1.0.0
     - pyspark=3.5.0
     - openjdk=11.0.13
   

   Copy

3. Para criar o ambiente necessário, execute o seguinte em seu shell:

   conda env create -f environment.yml
   

   Copy

Crie uma conta Open Catalog¶

Uma conta Open Catalog pode ser criada somente por um ORGADMIN.

1. No Snowsight, no painel de navegação, selecione Admin > Contas.

2. No menu suspenso + Conta, selecione Criar conta do Snowflake Open Catalog.

3. Conclua a caixa de diálogo Criar conta do Snowflake Open Catalog:

   • Nuvem: O provedor de nuvem onde deseja armazenar tabelas Apache Iceberg™.

   • Região: A região onde deseja armazenar as tabelas Iceberg.

   • Edição: A edição para sua conta Open Catalog.

4. Selecione Avançar.

5. Na caixa de diálogo Criar nova conta, preencha os campos Nome da conta, Nome de usuário, Senha e E-mail.

6. Selecione Criar conta. Sua nova conta do Open Catalog será criada e uma caixa de confirmação será exibida.

7. Na caixa de confirmação, selecione URL do localizador de contas para abrir o URL do localizador de contas em seu navegador da Web.

8. Adicione o URL do localizador de contas aos favoritos. Ao fazer login no Open Catalog, você deve especificar o URL do localizador de conta.

Faça login na interface da Web do Open Catalog¶

1. Clique no URL da conta que você recebeu por e-mail após criar a conta, OR vá para https://app.snowflake.com.

2. Clique em Fazer login em uma conta diferente e faça login com a conta do Open Catalog criada anteriormente.

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

Se você ainda não tiver uma, comece criando uma política de IAM que conceda acesso ao local de seu S3. Para obter instruções sobre como criar esta política, consulte Criação de uma política de IAM que concede acesso ao local de seu S3.

Crie uma função IAM¶

Se você ainda não tiver uma, crie uma função AWS IAM para o Open Catalog para conceder privilégios em seu bucket S3. Para obter instruções, consulte Criação de uma função IAM. Quando as instruções solicitarem que você selecione uma política, selecione a política de IAM que concede acesso ao local de seu S3.

Criação de um catálogo interno no Open Catalog¶

É possível usar um catálogo interno em sua conta do Open Catalog para criar tabelas, consultá-las e executar DML nelas usando o Apache Spark™ ou outros mecanismos de consulta.

1. Entre em sua nova conta do Open Catalog.

2. Para criar um novo catálogo, no painel à esquerda, selecione Catálogos.

3. Selecione + Catálogo no canto superior direito.

4. Na caixa de diálogo Criar catálogo, insira os seguintes detalhes:

   • Nome: nomear o catálogo demo_catalog.

   • Local base padrão: O local onde os dados da tabela serão armazenados.

   • Locais adicionais (opcional): Uma lista separada por vírgulas de vários locais de armazenamento. Ele é usado principalmente se você precisar importar tabelas de diferentes locais neste catálogo. Você pode deixar em branco.

   • ARN da função S3: Uma função AWS que tem acesso de leitura e gravação aos locais de armazenamento. Insira o ARN do nome da função de IAM que você criou para o Open Catalog.

   • ID externo: (opcional): Um segredo que você deseja fornecer ao criar uma relação de confiança entre o usuário do catálogo e a conta de armazenamento. Se você ignorar isso, ele será gerado automaticamente. Use uma cadeia de caracteres simples como abc123 para este tutorial.

5. Selecione Criar. Seu catálogo é criado e os seguintes valores são adicionados a ele:

   • O ARN do usuário de IAM para sua conta do Open Catalog.

   • Se você não inseriu um ID externo, um ID externo será gerado automaticamente para seu catálogo.

   Você precisará desses valores na próxima seção ao criar uma relação de confiança.

Crie uma relação de confiança¶

Após criar um catálogo, você precisa definir uma relação de confiança para que a função S3 especificada na configuração acima possa ler e gravar dados no local de armazenamento. Observe que para concluir esta tarefa, você precisará do ARN do usuário de S3 IAM e o ID externo para seu catálogo.

1. Após a criação do catálogo, selecione-o na lista para exibir o ARN do usuário de S3 IAM e o ID externo de seu catálogo.

2. Para criar a relação de confiança, conclua as instruções em Etapa 5: conceda ao usuário de IAM permissões para acessar objetos do bucket.

   No objeto JSON mostrado nestas instruções:

   • Em <open_catalog_user_arn>, use o valor em ARN do usuário de IAM na UI do Open Catalog.

   • Em <open_catalog_external_id>, use o valor em ID externo na UI do Open Catalog.

   

Configure uma nova conexão de serviço para o Apache Spark™¶

Crie uma nova conexão (par client_id/client_secret) para o Apache Spark executar consultas no catálogo que você acabou de criar.

1. No Open Catalog, no painel esquerdo, selecione a guia Conexões e, em seguida, selecione + Conexão no canto superior direito.

2. Na caixa de diálogo Configurar conexão de serviço, crie uma nova função de entidade ou escolha uma das funções disponíveis.

3. Selecione Criar.

4. Na caixa de diálogo Configurar conexão de serviço, para copiar o ID do cliente e o segredo do cliente para um editor de texto, selecione Copiar dentro do campo Como <CLIENT ID>:<SECRET>

   Importante

   Você não poderá recuperar essas cadeias de caracteres de texto do serviço Open Catalog mais tarde, portanto, você deve copiá-las agora. Use essas cadeias de caracteres de texto ao configurar o Spark.

Definição dos privilégios de catálogo para conexão¶

Agora você concede privilégios à conexão de serviço para que ela possa acessar o catálogo. Sem privilégios de acesso, a conexão de serviço não pode executar nenhuma consulta no catálogo.

1. No painel de navegação, selecione Catálogos e, em seguida, selecione seu catálogo na lista.

2. Para criar uma nova função, selecione a guia Funções.

3. Selecione + Função de catálogo.

4. Na caixa de diálogo Criar função de catálogo, para Nome, insira spark_catalog_role.

5. Em Privilégios, selecione CATALOG_MANAGE_CONTENT e depois selecione Criar.

   Isso dá à função privilégios para criar, ler e gravar em tabelas.

6. Selecione Conceder à função de entidade.

7. Na caixa de diálogo Função do catálogo de concessões, para Função de entidade receber concessão, selecione my_spark_admin_role.

8. Em Função de catálogo a ser concedida, selecione spark_catalog_role e, em seguida, selecione Conceder.

Como resultado desse procedimento, a função spark_catalog_role é concedida a my_spark_admin_role, o que concede privilégios de administrador para a conexão Spark que você criou no procedimento anterior.

Instalação do Spark¶

Em seu terminal, execute os seguintes comandos para ativar o ambiente virtual que você criou na configuração e abrir os notebooks Jupyter:

conda activate iceberg-lab
jupyter notebook

Configuração do Spark¶

• Para registrar a conexão de serviço, execute os seguintes comandos em um notebook Jupyter.

  import os
  os.environ['SPARK_HOME'] = '/Users/<username>/opt/anaconda3/envs/iceberg-lab/lib/python3.12/site-packages/pyspark'
  
  import pyspark
  from pyspark.sql import SparkSession
  
  spark = SparkSession.builder.appName('iceberg_lab') \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160,software.amazon.awssdk:url-connection-client:2.20.160') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'opencatalog') \
  .config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
  .config('spark.sql.catalog.opencatalog.type', 'rest') \
  .config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.catalog.opencatalog.uri','https://<open_catalog_account_identifier>.snowflakecomputing.com/polaris/api/catalog') \
  .config('spark.sql.catalog.opencatalog.credential','<client_id>:<client_secret>') \
  .config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
  .config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:<principal_role_name>') \
  .getOrCreate()
  
  #Show namespaces
  spark.sql("show namespaces").show()
  
  #Create namespace
  spark.sql("create namespace spark_demo")
  
  #Use namespace
  spark.sql("use namespace spark_demo")
  
  #Show tables; this will show no tables since it is a new namespace
  spark.sql("show tables").show()
  
  #create a test table
  spark.sql("create table test_table (col1 int) using iceberg");
  
  #insert a record in the table
  spark.sql("insert into test_table values (1)");
  
  #query the table
  spark.sql("select * from test_table").show();
  

  Copy

  Para obter mais informações, consulte Registrar uma conexão de serviço no Spark.

.config('spark.sql.catalog.opencatalog.client.region','<target_s3_region>') \

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
.config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160,software.amazon.awssdk:url-connection-client:2.20.160') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.config('spark.sql.defaultCatalog', 'opencatalog') \
.config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
.config('spark.sql.catalog.opencatalog.type', 'rest') \
.config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
.config('spark.sql.catalog.opencatalog.uri','https://<open_catalog_account_identifier>.snowflakecomputing.com/polaris/api/catalog') \
.config('spark.sql.catalog.opencatalog.credential','<client_id>:<secret>') \
.config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
.config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:<principal_role_name>') \
.config('spark.sql.catalog.opencatalog.client.region','<target_s3_region>') \
.getOrCreate()

Consulta às tabelas usando o Snowflake¶

Você pode criar um objeto de integração de catálogo no Snowflake e criar uma tabela Apache Iceberg™ no Snowflake que represente a tabela no Open Catalog. No exemplo a seguir, você cria uma tabela Iceberg no Snowflake que representa a tabela Iceberg recém-criada pelo Spark no catálogo interno do Open Catalog.

É possível usar as mesmas credenciais de conexão do Spark ou criar uma nova conexão do Snowflake. Se você criar uma nova conexão, precisará definir funções e privilégios adequadamente.

1. Crie um objeto de integração de catálogo:

   CREATE OR REPLACE CATALOG INTEGRATION demo_open_catalog_int 
     CATALOG_SOURCE = POLARIS 
     TABLE_FORMAT = ICEBERG 
     CATALOG_NAMESPACE = '<catalog_namespace>'
     REST_CONFIG = (
       CATALOG_URI = 'https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.com/polaris/api/catalog' 
       CATALOG_NAME = ‘<catalog_name>’
     )
       REST_AUTHENTICATION = (
       TYPE = OAUTH 
       OAUTH_CLIENT_ID = '<client_id>' 
       OAUTH_CLIENT_SECRET = '<secret>' 
       OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL') 
     ) 
     ENABLED = TRUE;
   
   # the <catalog_namespace> created in previous step is spark_demo.
   # the <catalog_name> created in previous step is demo_catalog.
   

   Copy

2. Crie a representação da tabela no Snowflake usando a integração de catálogo criada acima e consulte a tabela:

   CREATE OR REPLACE ICEBERG TABLE test_table
     CATALOG = 'demo_open_catalog_int'
     EXTERNAL_VOLUME = '<external_volume>'
     CATALOG_TABLE_NAME = 'test_table';
   
   SELECT * FROM test_table;
   

   Copy

Criação de um catálogo externo no Open Catalog¶

As tabelas Iceberg do Snowflake podem ser sincronizadas em um catálogo externo em sua conta do Open Catalog.

1. Entre em sua nova conta do Open Catalog.

2. Para criar um novo catálogo, no painel à esquerda, selecione Catálogos.

3. Selecione + Catálogo no canto superior direito.

4. Na caixa de diálogo Criar catálogo, insira os seguintes detalhes:

   • Nome: Nomeie o catálogo como demo_catalog_ext.

   • Defina o seletor de Externo como Ativado.

   • Local base padrão: O local onde os dados da tabela serão armazenados.

     Observação

     É necessário usar um local de armazenamento diferente do catálogo interno criado durante o Caso de uso 1 deste tutorial. Para garantir que os privilégios de acesso definidos para um catálogo sejam aplicados corretamente, dois catálogos diferentes não podem ter locais sobrepostos.

   • Locais adicionais (opcional): Uma lista separada por vírgulas de vários locais de armazenamento. Ele é usado principalmente se você precisar importar tabelas de diferentes locais neste catálogo. Você pode deixar em branco.

   • ARN da função S3: Uma função AWS que tem acesso de leitura e gravação aos locais de armazenamento.

   • ID externo: (opcional): Um segredo que você deseja fornecer ao criar uma relação de confiança entre o usuário do catálogo e a conta de armazenamento. Se você ignorar isso, ele será gerado automaticamente. Use uma cadeia de caracteres simples como abc123 para este tutorial.

5. Selecione Criar. Os seguintes valores são adicionados ao seu catálogo:

   • O ARN do usuário de IAM para sua conta do Open Catalog.

   • Se você não inseriu um ID externo, um ID externo será gerado automaticamente para seu catálogo.

Configurar uma nova conexão de serviço para o Snowflake¶

1. No Open Catalog, no painel esquerdo, selecione a guia Conexões e, em seguida, selecione + Conexão no canto superior direito.

2. Na caixa de diálogo Configurar conexão de serviço, crie uma nova função de entidade ou escolha uma das funções disponíveis.

3. Selecione Criar.

4. Na caixa de diálogo Configurar conexão de serviço, para copiar o ID do cliente e o segredo do cliente para um editor de texto, selecione Copiar dentro do campo Como <CLIENT ID>:<SECRET>

   Importante

   Você não poderá recuperar essas cadeias de caracteres de texto do serviço Open Catalog mais tarde, portanto, você deve copiá-las agora. Use essas cadeias de caracteres de texto ao configurar o Spark.

Definição de privilégios de catálogo¶

Para definir privilégios no catálogo externo para que a conexão Snowflake tenha os privilégios corretos para um catálogo externo, siga estas etapas:

1. No painel de navegação, selecione Catálogos e, em seguida, selecione seu catálogo externo na lista.

2. Para criar uma nova função, selecione a guia Funções.

3. Selecione + Função de catálogo.

4. Na caixa de diálogo Criar função de catálogo, para Nome, insira spark_catalog_role.

5. Em Privilégios, selecione CATALOG_MANAGE_CONTENT e depois selecione Criar.

   Isso dá à função privilégios para criar, ler e gravar em tabelas.

6. Selecione Conceder à função de entidade.

7. Na caixa de diálogo Função do catálogo de concessões, para Função de entidade receber concessão, selecione my_spark_admin_role.

8. Em Função de catálogo a ser concedida, selecione spark_catalog_role e, em seguida, selecione Conceder.

Criação de um objeto de integração de catálogo no Snowflake¶

No Snowflake, crie um objeto de integração de catálogo usando o comandoCREATE CATALOG INTEGRATION (Snowflake Open Catalog). Para CATALOG_NAME, especifique o nome do catálogo externo que configurou na sua conta do Open Catalog (demo_catalog_ext).

O Snowflake sincroniza a tabela e seu namespace pai com esse catálogo externo no Open Catalog. Por exemplo, se tiver uma tabela open_catalog_demo.iceberg.test_table_managed Iceberg registrada no Snowflake e especificar demo_catalog_ext na integração do catálogo, o Snowflake sincronizará a tabela com o Open Catalog com o seguinte nome totalmente qualificado: demo_catalog_ext.open_catalog_demo.iceberg.test_table_managed.

CREATE OR REPLACE CATALOG INTEGRATION demo_open_catalog_ext 
  CATALOG_SOURCE=POLARIS 
  TABLE_FORMAT=ICEBERG 
  REST_CONFIG = (
    CATALOG_URI = 'https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.com/polaris/api/catalog' 
    CATALOG_NAME = '<catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH 
    OAUTH_CLIENT_ID = '<client_id>' 
    OAUTH_CLIENT_SECRET = '<secret>' 
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL') 
  ) 
  ENABLED=TRUE;

# the <catalog_name> created in previous step is demo_catalog_ext.

Configurar a sincronização do catálogo¶

Antes de poder sincronizar uma tabela Iceberg gerenciada pelo Snowflake com o Open Catalog, especifique o catálogo externo no Open Catalog com o qual o Snowflake deve sincronizar a tabela.

Para configurar a sincronização do catálogo, use o comando ALTER DATABASE com o parâmetro CATALOG_SYNC. Para o valor desse parâmetro, especifique o nome da integração do catálogo para o Open Catalog. Por exemplo:

ALTER DATABASE open_catalog_demo SET CATALOG_SYNC = 'demo_open_catalog_ext';

Depois de executar esse código, o Snowflake sincroniza todas as tabelas Iceberg gerenciadas pelo Snowflake no banco de dados open_catalog_demo com o catálogo externo <catalog_name> no Open Catalog que você especificou na integração do catálogo demo_open_catalog_ext.

Criar uma tabela Iceberg gerenciada pelo Snowflake¶

Crie uma tabela Iceberg gerenciada pelo Snowflake e sincronize-a do Snowflake com o Open Catalog. Para obter mais informações, consulte:

• Configuração de um volume externo para o Amazon S3

• CREATE ICEBERG TABLE (Snowflake como o catálogo Iceberg)

Importante

O STORAGE_BASE_URL para o volume externo deve corresponder ao local base padrão do catálogo externo criado no Open Catalog.

use database open_catalog_demo;
use schema iceberg;

# Note that the storage location for this external volume will be different than the storage location for the external volume in use case 1

CREATE OR REPLACE EXTERNAL VOLUME snowflake_demo_ext
  STORAGE_LOCATIONS =
      (
        (
            NAME = '<storage_location_name>'
            STORAGE_PROVIDER = 'S3'
            STORAGE_BASE_URL = 's3://<s3_location>'
            STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::<aws_acct>:role/<rolename>'
            STORAGE_AWS_EXTERNAL_ID = '<external_id>'
        )
      );

CREATE OR REPLACE ICEBERG TABLE test_table_managed (col1 int)
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'snowflake_demo_ext'
  BASE_LOCATION = 'test_table_managed'

Quando você modifica a tabela no Snowflake, as alterações são sincronizadas automaticamente com o catálogo externo na sua conta Open Catalog. Outros mecanismos, como o Apache Spark™, podem consultar a tabela conectando-se ao Open Catalog.

Observação

Se a tabela não sincronizar com o Open Catalog, execute a função de sistema SYSTEM$SEND_NOTIFICATIONS_TO_CATALOG para diagnosticar o motivo da falha de sincronização. Para obter mais informações, consulte SYSTEM$SEND_NOTIFICATIONS_TO_CATALOG.

O que você aprendeu¶

• Crie uma conta no Open Catalog.

• Crie um catálogo interno em sua conta do Open Catalog.

• Use o Spark para criar tabelas no catálogo interno.

• Use o Snowflake para criar uma integração de catálogo para o Open Catalog para executar consultas em uma tabela criada em um catálogo interno em sua conta do Open Catalog.

• Crie um catálogo externo em sua conta do Open Catalog.

• Crie uma tabela gerenciada do Apache Iceberg™; no Snowflake e sincronize-a, juntamente com dois namespaces pai, com o catálogo externo em sua conta do Open Catalog. No tutorial, você aprendeu a configurar a sincronização do catálogo no nível do banco de dados. No entanto, você também pode configurá-lo no nível da conta, do esquema ou da tabela e sincronizá-lo com um namespace pai. Para obter mais informações, consulte os seguintes tópicos:

  • Para obter um exemplo de configuração da sincronização do catálogo no nível do esquema, consulte Configurar a sincronização do catálogo no nível do esquema na documentação do Snowflake.

  • Para obter mais informações sobre como configurar a sincronização do catálogo, consulte CATALOG_SYNC na documentação do Snowflake.

  • Para sincronizar a tabela com um namespace pai, defina a propriedade CATALOG_SYNC_NAMESPACE_MODE com o comando CREATE DATABASE. Para saber mais, consulte CREATE DATABASE na documentação do Snowflake.

    Nota

    Se o mecanismo de consulta de terceiros só puder consultar tabelas localizadas até o segundo nível de namespace em um catálogo, você deverá sincronizar a tabela com um namespace pai. Caso contrário, o Snowflake sincronizará a tabela com o terceiro nível de namespace no Open Catalog e você não poderá consultar a tabela.

Recursos relacionados¶

• Documentação das tabelas Snowflake Iceberg

• Repositório GitHub do Apache Polaris™ (incubando)

• Documentação do Apache Iceberg