Tabelas do BigQuery para Apache Iceberg

Para receber suporte durante a prévia, envie um e-mail para bigquery-tables-for-apache-iceberg-help@google.com.

As tabelas do BigQuery para Apache Iceberg (doravante, tabelas do Iceberg) fornecem a base para criar lakehouses de formato aberto no Google Cloud. As tabelas Iceberg oferecem a mesma experiência totalmente gerenciada das tabelas do BigQuery, mas armazenam dados em buckets de armazenamento do cliente usando o Parquet para serem interoperáveis com os formatos de tabelas abertas do Iceberg.

As tabelas Iceberg oferecem suporte aos seguintes recursos:

Arquitetura

As tabelas Iceberg trazem a conveniência do gerenciamento de recursos do BigQuery para tabelas que residem nos seus próprios buckets da nuvem. Com as tabelas Iceberg, é possível usar o BigQuery nelas sem mover os dados para fora dos buckets que você controla.

O diagrama a seguir mostra a arquitetura de tabelas gerenciadas em um nível geral: Diagrama da arquitetura do BigQuery para tabelas Iceberg.

Esse gerenciamento de tabelas tem as seguintes implicações no seu bucket:

  • O BigQuery cria novos arquivos de dados no bucket em resposta a solicitações de gravação e otimizações de armazenamento em segundo plano, como instruções DML e streaming.
  • Quando você exclui uma tabela gerenciada no BigQuery, ele não exclui os arquivos de dados associados. Confirme a exclusão excluindo manualmente os arquivos e os metadados da tabela exportada do bucket.
  • As tabelas Iceberg não geram custos de armazenamento do BigQuery. Veja mais informações em Faturamento.

A criação de uma tabela Iceberg é semelhante à criação de tabelas do BigQuery. Como ele armazena dados em formatos abertos no Cloud Storage, ele tem mais opções para:

  • Especificar a conexão de recursos do Cloud com WITH CONNECTION para configurar as credenciais de conexão do BigLake para acessar o Cloud Storage.
  • Especificar o formato do arquivo de armazenamento de dados com file_format. O PARQUET tem suporte no pré-lançamento.
  • Especificação do formato da tabela de metadados de código aberto com table_format. O ICEBERG tem suporte no pré-lançamento.

Práticas recomendadas

É crucial modificar as tabelas Iceberg apenas pelo BigQuery. Qualquer alteração ou adição direta ao bucket pode resultar em perda de dados ou erros irrecuperáveis. A tabela a seguir mostra os possíveis cenários:

Operação Consequências Prevenção
Adicione novos arquivos ao bucket fora do BigQuery. Perda de dados: novos arquivos ou objetos adicionados fora do BigQuery não são rastreados por ele. Os arquivos não rastreados são excluídos por processos de coleta de lixo em segundo plano. Adicione dados exclusivamente pelo BigQuery. Isso permite que o BigQuery rastreie os arquivos e evite que eles sejam coletados.
Para evitar adições acidentais e perda de dados, também recomendamos restringir as permissões de gravação de ferramentas externas em buckets que contêm tabelas Iceberg.
Crie uma nova tabela Iceberg em um prefixo não vazio. Perda de dados: os dados existentes não são rastreados pelo BigQuery. Portanto, esses arquivos são considerados não rastreados e excluídos por processos de coleta de lixo em segundo plano. Crie novas tabelas do Iceberg apenas em prefixos vazios.
Modifique ou substitua os arquivos de dados da tabela do Iceberg. Perda de dados: em caso de modificação ou substituição externa, a tabela falha em uma verificação de consistência e fica ilegível. As consultas na tabela falham.
Não há como recuperar o acesso de forma autoatendimento. Entre em contato com o suporte para receber ajuda com a recuperação de dados.		 Modifique os dados exclusivamente pelo BigQuery. Isso permite que o BigQuery rastreie os arquivos e evite que eles sejam coletados.
Para evitar adições acidentais e perda de dados, também recomendamos restringir as permissões de gravação de ferramentas externas em buckets que contêm tabelas Iceberg.
Crie duas tabelas do BigQuery para o Apache Iceberg com os mesmos URIs ou com URIs sobrepostos. Perda de dados: o BigQuery não conecta instâncias de URI idênticas de tabelas Iceberg. Os processos de coleta de lixo em segundo plano para cada tabela vão considerar os arquivos da tabela oposta como não rastreados e excluí-los, causando perda de dados. Use URIs exclusivos para cada tabela do Iceberg.

