Configuração da replicação para tabelas Apache Iceberg™ gerenciadas pelo Snowflake¶

Escolha da versão preliminar pública para replicação de tabelas Iceberg gerenciadas pelo Snowflake¶

Para optar por essa versão preliminar pública, é necessário escolher ambas as contas de origem e de destino.

1. Para escolher a conta de origem, depois de habilitar os recursos em versão preliminar na conta, use o comando ALTER ACCOUNT para habilitar os seguintes parâmetros no nível da conta:

   • ENABLE_ICEBERG_MANAGED_TABLE_REPLICATION

     Nota

     Você também pode habilitar esse parâmetro no nível do grupo de failover.

   • ENABLE_SELECTIVE_EXTERNAL_VOLUME_REPLICATION_PUPR

   Por exemplo:

   ALTER ACCOUNT SET
     ENABLE_ICEBERG_MANAGED_TABLE_REPLICATION = TRUE
     ENABLE_SELECTIVE_EXTERNAL_VOLUME_REPLICATION_PUPR = TRUE;
   

   Copy

2. Repita a etapa anterior para a conta de destino.

Habilitar a replicação¶

Um usuário com a função ORGADMIN deve habilitar a replicação para cada conta de origem e destino na organização:

USE ROLE ORGADMIN;
SELECT SYSTEM$GLOBAL_ACCOUNT_SET_PARAMETER(
    '<organization_name>.<account_name>',
    'ENABLE_ACCOUNT_DATABASE_REPLICATION',
    'true');

Para obter mais informações, consulte Pré-requisito: Habilitar a replicação para contas na organização.

Para obter mais informações sobre replicação, consulte Introdução à replicação e failover em várias contas.

Replicação de um volume externo usando um grupo de failover¶

Estas etapas fornecem um fluxo de trabalho de amostra para replicar um volume externo e as tabelas Iceberg que dependem dele para uma conta de destino usando um grupo de failover.

1. Na conta de origem, atualize seu volume externo para adicionar um local de armazenamento na mesma região que sua conta de destino.

   Por exemplo:

   ALTER EXTERNAL VOLUME exvol1
    ADD STORAGE_LOCATION =
    (
      NAME = 'my-s3-us-central-2'
      STORAGE_PROVIDER = 'S3'
      STORAGE_BASE_URL = 's3://my_bucket_us_central-2/'
      STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/myrole'
      STORAGE_AWS_EXTERNAL_ID = 'iceberg_table_external_id'
    );
   

   Copy

   Importante

   Se você não especificar seu próprio STORAGE_AWS_EXTERNAL_ID para armazenamento S3, deverá chamar DESCRIBE EXTERNAL VOLUME depois de adicionar o novo local de armazenamento para recuperar o ID externo gerado pelo Snowflake. Você precisa do ID externo para configurar o acesso ao S3 na próxima etapa.

   O Snowflake define este novo local como o local de armazenamento ativo para o volume externo secundário.

2. Na conta de origem, crie uma tabela Iceberg gerenciada pelo Snowflake que use o volume externo que você atualizou com o local de armazenamento adicional.

   Por exemplo:

   CREATE ICEBERG TABLE my_iceberg_table (amount int)
     CATALOG = 'SNOWFLAKE'
     EXTERNAL_VOLUME = 'exvol1'
     BASE_LOCATION = 'my_iceberg_table';
   

   Copy

3. Na conta de origem, recupere as informações sobre a entidade de serviço do Snowflake para sua conta de destino seguindo estas etapas:

   1. Recupere o nome (account_name) da conta de destino usando o comando SHOW REPLICATION ACCOUNTS.

      SHOW REPLICATION ACCOUNTS LIKE 'my_target_account%';
      

      Copy

   2. Chame a função do sistema SYSTEM$DESC_ICEBERG_ACCESS_IDENTITY. Especifique o provedor de nuvem do local de armazenamento de destino e o nome da sua conta de destino exatamente como aparece na coluna account_name da saída de SHOW REPLICATION ACCOUNTS.

      Por exemplo:

      SELECT SYSTEM$DESC_ICEBERG_ACCESS_IDENTITY('S3', 'MY_TARGET_ACCOUNT_1');
      

      Copy

4. Configure o acesso do Snowflake ao local de armazenamento associado à sua conta de destino. Siga as instruções do seu provedor de nuvem, usando as informações que você recuperou para a entidade de serviço na conta de destino:

   • Configuração de um volume externo para Amazon S3. Use o ID externo associado ao local de armazenamento da sua conta de destino.

   • Configuração de um volume externo para o Google Cloud Storage

   • Configuração de um volume externo para o Azure. No AZURE_CONSENT_URL TEMPLATE retornado por SYSTEM$DESC_ICEBERG_ACCESS_IDENTITY, substitua your_tenant_id pelo ID do seu locatário ao qual o local de armazenamento pertence.

