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 do BigQuery para Apache Iceberg são diferentes das tabela externas do BigLake para Apache Iceberg porque apenas as tabelas do BigQuery para Apache Iceberg podem ser modificadas diretamente no BigQuery. As tabelas externas do BigLake para o Apache Iceberg são tabelas somente leitura geradas em outro mecanismo de consulta, como o Apache Spark, e só podem ser consultadas usando o BigQuery.

As tabelas Iceberg são compatíveis com os seguintes recursos:

  • Mutações de tabela usando a linguagem de manipulação de dados (DML) do GoogleSQL.
  • Streaming unificado de lote e de alta capacidade de processamento usando a API StorageWrite com os conectores do BigLake, como Spark, Dataflow e outros mecanismos.
  • Evolução do esquema, que permite adicionar, soltar e renomear colunas de acordo com suas necessidades. Esse recurso também permite mudar o tipo de dados de uma coluna e o modo de coluna. Para mais informações, consulte as regras de conversão de tipo.
  • Otimização automática de armazenamento, incluindo dimensionamento de arquivos adaptável, clustering automático, coleta de lixo e otimização de metadados.
  • Segurança no nível da coluna e mascaramento de dados.

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 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 de tabela exportados do bucket.
  • As tabelas Iceberg não incorrem em 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:

  • Especifique 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 na visualização.
  • Especificar o formato da tabela de metadados de código aberto com table_format. O ICEBERG tem suporte na visualização.

Práticas recomendadas

Mudar ou adicionar arquivos diretamente ao bucket fora do BigQuery pode causar perda de dados ou erros irreversíveis. A tabela a seguir descreve 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 do 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 apenas novas tabelas Iceberg 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 por conta própria. 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.

Consideração de local

É possível melhorar a performance usando buckets de região única ou birregional do Cloud Storage em vez de buckets multirregionais.

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 que usam reservas (slots) seguem os preços 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ço da API Storage Read para ler 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, verifique se você configurou uma conexão de recursos do Cloud em 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 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 coluna completas. O carregamento rápido não detecta valores inválidos (como carimbos de data/hora fora do intervalo) 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 do 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 carga do BigQuery para carregar arquivos externos nelas. Se você tiver uma tabela do Iceberg, siga o guia da CLI bq load ou o guia 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 do 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 em 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 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.

Ler tabelas Iceberg com metadados do Iceberg

Para ler dados das tabelas Iceberg no formato Iceberg, siga estas etapas:

  1. Exporte os metadados para o formato Iceberg com a instrução SQL EXPORT TABLE METADATA.

  2. Configure e leia dados de tabelas no Apache Spark com o HadoopCatalog.

    O exemplo a seguir configura seu ambiente para usar o Spark SQL com o Apache Iceberg e, em seguida, executa uma consulta para buscar dados de uma tabela 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 do 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 no Cloud Storage. Você vai receber cobrança por todos os dados armazenados, incluindo os dados históricos da tabela. As cobranças de processamento de dados e de transferência do Cloud Storage também podem ser aplicadas. 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 reclassificaçã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 carga e exportação vão usar preferencialmente esses slots de reserva.

Limitações

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