Configurar opções de tabela

É possível usar as opções de tabela no catálogo do ambiente de execução do Lakehouse para ativar a interoperabilidade de gravação de DML do BigQuery e o gerenciamento de tabelas (otimização automática de armazenamento) para suas tabelas do Apache Iceberg.

Para saber mais sobre os formatos de tabela compatíveis e os recursos de ativação no catálogo do ambiente de execução do Lakehouse, consulte Comparar tipos de tabela e 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, se ainda não tiver feito isso.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

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

Funções exigidas

Para receber as permissões necessárias para configurar as 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 de fornecimento sem 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 as opções de tabela:

Tabelas do Iceberg compatíveis

Embora o catálogo do ambiente de execução do Lakehouse seja compatível com tabelas do Apache Iceberg V2 (GA) e V3 (pré-lançamento), os recursos gerenciados (DML do BigQuery e gerenciamento de tabelas) são compatíveis apenas com tabelas do Iceberg V2. As tabelas do Iceberg V1 não são compatíveis. Para fazer upgrade das tabelas V1, consulte Fazer upgrade das tabelas do Iceberg V1 para V2.

Requisito de fornecimento de credenciais

Para ativar o gerenciamento de tabelas, o catálogo do 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 de serviço de venda de credenciais para autenticar e atualizar os arquivos de dados de armazenamento subjacentes.

Ativar a DML do BigQuery

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

As instruções compatíveis 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 compatíveis com 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 de tabelas são ativados por padrão. Ao criar uma tabela de mecanismos de código aberto, configure a propriedade de tabela gcp.biglake.bigquery-dml.enabled = true usando a sintaxe DDL do 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, 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 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.

O gerenciamento de tabelas permite realizar as seguintes operações:

  • Expiração de snapshot e coleta de lixo: a expiração de snapshot gerencia a retenção e a exclusão de arquivos de dados e metadados de snapshots de tabela. 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 na tabela. Ele remove entradas de snapshot expiradas criando uma definição de snapshot adicional em um novo arquivo de metadados que omite referências aos snapshots removidos.

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

    • Limitação: a remoção de arquivos órfãos não é processada pelo gerenciamento de tabelas. Saiba mais em Limitações.

  • Coalesce (compactação): o Coalesce é 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 serão selecionados para compactação se o tamanho médio descompactado for inferior a 50% do tamanho do arquivo de destino de 256 MB. Cada operação de união produz um novo snapshot de tabela. Os jobs de união normalmente são interrompidos e repetidos após qualquer operação de 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.

  • Monitoramento de jobs de gerenciamento de tabelas: todos os jobs de gerenciamento de tabelas em segundo plano são registrados na visualização INFORMATION_SCHEMA.JOBS no BigQuery. É possível consultar essa visualização para rastrear essas operações, de maneira semelhante a 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. Pode haver períodos sem jobs em segundo plano se não houver gravações na tabela. Por outro lado, altos volumes de gravação podem resultar em uma atividade de job mais visível em INFORMATION_SCHEMA.

Escolher se você quer ativar o gerenciamento de tabelas

Para tabelas do Apache Iceberg gerenciadas pelo catálogo do ambiente de execução do Lakehouse e disponibilizadas pelo endpoint do catálogo REST do Apache Iceberg, é possível ativar o gerenciamento de tabelas ou gerenciar a manutenção de tabelas (como compactação e expiração de snapshots) por conta própria usando mecanismos de código aberto ou de terceiros.

Ative o gerenciamento de tabelas (gcp.biglake.table-management.enabled = true) quando todas as condições a seguir forem atendidas:

  • Você quer compactação automática de arquivos em segundo plano (coalesce), expiração automática de snapshots e coleta de lixo após gravações de streaming de DML ou de código aberto.

  • Seu catálogo usa o modo de venda de credenciais.

  • Uma janela de retenção de snapshots e de viagem no tempo de até sete dias (cinco dias por padrão) atende aos seus requisitos.

  • Sua tabela atende aos requisitos de recursos gerenciados (consulte Limitações).

Mantenha o gerenciamento de tabelas desativado (o padrão para tabelas criadas com base em mecanismos de código aberto ou defina gcp.biglake.table-management.enabled = false) e gerencie a manutenção de tabelas por conta própria quando qualquer uma das seguintes condições se aplicar:

  • Você executa procedimentos personalizados de compactação ou manutenção em mecanismos de código aberto, como Apache Spark, Apache Flink ou Trino, especialmente se as tabelas dependem de layouts de ordenação em Z ou classificação linear que a coalescência não preserva.

  • Suas tabelas usam tags ou ramificações de snapshot do Apache Iceberg (que fazem com que o gerenciamento de tabelas pule a expiração do snapshot) ou exigem retenção de snapshot e viagem no tempo por mais de 7 dias.

  • Seu catálogo usa credenciais de usuário final (permissões diretas do Identity and Access Management (IAM) do Cloud Storage) em vez do modo de venda de credenciais.

  • As tabelas usam recursos que não são compatíveis com os recursos gerenciados (nesse caso, o gerenciamento de tabelas e a DML do BigQuery precisam permanecer desativados), como o Apache Iceberg versão 3, o modo de mesclagem na leitura, o particionamento de várias colunas ou IDENTITY ou caminhos personalizados de armazenamento de dados e metadados. Para ver uma lista completa de recursos sem suporte, consulte Limitações.

Ativar o gerenciamento de tabelas para novas tabelas

