Configurar opções de tabela

Ao configurar as opções de tabela, é possível ativar a interoperabilidade de gravação do BigQuery ou o gerenciamento de tabelas (otimização automática de armazenamento) para as tabelas do Apache Iceberg no catálogo de ambientes de execução do Lakehouse. Essas opções servem como configurações básicas que ampliam os recursos para operações na tabela.

Ao configurar propriedades específicas da tabela, é possível ativar a interoperabilidade de gravação com a DML do BigQuery ou o gerenciamento automático de tabelas (otimização de armazenamento).

Ao usar tabelas no catálogo de tempo de execução do lakehouse, é útil entender os diferentes tipos de tabelas e os recursos de ativação. Para saber mais sobre o uso de tabelas do Apache Iceberg, consulte Visão geral das tabelas do Apache Iceberg.

Antes de começar

  1. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  2. Ative a API BigLake.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar a API

  3. Configure o catálogo de ambientes de execução do Lakehouse com o endpoint do catálogo REST do Apache Iceberg.

Funções exigidas

Para ter as permissões necessárias para configurar opções de tabela, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto e no bucket de armazenamento:

  • Configure as propriedades da tabela no modo de venda de credenciais: Editor do BigLake (roles/biglake.editor): o projeto
  • Configure as propriedades da tabela no modo sem fornecimento de credenciais:
    • Editor do BigLake (roles/biglake.editor): o projeto
    • Usuário de objetos do Storage (roles/storage.objectUser): o bucket do Cloud Storage

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

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Considerações sobre a configuração

Considere os seguintes requisitos e comportamentos padrão ao configurar opções de tabela:

Tabelas do Iceberg compatíveis

Somente tabelas do Apache Iceberg V2 (GA) e V3 (pré-lançamento) são compatíveis. Não há suporte para tabelas do Iceberg V1. Para fazer upgrade das tabelas V1 atuais, consulte Fazer upgrade das tabelas Iceberg V1 para V2.

Requisito de fornecimento de credenciais

Para ativar o gerenciamento automático de tabelas, o catálogo de ambiente de execução do lakehouse precisa ter a venda de credenciais ativada no nível do catálogo. Os jobs em segundo plano de gerenciamento de tabelas usam a conta do serviço de venda de credenciais para autenticar e atualizar os arquivos de dados de armazenamento subjacentes.

Ativar a DML do BigQuery

Ao ativar as instruções da linguagem de manipulação de dados (DML) do BigQuery, você desbloqueia a interoperabilidade de gravação do BigQuery em tabelas do Apache Iceberg criadas com mecanismos de código aberto.

As instruções aceitas incluem INSERT, UPDATE, DELETE e MERGE, além de instruções DDL padrão, como CREATE TABLE, ALTER TABLE e DROP TABLE, exceto aquelas que não são aceitas em tabelas do Apache Iceberg no BigQuery.

Ativar a DML do BigQuery para novas tabelas

Quando você cria uma tabela no BigQuery, a DML do BigQuery e o gerenciamento automático de tabelas são ativados por padrão. Ao criar uma tabela usando mecanismos de código aberto, configure a propriedade gcp.biglake.bigquery-dml.enabled = true usando a sintaxe DDL do seu mecanismo.

Por exemplo, no Spark SQL:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Ativar a DML do BigQuery para tabelas atuais

Para ativar a DML do BigQuery em uma tabela atual, atualize a propriedade da tabela.

Por exemplo, no Spark SQL:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Desativar a DML do BigQuery

Desativar a DML do BigQuery torna a tabela somente leitura para o BigQuery e interrompe o gerenciamento automático de tabelas.

Por exemplo, no Spark SQL:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

Ativar o gerenciamento de tabelas

O gerenciamento de tabelas automatiza processos em segundo plano para otimizar o armazenamento e gerenciar o ciclo de vida de dados e metadados, como compactação e coleta de lixo.