Faturamento

Os recursos a seguir são cobrados usando os preços publicados:

  • Preços do Cloud Storage para todos os dados armazenados em buckets do Cloud Storage, processamento de dados feito pelo Cloud Storage e uso da rede para a quantidade de dados lidos do bucket.
  • Preços de computação do BigQuery para consultas, DML e otimização de armazenamento em segundo plano (incluindo agrupamento, coalescência e coleta de lixo).
    • As cobranças usando reservas (slots) seguem os preços de slot atuais.
    • As cobranças que usam as unidades de manutenção de estoque (SKUs) on demand seguem os preços on demand atuais. Para mais informações, consulte Custos do BigLake.
  • A computação de carga em lote e de extração é cobrada usando SKUs on demand ou reservas (slots).
  • Preços da API Storage Write para leitura do Spark pela API Read.
  • Preços da API Storage Write para streaming.

Fluxos de trabalho de tabelas Iceberg

As seções a seguir descrevem como criar, carregar, gerenciar e consultar tabelas gerenciadas.

Antes de começar

Antes de criar e usar tabelas do Iceberg, configure uma conexão de recursos do Cloud a um bucket de armazenamento. Sua conexão precisa de permissões de gravação no bucket de armazenamento, conforme especificado na seção Papéis obrigatórios a seguir.

Funções exigidas

Para receber as permissões necessárias para permitir que o BigQuery gerencie tabelas no seu projeto, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para permitir que o BigQuery gerencie tabelas no seu projeto. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para permitir que o BigQuery gerencie tabelas no seu projeto:

  • bigquery.connections.delegate no seu projeto
  • bigquery.jobs.create no seu projeto
  • bigquery.readsessions.create no seu projeto
  • bigquery.tables.create no seu projeto
  • bigquery.tables.get no seu projeto
  • bigquery.tables.getData no seu projeto
  • storage.buckets.get no seu projeto
  • storage.objects.create no seu projeto
  • storage.objects.delete no seu projeto
  • storage.objects.get no seu projeto
  • storage.objects.list no seu projeto

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Criar tabelas Iceberg

Para criar uma tabela Iceberg, selecione um dos seguintes métodos:

SQL 

CREATE TABLE [PROJECT_NAME.]DATASET_NAME.TABLE_NAME (
COLUMN DATA_TYPE[, ...]
)
CLUSTER BY CLUSTER_COLUMN_LIST
WITH CONNECTION CONNECTION_NAME
OPTIONS (
file_format = 'PARQUET',
table_format = 'ICEBERG',
storage_uri = 'STORAGE_URI');

Substitua:

  • PROJECT_NAME: o projeto que contém o conjunto de dados. Se não for definido, o comando vai assumir o projeto padrão.
  • DATASET_NAME: um conjunto de dados existente.
  • TABLE_NAME: o nome da tabela que você está criando;
  • DATA_TYPE: o tipo de dados das informações contidas na coluna.
  • CLUSTER_COLUMN_LIST: uma lista separada por vírgulas que contém até quatro colunas. Elas precisam ser de nível superior e não repetidas.
  • CONNECTION_NAME: o nome da conexão. Por exemplo, myproject.us.myconnection.
  • STORAGE_URI: um URI do Cloud Storage totalmente qualificado. Por exemplo, gs://mybucket/table.

bq 

bq --project_id=PROJECT_NAME mk \
    --file_format=PARQUET \
    --table_format=ICEBERG \
    --connection_id=CONNECTION_NAME \
    --storage_uri=STORAGE_URI \
    --schema=COLUMN_NAME:DATA_TYPE[, ...] \
    --clustering_fields=CLUSTER_COLUMN_LIST \
    MANAGED_TABLE_NAME

