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

Importante

O registro de arquivos Parquet usando ADD_FILES_COPY não é recomendado se esses arquivos já fazem parte de outra tabela Iceberg.

A prática recomendada para converter tabelas Iceberg gerenciadas externamente em tabelas Iceberg gerenciadas pelo Snowflake sem reescrever arquivos é usar o comando ALTER ICEBERG TABLE … CONVERT TO MANAGED.

Considerações e limitações ao carregar dados em tabelas Iceberg¶

Para carregar as colunas de metadados de linhagem de linhas para arquivos Parquet, que são _row_id e _last_updated_sequence_number, você deve usar a opção FULL_INGEST. As outras opções LOAD_MODE não são compatíveis. No entanto, os arquivos Parquet que contêm a linhagem de linhas provavelmente já fazem parte de uma tabela Iceberg v3. Para as práticas recomendadas de como lidar com arquivos Parquet que já fazem parte de outra tabela Iceberg, consulte a observação acima.

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

Este exemplo mostra como criar uma tabela Iceberg e, em seguida, carregar os dados nela de arquivos de dados Parquet compatíveis com o Iceberg em uma área de preparação externa.

Importante

O registro de arquivos Parquet usando ADD_FILES_COPY não é recomendado se esses arquivos já fazem parte de outra tabela Iceberg. A prática recomendada para converter tabelas Iceberg gerenciadas externamente em tabelas Iceberg gerenciadas pelo Snowflake sem reescrever arquivos é usar o comando ALTER ICEBERG TABLE … CONVERT TO MANAGED.

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.

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

Este exemplo usa nomes de colunas que diferenciam maiúsculas de minúsculas. Você deve colocar os nomes das colunas entre aspas duplas ao criar a tabela Iceberg e especificar os nomes das colunas exatamente como aparecem no rodapé do Parquet.
```
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™.

Para carregar os dados dos arquivos Parquet preparados, localizados diretamente no caminho URL da área de preparação, na tabela Iceberg, use uma instrução COPY INTO:

Nas instruções COPY INTO <tabela> com LOAD_MODE = ADD_FILES_COPY, somente MATCH_BY_COLUMN_NAME = CASE_SENSITIVE é compatível.

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

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:

Crie uma tabela Apache Iceberg™ usando a função INFER_SCHEMA.
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.

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

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

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).

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

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