Com o gerenciamento de tabelas, você pode realizar as seguintes operações:

  • Expiração de snapshots e coleta de lixo:a expiração de snapshots gerencia a retenção e exclusão de dados e arquivos de metadados de snapshots de tabelas. Isso é executado automaticamente em segundo plano após qualquer mutação de dados. Os snapshots expiram com base nas propriedades da tabela do Iceberg configuradas pelo usuário history.expire.max-snapshot-age-ms e history.expire.min-snapshots-to-keep. Ele remove as entradas de snapshot expiradas do arquivo metadata.json, seguidas pela exclusão física dos arquivos de dados e metadados que pertenciam apenas aos snapshots expirados e não são mais referenciados por nenhum snapshot ativo.

    • Limitação: a expiração do snapshot e a coleta de lixo associada são ignoradas se a tabela usar tags ou ramificações. Saiba mais em Limitações.

    • Limitação: a remoção de arquivos órfãos não é processada pelo gerenciamento automático de tabelas. Para mais informações, consulte Limitações.

  • União (compactação): a união é responsável por manter o formato dos dados, mesclando arquivos pequenos em arquivos maiores. A coalescência é executada automaticamente em segundo plano após qualquer mutação de dados. Os arquivos são selecionados para compactação se o tamanho médio descompactado for menor que 50% do tamanho de arquivo de destino de 256 MB. Cada operação de coalescência produz um novo instantâneo de tabela. Os jobs de coalescência geralmente cedem e tentam novamente após qualquer operação DML em execução. No entanto, para evitar a falta indefinida de otimização de armazenamento, um job de coalescência é acionado à força a cada 24 horas se os dados forem qualificados para coalescência.

  • Jobs de gerenciamento de tabelas de monitoramento:todos os jobs de gerenciamento de tabelas em segundo plano são registrados na visualização INFORMATION_SCHEMA.JOBS do BigQuery. É possível consultar essa visualização para acompanhar essas operações, assim como você monitora outros jobs do BigQuery. Para mais informações sobre como consultar informações de jobs, consulte Receber jobs de otimização de armazenamento do Iceberg.

    A frequência dos jobs de gerenciamento de tabelas está diretamente relacionada à atividade de mutação de dados. Inserções ou atualizações pequenas e frequentes acionam tarefas em segundo plano com mais frequência. Você pode observar períodos sem jobs em segundo plano se não houver gravações na tabela. Por outro lado, volumes altos de gravação podem resultar em uma atividade de job mais visível em INFORMATION_SCHEMA.

Ativar o gerenciamento de tabelas para novas tabelas

Quando você cria uma tabela no BigQuery, a DML e o gerenciamento automático de tabelas são ativados por padrão. Ao criar uma tabela com mecanismos de código aberto, configure a propriedade gcp.biglake.table-management.enabled. Ao ativar o gerenciamento de tabelas, a DML do BigQuery também é ativada automaticamente, caso ainda não esteja.

Por exemplo, no Spark SQL:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

Ativar o gerenciamento de tabelas para tabelas atuais

Para ativar o gerenciamento de tabelas em uma tabela atual, atualize a propriedade da tabela.

Por exemplo, no Spark SQL:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

Desativar o gerenciamento de tabelas

Desativar o gerenciamento de tabelas impede que futuros jobs de otimização em segundo plano sejam enfileirados, mas os jobs ativos em andamento serão concluídos. Desativar o gerenciamento de tabelas não desativa a DML do BigQuery.

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);

BigQuery 

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");

Limitações

As limitações dos recursos gerenciados (como interoperabilidade de gravação do BigQuery e gerenciamento automático de tabelas) incluem:

Limitações gerais

  • Os recursos gerenciados são compatíveis apenas com tabelas do Apache Iceberg criadas no catálogo do ambiente de execução do Lakehouse usando o endpoint do catálogo REST do Apache Iceberg.
  • Todas as limitações atuais das tabelas do Apache Iceberg gerenciadas pelo BigQuery se aplicam às operações com recursos gerenciados ativados.
  • Não há suporte para recursos gerenciados em tabelas com a versão 3 do formato do Apache Iceberg. Somente tabelas no formato versão 2 (especificação do Iceberg v2) podem ser ativadas para recursos gerenciados.
  • Os recursos gerenciados não são compatíveis com tabelas que têm particionamento avançado, como por STRING, várias colunas ou evolução de partição.
  • As funcionalidades gerenciadas não são compatíveis com tabelas configuradas com ordens de classificação (por exemplo, usando o procedimento WRITE ORDER BY ou definindo write.distribution.mode = range).
  • Os recursos gerenciados não são compatíveis com tabelas do Iceberg v2 usando o modo merge-on-read. Somente tabelas que usam o modo de atualização, exclusão e mesclagem de cópia na gravação podem ser ativadas para recursos gerenciados.
  • Os recursos gerenciados não são compatíveis com arquivos de dados compactados usando codecs gzip, lz4 ou brotli (write.parquet.compression.codec). Apenas os tipos de compactação zstd e snappy são compatíveis com arquivos de dados.
  • Os recursos gerenciados não são compatíveis com tabelas se o esquema contiver identificadores de chave primária aninhados (identifier-field-ids) que referenciam caminhos ou campos aninhados em uma estrutura.
  • Os recursos gerenciados não são compatíveis com tabelas que têm dados personalizados ou locais de metadados (write.data.path e write.metadata.path). O local padrão do bucket do Cloud Storage é necessário para armazenar arquivos de dados e metadados.
  • O clustering do BigQuery não é compatível com tabelas do Apache Iceberg gerenciadas pelo catálogo de ambientes de execução do Lakehouse.
  • Se uma tabela for criada com o tipo de dados NUMERIC no BigQuery, todas as atualizações de esquema do Spark vão falhar porque o Spark lê NUMERIC como NUMERIC(38,9). Como solução alternativa, ao criar tabelas com o tipo NUMERIC no BigQuery, defina explicitamente a precisão como NUMERIC(38,9).
  • Problema conhecido:não é possível excluir uma coluna no BigQuery usando DDL (ALTER TABLE ... DROP COLUMN) e adicionar outra com o mesmo nome.

Limitações da viagem no tempo

  • Quando o gerenciamento de tabelas está ativado, o valor máximo recomendado para a propriedade history.expire.max-snapshot-age-ms é de sete dias.
  • As configurações de viagem no tempo no nível do projeto ou do conjunto de dados do BigQuery não se aplicam. Somente as propriedades e os padrões da tabela Iceberg estão ativos.

Limitações no gerenciamento de tabelas

  • A expiração do snapshot é ignorada para toda a tabela se ela contiver snapshots com tags ou ramificações. A retenção personalizada definida usando ALTER... RETAIN x DAYS é ignorada, assim como os valores definidos para a propriedade history.expire.max-ref-age-ms. Os mecanismos de código aberto ainda podem realizar a expiração de snapshots.
  • O gerenciamento automático de tabelas não expira esquemas nem especificações de partição. O arquivo metadata.json retém o histórico completo de esquemas e especificações de partição, mesmo que nenhum snapshot se refira a esses IDs de esquema.

  • Os arquivos órfãos criados pelo BigQuery ou por mecanismos de código aberto não são limpos pelo gerenciamento automático de tabelas. Os mecanismos de código aberto podem realizar a limpeza de arquivos órfãos. Por exemplo, usando o procedimento Spark remove_orphan_files com a opção prefix_listing definida como true.

  • O Coalesce não oferece suporte à ordenação Z e à classificação linear. Se a tabela tiver essas propriedades, não há garantia de que o layout será mantido após a execução da coalescência. Se as tabelas tiverem essas propriedades, a melhor ação é não ativar o gerenciamento de tabelas.