Substitua:

  • PROJECT_NAME: o projeto que contém o conjunto de dados. Se não for definido, o comando vai assumir o projeto padrão.
  • CONNECTION_NAME: o nome da conexão. Por exemplo, myproject.us.myconnection.
  • STORAGE_URI: um URI do Cloud Storage totalmente qualificado. Por exemplo, gs://mybucket/table.
  • COLUMN_NAME: o nome da coluna.
  • DATA_TYPE: o tipo de dados das informações contidas na coluna.
  • CLUSTER_COLUMN_LIST: uma lista separada por vírgulas que contém até quatro colunas. Elas precisam ser de nível superior e não repetidas.
  • MANAGED_TABLE_NAME: o nome da tabela que você está criando.

API

Chame o método tables.insert com um recurso de tabela definido, semelhante a este:

{
"tableReference": {
  "tableId": "TABLE_NAME"
},
"biglakeConfiguration": {
  "connectionId": "CONNECTION_NAME",
  "fileFormat": "PARQUET",
  "tableFormat": "ICEBERG",
  "storageUri": "STORAGE_URI"
},
"schema": {
  "fields": [
    {
      "name": "COLUMN_NAME",
      "type": "DATA_TYPE"
    }
    [, ...]
  ]
}
}

Substitua:

  • TABLE_NAME: o nome da tabela que você está criando.
  • CONNECTION_NAME: o nome da conexão. Por exemplo, myproject.us.myconnection.
  • STORAGE_URI: um URI do Cloud Storage totalmente qualificado. Os caracteres curinga também são compatíveis. Por exemplo, gs://mybucket/table.
  • COLUMN_NAME: o nome da coluna.
  • DATA_TYPE: o tipo de dados das informações contidas na coluna.

Importar dados para a tabela Iceberg

As seções a seguir descrevem como importar dados de vários formatos de tabela para tabelas do Iceberg.

Carga rápida de arquivos Parquet

A opção copy_files_only permite carregar dados mais rapidamente copiando seus arquivos Parquet atuais, em vez de ler o conteúdo e gravá-lo como novos arquivos. O carregamento rápido usa menos capacidade de computação em comparação com um carregamento de arquivo normal. Os arquivos Parquet precisam ser compatíveis com a especificação do Apache Iceberg e ter estatísticas de colunas completas. O carregamento rápido não detecta valores inválidos (como carimbos de data/hora fora de alcance) em arquivos porque eles não são lidos e reprocessados. Para mais informações sobre como carregar arquivos Parquet, consulte Como carregar dados Parquet em uma nova tabela.

Para carregar rapidamente arquivos Parquet simples em uma tabela Iceberg, use o comando bq load:

bq load \
    --copy_files_only \
    --source_format=PARQUET \
    DATASET_NAME.TABLE_NAME \
    PATH_TO_SOURCE

Substitua:

  • DATASET_NAME: o conjunto de dados que contém a tabela Iceberg.
  • TABLE_NAME: o nome da tabela Iceberg em que você está carregando dados.
  • PATH_TO_SOURCE: um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Os caracteres curinga também são compatíveis. Por exemplo, gs://mybucket/mydata*.parquet.

Carregar dados padrão de arquivos simples

As tabelas Iceberg usam jobs de carregamento do BigQuery para carregar arquivos externos nas tabelas Iceberg. Se você tiver tabelas do Iceberg, siga o guia da CLI bq load ou o guia do SQL LOAD para carregar dados externos. Depois de carregar os dados, novos arquivos Parquet são gravados na pasta STORAGE_URI/data.

Se as instruções anteriores forem usadas sem uma tabela do Iceberg, uma tabela do BigQuery será criada.

Confira a seguir exemplos específicos de ferramentas de carregamentos em lote em tabelas gerenciadas:

SQL 

LOAD DATA INTO MANAGED_TABLE_NAME
FROM FILES (
uris=['STORAGE_URI'],
format='FILE_FORMAT');

