Configurar opções de tabela

Ao configurar as opções de tabela, você pode 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 execução do Lakehouse. Essas opções servem como configurações básicas que estendem os recursos para operações na tabela.

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

Ao usar tabelas no catálogo de execução do Lakehouse, é útil entender os diferentes tipos de tabelas e os recursos de ativação de capacidade. 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 Google Cloud projeto.

  2. Ative a API BigLake.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel Proprietário (roles/owner). Caso contrário, você pode receber essa permissão com o papel Administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

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

Funções exigidas

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

  • Configurar propriedades de tabela no modo de fornecimento de credenciais: Editor do BigLake (roles/biglake.editor) – o projeto
  • Configurar propriedades de tabela no modo de fornecimento de não 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 com 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 com suporte

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

Requisito de fornecimento de credenciais

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

Ativar o BigQuery DML

A ativação das instruções da linguagem de manipulação de dados (DML) do BigQuery desbloqueia a interoperabilidade de gravação do BigQuery em tabelas do Apache Iceberg criadas usando mecanismos de código aberto.

As instruções com suporte incluem INSERT, UPDATE, DELETE e MERGE, bem como 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 o BigQuery DML para novas tabelas

Quando você cria uma tabela no BigQuery, o BigQuery DML e o gerenciamento automático de tabelas são ativados por padrão. Ao criar uma tabela em 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 o BigQuery DML para tabelas atuais

Para ativar o BigQuery DML 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 o BigQuery DML

A desativação do BigQuery DML 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.

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

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

    • Limitação: a expiração de snapshots 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. Saiba mais em Limitações.

  • Mesclar (compactação) : a mesclagem é responsável por manter o formato dos dados, mesclando arquivos pequenos em arquivos maiores. A mesclagem é 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 do arquivo de destino de 256 MB. Cada operação de mesclagem produz um novo snapshot de tabela. Os jobs de mesclagem normalmente são retomados e repetidos após qualquer operação DML em execução. No entanto, para evitar a escassez indefinida de otimização de armazenamento, um job de mesclagem é acionado à força a cada 24 horas se os dados forem qualificados para mesclagem.

  • 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 do BigQuery. É possível consultar essa visualização para acompanhar essas operações, de maneira semelhante ao monitoramento de outros jobs do BigQuery. Para mais informações sobre como consultar informações de job, 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 mais frequentes. É possível 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 mais atividade de job visível em INFORMATION_SCHEMA.

Ativar o gerenciamento de tabelas para novas tabelas

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

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

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

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 para recursos gerenciados (como a interoperabilidade de gravação do BigQuery e o gerenciamento automático de tabelas) incluem:

Limitações gerais

  • Os recursos gerenciados só são compatíveis com tabelas do Apache Iceberg criadas no catálogo de execução do Lakehouse usando o endpoint do catálogo REST do Apache Iceberg.
  • Todas as limitações atuais para 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 a versão 3 do formato do Apache Iceberg. Somente as tabelas da versão 2 do formato (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 particionamento por STRING, particionamento de várias colunas ou evolução de partição.
  • Os recursos gerenciados são indisponíveis para 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 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 oferecem suporte a arquivos de dados compactados usando 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 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 com locais de dados ou metadados personalizados (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 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 há suporte para a exclusão de uma coluna no BigQuery usando DDL (ALTER TABLE ... DROP COLUMN) seguida imediatamente pela adição de uma coluna com o mesmo nome.

Limitações com a 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 7 dias.
  • As configurações de viagem no tempo do projeto ou do conjunto de dados do BigQuery 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 de snapshots é 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, e todos os valores definidos para a history.expire.max-ref-age-ms propriedade são ignorados. Os mecanismos de código aberto ainda podem realizar a expiração de snapshots.
  • O gerenciamento automático 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 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 remove_orphan_files do Spark com a opção prefix_listing definida como true).

  • A mesclagem não oferece suporte à classificação linear e de ordem z. Se a tabela contiver essas propriedades, não será garantido que o layout seja mantido após a execução da mesclagem. Se as tabelas contiverem essas propriedades, a melhor ação será não ativar o gerenciamento de tabelas.

Limitações com o particionamento

  • Ao criar ou registrar tabelas em mecanismos de código aberto, os recursos gerenciados só oferecem suporte ao particionamento em tipos de campo DATE, DATETIME e TIMESTAMP com transformações hour, day, month e year (exceto a transformação hour em campos DATE) e tipos de campo INTEGER.
  • Os recursos gerenciados não são compatíveis com tabelas com 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 tabela não particionada.
    • Substituir uma tabela particionada por uma tabela que usa uma especificação de particionamento diferente.
  • Não há suporte para nomenclatura de campo de partição personalizada. 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 de tabela do Iceberg personalizadas

As seguintes propriedades de comportamento da tabela não podem ser configuradas para valores não padrão quando os recursos gerenciados estão ativados. 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ó oferecem suporte a tabelas do Iceberg v2.
write.format.default parquet As tabelas só oferecem suporte a 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 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ó oferecem suporte à cópia na gravação.
write.update.mode copy-on-write Os jobs de gravação e gerenciamento de tabelas do BigQuery só oferecem suporte à cópia na gravação.
write.merge.mode copy-on-write Os jobs de gravação e gerenciamento de tabelas do BigQuery só oferecem suporte à cópia na gravação.
write.delete.isolation-level Detecção de conflitos estrita 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 estrita O mesmo comportamento de write.delete.isolation-level.
write.merge.isolation-level Detecção de conflitos estrita O mesmo comportamento de write.delete.isolation-level.

As seguintes propriedades podem ser configuradas ao criar ou alterar tabelas em 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ó oferecem suporte aos 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 é recomendado até 7 dias (604800000 ms) quando o gerenciamento de tabelas está ativado. Os jobs de gerenciamento de tabelas excluem snapshots mais antigos do que a duração especificada.
history.expire.min-snapshots-to-keep 1 Pode ser configurado para 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 as gravações do BigQuery e os jobs de gerenciamento de tabelas podem não estar em conformidade com elas.

A seguir