Carregamento dados nas tabelas do Apache Iceberg™

O Snowflake oferece suporte às seguintes opções para carregar dados em uma tabela Iceberg gerenciada pelo Snowflake:

Formatos de arquivo

É possível carregar dados em uma tabela Iceberg a partir de arquivos em qualquer um dos formatos compatíveis para carregamento em tabelas Snowflake padrão.

Para CSV, JSON, Avro e ORC, o Snowflake converte os dados de formatos de arquivo não Parquet em arquivos Iceberg Parquet e armazena os dados no local base da tabela Iceberg. Somente a opção padrão LOAD_MODE = FULL_INGEST é compatível com esses cenários de carregamento de formato de arquivo que exigem conversão de tipo.

Para arquivos Apache Parquet, o Snowflake carrega os dados diretamente nas colunas da tabela e permite que você escolha entre as seguintes opções LOAD_MODE:

  • FULL_INGEST: examina os arquivos e reescreve os dados Parquet no local base da tabela Iceberg.

  • ADD_FILES_COPY: o binário copia os arquivos do Apache Parquet compatíveis com o Iceberg que não estão registrados em um catálogo Iceberg para o local base da tabela do Iceberg e, em seguida, registra os arquivos na tabela Iceberg.

Para obter mais informações, consulte COPY INTO <tabela>.

Exemplo: carregamento de arquivos Parquet compatíveis com o Iceberg

Este exemplo aborda como criar uma tabela Iceberg e, em seguida, carregar dados nela a partir de arquivos de dados Parquet compatíveis com o Iceberg em um estágio externo.