5. Na conta de origem, use o comando CREATE FAILOVER GROUP para criar um grupo de failover. Especifique EXTERNAL VOLUMES na lista OBJECT_TYPES. Na lista ALLOWED_DATABASES, inclua o banco de dados com as tabelas Iceberg que você deseja replicar. Na lista ALLOWED_EXTERNAL_VOLUMES, inclua os volumes externos que fornecem acesso às tabelas Iceberg que você deseja replicar.

   CREATE FAILOVER GROUP my_iceberg_fg
     OBJECT_TYPES = DATABASES, EXTERNAL VOLUMES
     ALLOWED_DATABASES = my_iceberg_database
     ALLOWED_EXTERNAL_VOLUMES = my_external_volume
     ALLOWED_ACCOUNTS = myorg.my_account_1;
   

   Copy

   Nota

   Se você receber um erro do analisador SQL, sua lista de volumes externos permitidos talvez seja muito longa. Se você receber esse erro, encurte a lista na instrução CREATE FAILOVER GROUP e use o comando ALTER FAILOVER GROUP para adicionar volumes externos permitidos extras ao grupo de failover.

   Para atualizar um grupo existente, use o comando ALTER FAILOVER GROUP para adicionar EXTERNAL VOLUMES à lista OBJECT_TYPES. Inclua outros objetos existentes na lista OBJECT_TYPES para evitar descartá-los da conta de destino.

   Por exemplo, adicione EXTERNAL VOLUMES a um grupo de failover que já inclui DATABASES:

   ALTER FAILOVER GROUP my_iceberg_rg SET
     OBJECT_TYPES = DATABASES, EXTERNAL VOLUMES
     ALLOWED_EXTERNAL_VOLUMES = my_external_volume;
   

   Copy

6. Na conta de destino, crie um grupo de failover como uma réplica do grupo na conta de origem (my_source_account):

   CREATE FAILOVER GROUP my_iceberg_fg
     AS REPLICA OF myorg.my_source_account.my_iceberg_fg;
   

   Copy

   Pule essa etapa se você já tem um grupo secundário que replica o grupo na conta de origem.

7. Na conta de destino, execute um comando de atualização.

   ALTER FAILOVER GROUP my_iceberg_fg REFRESH;
   

   Copy

   Desde que você replique o banco de dados que contém a tabela Iceberg gerenciada pelo Snowflake e tenha configurado o acesso ao seu armazenamento em nuvem para a conta de destino, o Snowflake replicará a tabela na conta de destino.

   Nota

   A operação de atualização falhará se o Snowflake não puder acessar o local de armazenamento configurado para a conta de destino. Se isso acontecer, verifique novamente as configurações de controle de acesso ou tente Verificação de acesso ao armazenamento.

Replicação de volume externo usando um grupo de replicação¶

Estas etapas fornecem um fluxo de trabalho de amostra para replicar um volume externo e as tabelas Iceberg que dependem dele para uma conta de destino usando um grupo de replicação.

1. Na conta de origem, atualize seu volume externo para adicionar um local de armazenamento na mesma região que sua conta de destino.

   Por exemplo:

   ALTER EXTERNAL VOLUME exvol1
    ADD STORAGE_LOCATION =
    (
      NAME = 'my-s3-us-central-2'
      STORAGE_PROVIDER = 'S3'
      STORAGE_BASE_URL = 's3://my_bucket_us_central-2/'
      STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/myrole'
      STORAGE_AWS_EXTERNAL_ID = 'iceberg_table_external_id'
    );
   

   Copy

   Importante

   Se você não especificar seu próprio STORAGE_AWS_EXTERNAL_ID para armazenamento S3, deverá chamar DESCRIBE EXTERNAL VOLUME depois de adicionar o novo local de armazenamento para recuperar o ID externo gerado pelo Snowflake. Você precisa do ID externo para configurar o acesso ao S3 na próxima etapa.

   O Snowflake define este novo local como o local de armazenamento ativo para o volume externo secundário.

2. Na conta de origem, crie uma tabela Iceberg gerenciada pelo Snowflake que use o volume externo que você atualizou com o local de armazenamento adicional.

   Por exemplo:

   CREATE ICEBERG TABLE my_iceberg_table (amount int)
     CATALOG = 'SNOWFLAKE'
     EXTERNAL_VOLUME = 'exvol1'
     BASE_LOCATION = 'my_iceberg_table';
   

   Copy