Substitua:

  • MANAGED_TABLE_NAME: o nome de uma tabela Iceberg
  • STORAGE_URI: um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Os caracteres curinga também são compatíveis. Por exemplo, gs://mybucket/table.
  • FILE_FORMAT: o formato da tabela de origem. Para saber quais formatos são aceitos, consulte a linha format de load_option_list.

bq 

bq load \
  --source_format=FILE_FORMAT \
  MANAGED_TABLE \
  STORAGE_URI

Substitua:

  • FILE_FORMAT: o formato da tabela de origem. Para saber quais formatos são aceitos, consulte a linha format de load_option_list.
  • MANAGED_TABLE_NAME: o nome de uma tabela Iceberg
  • STORAGE_URI: um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separada por vírgulas. Os caracteres curinga também são compatíveis. Por exemplo, gs://mybucket/table.

Carga padrão de arquivos particionados do Hive

É possível carregar arquivos particionados pelo Hive em tabelas do Iceberg usando jobs de carregamento padrão do BigQuery. Para mais informações, consulte Como carregar dados particionados externamente.

Carregar dados de streaming do Pub/Sub

É possível carregar dados de streaming nas tabelas Iceberg usando uma assinatura do Pub/Sub no BigQuery.

Exportar dados das tabelas Iceberg

As seções a seguir descrevem como exportar dados de tabelas do Iceberg para vários formatos de tabela.

Exportar dados para formatos simples

Para exportar uma tabela Iceberg para um formato plano, use a instrução EXPORT DATA e selecione um formato de destino. Para mais informações, consulte Como exportar dados.

Exportar metadados como uma tabela Iceberg

Para exportar os metadados de uma tabela do Iceberg como uma tabela do Iceberg, selecione um dos seguintes métodos:

bq

Use a instrução EXPORT TABLE METADATA.

O exemplo a seguir exporta metadados de tabela no formato Iceberg na pasta metadata em storage_uri para a tabela:

bq query \
  --nouse_legacy_sql \
  --nouse_cache "EXPORT TABLE METADATA FROM TABLE_NAME"

Spark

No Apache Spark, é possível exportar metadados de tabela com o HadoopCatalog.

O exemplo a seguir configura seu ambiente para usar o Spark SQL com o Apache Iceberg, estabelece um catálogo para gerenciar as tabelas do Iceberg e executa uma consulta para buscar dados de uma tabela do Iceberg especificada.

spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-ICEBERG_VERSION_NUMBER \
  --conf spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.CATALOG_NAME.type=hadoop \
  --conf spark.sql.catalog.CATALOG_NAME.warehouse='BUCKET_PATH' \

# Queries the table
spark-sql> SELECT * FROM CATALOG_NAME.FOLDER_NAME;

Substitua:

  • ICEBERG_VERSION_NUMBER: a versão atual do ambiente de execução do Apache Spark Iceberg. Faça o download da versão mais recente em Lançamentos do Spark.
  • CATALOG_NAME: o catálogo para referenciar a tabela Iceberg.
  • BUCKET_PATH: o caminho para o bucket que contém os arquivos de tabela. Por exemplo, gs://mybucket/.
  • FOLDER_NAME: a pasta que contém os arquivos de tabela. Por exemplo, myfolder.

Modificar tabelas do Iceberg

Para modificar uma tabela Iceberg, siga as etapas em Como modificar esquemas de tabelas.

Preços

O preço da tabela Iceberg consiste em três componentes separados:

Armazenamento

A tabela Iceberg armazena todos os dados em storage_name. Você vai receber cobrança por todos os dados armazenados, incluindo os dados históricos da tabela. O processamento de dados e as taxas de transferência do Cloud Storage também podem ser aplicáveis. Não há taxas de armazenamento específicas do BigQuery. Para mais informações, consulte Preços do Cloud Storage.

Otimização de armazenamento

As tabelas Iceberg exigem operações de otimização de armazenamento, como a união de arquivos e a reclusterização. Essas operações de otimização usam slots de pagamento conforme o uso da edição Enterprise e não usam reservas BACKGROUND atuais.