Limitações com o particionamento

  • Ao criar ou registrar tabelas de mecanismos de código aberto, os recursos gerenciados só oferecem suporte a particionamento em tipos de campo DATE, TIMESTAMP e TIMESTAMPTZ com transformações hour, day, month e year (exceto a transformação hour em campos DATE).
  • Os recursos gerenciados não são compatíveis com tabelas que têm transformações IDENTITY. Os usuários precisam especificar explicitamente a transformação.
  • Os comandos CREATE OR REPLACE em tabelas com recursos gerenciados só são compatíveis se usarem a mesma especificação de partição. As substituições a seguir não são compatíveis:
    • Substituir uma tabela não particionada por uma tabela particionada.
    • Substituir uma tabela particionada por uma não particionada.
    • Substituir uma tabela particionada por uma tabela que usa uma especificação de particionamento diferente.
  • Não é possível personalizar o nome do campo de partição. As tabelas criadas ou registradas de mecanismos de código aberto precisam seguir a convenção de nomenclatura padrão do campo de partição do mecanismo (adicionando _ e o nome da transformação, como _hour, _day, _month ou _year). Por exemplo, para um campo chamado time_date usando a transformação DAY, o valor esperado do campo de partição é: json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

Limitações com propriedades personalizadas da tabela Iceberg

As propriedades de comportamento da tabela a seguir não podem ser configuradas para valores diferentes dos padrões quando as funcionalidades gerenciadas estão ativadas. Os valores padrão são codificados quando qualquer recurso gerenciado está ativado:

Propriedade Valor padrão Detalhes
format-version 2 Os recursos gerenciados só são compatíveis com tabelas Iceberg v2.
write.format.default parquet As tabelas só são compatíveis com arquivos de dados no formato Parquet.
write.data.path table location + /data O caminho padrão do bucket do Cloud Storage configurado para o catálogo REST do data lakehouse é usado para gravar arquivos de dados.
write.metadata.path table location + /metadata O caminho padrão do bucket do Cloud Storage configurado para o catálogo REST do Lakehouse é usado para gravar arquivos de metadados.
write.delete.mode copy-on-write Os jobs de gravação e gerenciamento de tabelas do BigQuery só aceitam cópia na gravação.
write.update.mode copy-on-write Os jobs de gravação e gerenciamento de tabelas do BigQuery só aceitam cópia na gravação.
write.merge.mode copy-on-write Os jobs de gravação e gerenciamento de tabelas do BigQuery só aceitam cópia na gravação.
write.delete.isolation-level Detecção estrita de conflitos As mudanças que modificam o arquivo metadata.json (incluindo conflitos de dados e metadados, leituras fantasmas ou gravações simultâneas sem conflitos) fazem com que a transação simultânea falhe e seja repetida.
write.update.isolation-level Detecção estrita de conflitos Mesmo comportamento que write.delete.isolation-level.
write.merge.isolation-level Detecção estrita de conflitos Mesmo comportamento que write.delete.isolation-level.

As propriedades a seguir podem ser configuradas ao criar ou alterar tabelas de mecanismos de código aberto:

Propriedade Valor padrão Detalhes
write.parquet.compression-codec zstd A otimização de gravações e armazenamento do BigQuery é compatível apenas com os formatos de compactação zstd e snappy. Outros formatos de compactação (como gzip, brotli e lz4) não são compatíveis.
write.metadata.compression-codec null Pode ser configurado como null ou gzip.
history.expire.max-snapshot-age-ms 432000000 (5 dias) Pode ser configurado para qualquer número inteiro positivo, mas é recomendável até 7 dias (604800000 ms) quando o gerenciamento de tabelas está ativado. Os jobs de gerenciamento de tabelas excluem snapshots com mais tempo do que a duração especificada.
history.expire.min-snapshots-to-keep 1 Pode ser configurado como qualquer número inteiro positivo. Os jobs de gerenciamento de tabelas retêm pelo menos esse número de snapshots.

Outras propriedades de gravação do Apache Iceberg, como write.target-file-size-bytes e write.parquet.page-size-bytes, podem ser configuradas em mecanismos de código aberto, mas os jobs de gravação e gerenciamento de tabelas do BigQuery podem não obedecer a elas.

A seguir