Para fins de demonstração, este exemplo usa os seguintes recursos:

  • Um volume externo nomeado iceberg_ingest_vol. Para criar um volume externo, consulte Configuração de um volume externo.

  • Um estágio externo nomeado my_parquet_stage com arquivos Parquet compatíveis com Iceberg. Para criar um estágio externo, consulte CREATE STAGE.

  1. Crie um objeto de formato de arquivo que descreva os arquivos Parquet em estágio, usando a configuração necessária para copiar dados Parquet compatíveis com Iceberg (TYPE = PARQUET USE_VECTORIZED_SCANNER = TRUE):

    CREATE OR REPLACE FILE FORMAT my_parquet_format
  TYPE = PARQUET
  USE_VECTORIZED_SCANNER = TRUE;
    Copy

  2. Crie uma tabela Iceberg gerenciada pelo Snowflake, definindo colunas com tipos de dados compatíveis com os tipos de dados do arquivo Parquet de origem:

    CREATE OR REPLACE ICEBERG TABLE customer_iceberg_ingest (
  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_ingest_vol'
  BASE_LOCATION = 'customer_iceberg_ingest/';
    Copy

    Nota

    A instrução de exemplo especifica os tipos de dados Iceberg que mapeiam para os tipos de dados Snowflake. Para obter mais informações, consulte Tipos de dados para tabelas Apache Iceberg™.

  3. Use uma instrução COPY INTO para carregar os dados dos arquivos Parquet preparados (localizados diretamente no caminho de URL do estágio) na tabela Iceberg:

    COPY INTO customer_iceberg_ingest
  FROM @my_parquet_stage
  FILE_FORMAT = 'my_parquet_format'
  LOAD_MODE = ADD_FILES_COPY
  PURGE = TRUE
  MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;
    Copy

    Nota

    O exemplo especifica LOAD_MODE = ADD_FILES_COPY, que diz ao Snowflake para copiar os arquivos no local do volume externo e, em seguida, registrar os arquivos na tabela.

    Essa opção evita cobranças de arquivos, pois o Snowflake não examina os arquivos Parquet de origem e reescreve os dados em novos arquivos Parquet.

    Saída:

    +---------------------------------------------------------------+--------+-------------+-------------+-------------+-------------+-------------+------------------+-----------------------+-------------------------+
| file                                                          | status | rows_parsed | rows_loaded | error_limit | errors_seen | first_error | first_error_line | first_error_character | first_error_column_name |
|---------------------------------------------------------------+--------+-------------+-------------+-------------+-------------+-------------+------------------+-----------------------+-------------------------|
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_008.parquet | LOADED |       15000 |       15000 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_006.parquet | LOADED |       15000 |       15000 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_005.parquet | LOADED |       15000 |       15000 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_002.parquet | LOADED |           5 |           5 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_010.parquet | LOADED |       15000 |       15000 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
+---------------------------------------------------------------+--------+-------------+-------------+-------------+-------------+-------------+------------------+-----------------------+-------------------------+

  4. Consultar a tabela:

    SELECT
    c_custkey,
    c_name,
    c_mktsegment
  FROM customer_iceberg_ingest
  LIMIT 10;
    Copy

    Saída:

    +-----------+--------------------+--------------+
| C_CUSTKEY | C_NAME             | C_MKTSEGMENT |
|-----------+--------------------+--------------|
|     75001 | Customer#000075001 | FURNITURE    |
|     75002 | Customer#000075002 | FURNITURE    |
|     75003 | Customer#000075003 | MACHINERY    |
|     75004 | Customer#000075004 | AUTOMOBILE   |
|     75005 | Customer#000075005 | FURNITURE    |
|         1 | Customer#000000001 | BUILDING     |
|         2 | Customer#000000002 | AUTOMOBILE   |
|         3 | Customer#000000003 | AUTOMOBILE   |
|         4 | Customer#000000004 | MACHINERY    |
|         5 | Customer#000000005 | HOUSEHOLD    |
+-----------+--------------------+--------------+

Exemplo: carregue os arquivos Parquet compatíveis com Iceberg na tabela criada com a função INFER_SCHEMA

Este exemplo explica como fazer o seguinte:

  1. Crie uma tabela Apache Iceberg™ usando a função INFER_SCHEMA.

  2. Carregue os dados a partir de arquivos de dados Parquet compatíveis com o Iceberg em um estágio externo.

Para fins de demonstração, este exemplo usa os seguintes recursos:

  • Um volume externo nomeado iceberg_ingest_vol. Para criar um volume externo, consulte Configuração de um volume externo.

  • Um estágio externo nomeado my_parquet_stage com arquivos Parquet compatíveis com Iceberg. Para criar um estágio externo, consulte CREATE STAGE.

  1. Crie um objeto de formato de arquivo que descreva os arquivos Parquet em estágio, usando a configuração necessária para copiar dados Parquet compatíveis com Iceberg (TYPE = PARQUET USE_VECTORIZED_SCANNER = TRUE):

    CREATE OR REPLACE FILE FORMAT my_parquet_format
  TYPE = PARQUET
  USE_VECTORIZED_SCANNER = TRUE;
    Copy

  2. Recuperar as definições das colunas para os arquivos Parquet no estágio my_parquet_stage:

    SELECT *
  FROM TABLE(
    INFER_SCHEMA(
      LOCATION=>'@my_parquet_stage/customer_iceberg/files-to-ingest/'
      , FILE_FORMAT=>'my_parquet_format'
      , KIND => 'ICEBERG'
      )
    );
    Copy

    Saída:

    +-------------+---------+----------+---------------------+------------------------------------------------------+----------+
| COLUMN_NAME | TYPE    | NULLABLE | EXPRESSION          | FILENAMES                                            | ORDER_ID |
|-------------+---------+----------+---------------------+------------------------------------------------------|----------+
| id          | INT     | False    | $1:id::INT          | customer_iceberg/files-to-ingest/customers.parquet   | 0        |
| custnum     | INT     | False    | $1:custnum::INT     | customer_iceberg/files-to-ingest/customers.parquet   | 1        |
+-------------+---------+----------+---------------------+------------------------------------------------------+----------+

  3. Crie uma tabela Iceberg usando o esquema detectado.

    CREATE ICEBERG TABLE myicebergtable
  USING TEMPLATE (
    SELECT ARRAY_AGG(OBJECT_CONSTRUCT(*))
    WITHIN GROUP (ORDER BY order_id)
      FROM TABLE(
        INFER_SCHEMA(
          LOCATION=>'@my_parquet_stage/customer_iceberg/files-to-ingest/',
          FILE_FORMAT=>'my_parquet_format',
          KIND => 'ICEBERG'
        )
      ))
 ... {rest of the ICEBERG options}
 ;
    Copy

    Nota

    Usar * para ARRAY_AGG(OBJECT_CONSTRUCT()) pode resultar em um erro se o resultado retornado for maior que 16MB. Recomendamos evitar o uso de * para conjuntos de resultados maiores e usar apenas as colunas necessárias, COLUMN NAME, TYPE e NULLABLE, para a consulta. A coluna opcional ORDER_ID pode ser incluída ao usar WITHIN GROUP (ORDER BY order_id).

  4. Use uma instrução COPY INTO para carregar os dados dos arquivos Parquet em estágios na tabela Iceberg:

    COPY INTO myicebergtable
  FROM @my_parquet_stage/customer_iceberg/files-to-ingest/
  FILE_FORMAT = 'my_parquet_format'
  LOAD_MODE = ADD_FILES_COPY
  MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;
    Copy

    Nota

    O exemplo especifica LOAD_MODE = ADD_FILES_COPY, que diz ao Snowflake para copiar os arquivos no local do volume externo e, em seguida, registrar os arquivos na tabela.

    Essa opção evita cobranças de arquivos, pois o Snowflake não examina os arquivos Parquet de origem e reescreve os dados em novos arquivos Parquet.

    Saída:

    +---------------------------------------------------------------------+--------+-------------+-------------+-------------+-------------+-------------+------------------+-----------------------+-------------------------+
| file                                                                | status | rows_parsed | rows_loaded | error_limit | errors_seen | first_error | first_error_line | first_error_character | first_error_column_name |
|---------------------------------------------------------------------+--------+-------------+-------------+-------------+-------------+-------------+------------------+-----------------------+-------------------------|
| my_parquet_stage/customer_iceberg/files-to-ingest/customers.parquet | LOADED |       15000 |       15000 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
+---------------------------------------------------------------------+--------+-------------+-------------+-------------+-------------+-------------+------------------+-----------------------+-------------------------+

  5. Após carregar os dados, consulte a tabela:

    SELECT
    id,
    custnum
  FROM myicebergtable
  LIMIT 10;
    Copy

    Saída:

    +-----------+---------+
| id        | custnum |
|-----------+---------+
|         1 |   75001 |
|         2 |   75002 |
|         3 |   75003 |
|         4 |   75004 |
|         5 |   75005 |
|         6 |   75006 |
|         7 |   75007 |
|         8 |   75008 |
|         9 |   75009 |
|        10 |   75010 |
+-----------+---------+
Linguagem: Português