As operações de exportação de dados que ocorrem durante o streaming pela API Storage Write do BigQuery estão incluídas nos preços da API Storage Write e não são cobradas como manutenção em segundo plano. Para mais informações, consulte Preços de ingestão de dados do BigQuery.

Consultas e jobs

Assim como nas tabelas do BigQuery, você vai receber cobranças por consultas e bytes lidos (por TiB) se estiver usando o preço on demand do BigQuery ou o consumo de slots (por hora de slot) se estiver usando o preço de computação de capacidade do BigQuery.

Os preços do BigQuery também se aplicam à API BigQuery Storage Read e à API BigQuery Storage Write.

As operações de carga e exportação (como EXPORT METADATA) usam slots de pagamento por uso da edição Enterprise. Isso é diferente das tabelas do BigQuery, que não são cobradas por essas operações. Se as reservas PIPELINE com slots Enterprise ou Enterprise Plus estiverem disponíveis, as operações de carregamento e exportação vão usar preferencialmente esses slots de reserva.

Limitações

As tabelas Iceberg têm as seguintes limitações:

  • As tabelas Iceberg não oferecem suporte a operações de renomeação.
  • As tabelas Iceberg não são compatíveis com o seguinte esquema de tabela:
  • EXPORT METADATA não é compatível com tabelas que contêm o seguinte:
    • Tipos de dados de GEOGRAPHY
    • Tipos de dados BIGNUMERIC ou NUMERIC com precisão maior que 38 casas.
  • As tabelas Iceberg não oferecem suporte aos seguintes casos de evolução do esquema:
    • Coerções de tipo NUMERIC para FLOAT
    • Coerções de tipo INT para FLOAT
    • Adicionar novos campos aninhados a colunas RECORD usando instruções DDL SQL
  • As tabelas Iceberg mostram um tamanho de armazenamento de 0 bytes quando consultadas pelo console ou pelas APIs.
  • As tabelas Iceberg não são compatíveis com visualizações materializadas.
  • As tabelas Iceberg não são compatíveis com transações de várias instruções.
  • As tabelas Iceberg não oferecem suporte a cópias, clones ou snapshots de tabelas.
  • As tabelas Iceberg não oferecem suporte a atualizações de captura de dados alterados (CDC).
  • As tabelas Iceberg não oferecem suporte à recuperação de desastres gerenciada
  • As tabelas Iceberg não são compatíveis com o particionamento. Considere agrupar como uma alternativa.
  • As tabelas Iceberg não oferecem suporte à segurança no nível da linha.
  • As tabelas Iceberg não são compatíveis com a viagem no tempo.
  • As tabelas Iceberg não são compatíveis com janelas de fail-safe.
  • As tabelas Iceberg não oferecem suporte a jobs de extração.
  • A visualização INFORMATION_SCHEMA.TABLE_STORAGE não inclui tabelas Iceberg.
  • As tabelas Iceberg não são aceitas como destinos de resultados de consulta.
  • O CREATE OR REPLACE não oferece suporte à substituição de tabelas padrão por tabelas Iceberg ou vice-versa.
  • As instruções CREATE TABLE COPY não são compatíveis com tabelas Iceberg.
  • As instruções ALTER TABLE RENAME TO não são compatíveis com tabelas Iceberg.
  • O LOAD DATA OVERWRITE não oferece suporte a tabelas Iceberg como destino de substituição.
  • TRUNCATE TABLE não oferece suporte a tabelas Iceberg. Existem duas alternativas:
  • A função com valor de tabela (TVF) APPENDS não é compatível com tabelas Iceberg.
  • O carregamento em lote em tabelas Iceberg não oferece suporte a:
    • Adicionar colunas a tabelas.
    • Relaxar os modos ou tipos de coluna.
    • Criação de novas tabelas Iceberg.
    • Substituir uma tabela (também conhecido como writeDisposition WRITE_TRUNCATE).
  • As exportações do Iceberg no Apache Spark não contêm dados transmitidos recentemente no armazenamento otimizado para gravação.
  • O carregamento rápido não é compatível com arquivos com nomes de colunas flexíveis.