3. Na conta de origem, recupere as informações sobre a entidade de serviço do Snowflake para sua conta de destino seguindo estas etapas:

   1. Recupere o nome (account_name) da conta de destino usando o comando SHOW REPLICATION ACCOUNTS.

      SHOW REPLICATION ACCOUNTS LIKE 'my_target_account%';
      

      Copy

   2. Chame a função do sistema SYSTEM$DESC_ICEBERG_ACCESS_IDENTITY. Especifique o provedor de nuvem do local de armazenamento de destino e o nome da sua conta de destino exatamente como aparece na coluna account_name da saída de SHOW REPLICATION ACCOUNTS.

      Por exemplo:

      SELECT SYSTEM$DESC_ICEBERG_ACCESS_IDENTITY('S3', 'MY_TARGET_ACCOUNT_1');
      

      Copy

4. Configure o acesso do Snowflake ao local de armazenamento associado à sua conta de destino. Siga as instruções do seu provedor de nuvem, usando as informações que você recuperou para a entidade de serviço na conta de destino:

   • Configuração de um volume externo para Amazon S3. Use o ID externo associado ao local de armazenamento da sua conta de destino.

   • Configuração de um volume externo para o Google Cloud Storage

   • Configuração de um volume externo para o Azure. No AZURE_CONSENT_URL TEMPLATE retornado por SYSTEM$DESC_ICEBERG_ACCESS_IDENTITY, substitua your_tenant_id pelo ID do seu locatário ao qual o local de armazenamento pertence.

5. Na conta de origem, use o comando CREATE REPLICATION GROUP para criar um grupo de replicação. Especifique EXTERNAL VOLUMES na lista OBJECT_TYPES. Na lista ALLOWED_DATABASES, inclua o banco de dados com as tabelas Iceberg que deseja replicar. Na lista ALLOWED_EXTERNAL_VOLUMES, inclua os volumes externos que fornecem acesso às tabelas Iceberg que deseja replicar.

   CREATE REPLICATION GROUP my_iceberg_rg
     OBJECT_TYPES = DATABASES, EXTERNAL VOLUMES
     ALLOWED_DATABASES = my_iceberg_database
     ALLOWED_EXTERNAL_VOLUMES = my_external_volume
     ALLOWED_ACCOUNTS = myorg.my_account_1;
   

   Copy

   Nota

   Se você receber um erro do analisador SQL, sua lista de volumes externos permitidos talvez seja muito longa. Se você receber esse erro, encurte a lista na instrução CREATE REPLICATION GROUP e use o comando ALTER REPLICATION GROUP para adicionar volumes externos permitidos extras ao grupo de replicação.

   Para atualizar um grupo existente, use o comando ALTER REPLICATION GROUP para adicionar EXTERNAL VOLUMES à lista OBJECT_TYPES. Inclua outros objetos existentes na lista OBJECT_TYPES para evitar descartá-los da conta de destino.

   Por exemplo, adicione EXTERNAL VOLUMES a um grupo de replicação que já inclui DATABASES:

   ALTER REPLICATION GROUP my_iceberg_rg SET
     OBJECT_TYPES = DATABASES, EXTERNAL VOLUMES
     ALLOWED_EXTERNAL_VOLUMES = my_external_volume;
   

   Copy

6. Na conta de destino, crie um grupo de replicação como uma réplica do grupo na conta de origem (my_source_account):

   CREATE REPLICATION GROUP my_iceberg_rg
     AS REPLICA OF myorg.my_source_account.my_iceberg_rg;
   

   Copy

   Pule essa etapa se você já tem um grupo secundário que replica o grupo na conta de origem.

7. Na conta de destino, execute um comando de atualização.

   ALTER REPLICATION GROUP my_iceberg_rg REFRESH;
   

   Copy

   Desde que você replique o banco de dados que contém a tabela Iceberg gerenciada pelo Snowflake e tenha configurado o acesso ao seu armazenamento em nuvem para a conta de destino, o Snowflake replicará a tabela na conta de destino.

   Nota

   A operação de atualização falhará se o Snowflake não puder acessar o local de armazenamento configurado para a conta de destino. Se isso acontecer, verifique novamente as configurações de controle de acesso ou tente Verificação de acesso ao armazenamento.

Considerações e limitações¶

Considere os seguintes pontos ao usar a replicação para tabelas Iceberg:

• O Snowflake oferece suporte à replicação apenas de tabelas gerenciadas pelo Snowflake.

• Não há suporte para replicação de tabelas Iceberg convertidas. O Snowflake ignora tabelas convertidas durante as operações de atualização.

• Para tabelas replicadas, você deve configurar o acesso a um local de armazenamento na mesma região da conta de destino.

• Se você descartar ou alterar um local de armazenamento usado para replicação no volume externo primário, as operações de atualização poderão falhar.

• As tabelas secundárias na conta de destino são somente leitura até que você promova a conta de destino para atuar como conta de origem.

• O Snowflake mantém a hierarquia de diretórios da tabela Iceberg primária na tabela secundária.

• Para esse recurso, há custos de replicação. Para obter mais informações, consulte Explicação dos custos de replicação.

• Para considerações sobre os objetos da conta para grupos de replicação e de failover, consulte Objetos de conta.