Quando você cria uma tabela no BigQuery, a DML e o gerenciamento de tabelas são ativados por padrão. Ao criar uma tabela de mecanismos de código aberto, configure a propriedade gcp.biglake.table-management.enabled. A ativação do gerenciamento de tabelas ativa automaticamente a DML do BigQuery, se ainda não estiver ativada.

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, atualize a propriedade da tabela.

Spark SQL 

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

BigQuery 

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

Desativar o gerenciamento de tabelas

A desativação do gerenciamento de tabelas impede que futuros jobs de otimização em segundo plano sejam enfileirados, embora os jobs ativos em andamento sejam concluídos. A desativação do 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 de tabelas) incluem:

Limitações gerais

  • Os recursos gerenciados só são compatíveis 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 a operações com recursos gerenciados ativados.
  • Os recursos gerenciados não são compatíveis com tabelas com o Apache Iceberg format-version 3. Somente as tabelas de versão de formato 2 (especificação 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 particionamento por STRING, particionamento de várias colunas ou evolução de partição.
  • Os recursos gerenciados 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 Iceberg v2 que usam o modo de mesclagem na leitura. Somente as 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 os codecs gzip, lz4 ou brotli (write.parquet.compression-codec). Somente 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 contém identificadores de chave primária aninhados (identifier-field-ids) que fazem referência a 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 dados e arquivos de metadados.
  • O clustering do BigQuery não é compatível com tabelas do Apache Iceberg gerenciadas pelo catálogo do ambiente de execução do Lakehouse.
  • Se uma tabela for criada com o tipo de dados NUMERIC no BigQuery, 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 remover uma coluna no BigQuery usando DDL (ALTER TABLE ... DROP COLUMN) e, em seguida, adicionar novamente uma coluna com o mesmo nome.

Limitações com a viagem no tempo

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

Limitações com o gerenciamento de tabelas

  • A expiração do snapshot é ignorada para toda a tabela se ela tiver snapshots com tags ou ramificações. A retenção personalizada definida usando ALTER... RETAIN x DAYS é ignorada, e todos os valores definidos para a propriedade history.expire.max-ref-age-ms são ignorados. Os mecanismos de código aberto ainda podem realizar a expiração de snapshots.
  • O gerenciamento de tabelas não expira esquemas ou 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 de tabelas. Os mecanismos de código aberto podem realizar a limpeza de arquivos órfãos (por exemplo, usando o procedimento remove_orphan_files do Spark com a opção prefix_listing definida como true).

  • O Coalesce não é compatível com a ordenação em Z e a classificação linear. Se a tabela contiver essas propriedades, não há garantia de que o layout será mantido após a execução do coalesce. Se as tabelas tiverem essas propriedades, não ative o gerenciamento de tabelas.

Limitações com particionamento

  • Ao criar ou registrar tabelas de mecanismos de código aberto, os recursos gerenciados só oferecem suporte ao particionamento nos tipos de campo DATE, DATETIME e TIMESTAMP com transformações hour, day, month e year (exceto para a transformação hour em campos DATE) e tipos de campo INTEGER.
  • Os recursos gerenciados não são compatíveis com tabelas que têm transformações IDENTITY. É preciso 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 seguintes substituições 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 nomear campos de partição personalizados. As tabelas criadas ou registradas em mecanismos de código aberto precisam seguir a convenção de nomenclatura de campo de partição padrão do mecanismo (anexando _ 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 de tabelas do Iceberg

As seguintes propriedades de comportamento de tabela não podem ser configuradas com valores não padrão quando os recursos gerenciados estão ativados. Os valores padrão são codificados quando qualquer recurso gerenciado é ativado:

Propriedade Valor padrão Detalhes
format-version 2 Os recursos gerenciados só são compatíveis com tabelas do Iceberg v2.
write.format.default parquet As tabelas só aceitam arquivos de dados no formato Parquet.
write.data.path table location + /data O caminho padrão do bucket do Cloud Storage configurado para o endpoint do catálogo REST do Apache Iceberg é usado para gravar arquivos de dados.
write.metadata.path table location + /metadata O caminho padrão do bucket do Cloud Storage configurado para o endpoint do catálogo REST do Apache Iceberg é usado para gravar arquivos de metadados.
write.delete.mode copy-on-write As gravações do BigQuery e os jobs de gerenciamento de tabelas só aceitam cópia na gravação.
write.update.mode copy-on-write As gravações do BigQuery e os jobs de gerenciamento de tabelas só aceitam cópia na gravação.
write.merge.mode copy-on-write As gravações do BigQuery e os jobs de gerenciamento de tabelas só aceitam cópia na gravação.
write.delete.isolation-level Detecção de conflitos rigorosa As mudanças que modificam o arquivo metadata.json (incluindo conflitos de dados, conflitos de metadados, leituras fantasmas ou gravações simultâneas não conflitantes) fazem com que a transação simultânea falhe e seja repetida.
write.update.isolation-level Detecção de conflitos rigorosa Mesmo comportamento de write.delete.isolation-level.
write.merge.isolation-level Detecção de conflitos rigorosa Mesmo comportamento de 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 As gravações e a otimização de armazenamento do BigQuery só são compatíveis 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 como qualquer número inteiro não negativo até 2592000000 (30 dias) quando o gerenciamento de tabelas está ativado, com até 7 dias (604800000 ms) recomendados. Os jobs de gerenciamento de tabelas excluem snapshots mais antigos que a duração especificada.
history.expire.min-snapshots-to-keep 1 Pode ser configurado como qualquer número inteiro positivo até 100 quando o gerenciamento de tabelas está ativado. 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 as gravações do BigQuery e os jobs de gerenciamento de tabelas podem não estar em conformidade com elas.

A seguir