Criar tabelas externas do Apache Iceberg

As tabelas externas do Apache Iceberg permitem acessar tabelas do Apache Iceberg em um formato somente leitura com controle de acesso mais refinado, incluindo segurança no nível da linha e da coluna e mascaramento de dados. Essas tabelas não são mais recomendadas para a maioria dos casos de uso. Em vez disso, consulte Alternativas recomendadas.

Dependendo de onde seus dados estão armazenados, recomendamos as seguintes alternativas para acessar tabelas do Iceberg com metadados que não são gerenciados pelo Google Cloud:

  • Dados do Cloud Storage ou do Amazon Simple Storage Service (Amazon S3) gerenciados por catálogos remotos, como AWS Glue, Databricks Unity Catalog e Snowflake Horizon Catalog. Use o catálogo do ambiente de execução do Lakehouse com acesso a dados entre nuvens. O recurso de acesso a dados entre nuvens do catálogo do ambiente de execução do Lakehouse permite consultar dados em outros provedores de nuvem diretamente do Google Cloud sem migrar arquivos ou criar pipelines de ETL complexos.
  • Tabelas do Armazenamento de Blobs do Azure ou do Apache Iceberg não gerenciadas por um catálogo remoto compatível com o catálogo do ambiente de execução do Lakehouse com acesso a dados entre nuvens. Continue com as tabelas externas do Apache Iceberg usando arquivos de metadados JSON do Iceberg.

Suporte a formatos e versões do Iceberg

O Iceberg é um formato de tabela de código aberto compatível com tabelas de dados de escala de petabytes. A especificação aberta do Iceberg permite executar vários mecanismos de consulta em uma única cópia dos dados armazenados em um repositório de objetos. As tabelas externas do Iceberg são compatíveis com a versão 2 do Iceberg, incluindo a mesclagem na leitura. O suporte para a versão 3 do Iceberg, incluindo vetores de exclusão binária, está em pré-lançamento. Para enviar feedback ou fazer perguntas relacionadas a esse recurso em fase de pré-lançamento, entre em contato com biglake-help@google.com.

Antes de começar

Ative as APIs BigQuery Connection e BigQuery Reservation, se ainda não estiverem ativadas.

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 as APIs

Funções exigidas

Para receber as permissões necessárias para criar uma tabela externa do Iceberg, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

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 criar uma tabela externa do Iceberg. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para criar uma tabela externa do Iceberg:

  • bigquery.tables.create
  • bigquery.connections.delegate
  • bigquery.jobs.create

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

Criar tabelas com um arquivo de metadados

É possível criar tabelas externas do Iceberg com um arquivo de metadados JSON. No entanto, é necessário atualizar manualmente o URI do arquivo de metadados JSON para manter a tabela externa do Iceberg atualizada. Se o URI não for atualizado, as consultas no BigQuery poderão falhar ou fornecer resultados diferentes de outros mecanismos de consulta que usam diretamente um catálogo do Iceberg.

Os arquivos de metadados da tabela do Iceberg são criados no bucket do Cloud Storage que você especificou ao criar uma tabela do Iceberg usando o Spark.

Selecione uma das seguintes opções:

SQL

Use a instrução CREATE EXTERNAL TABLE. O exemplo a seguir cria uma tabela externa do Iceberg chamada myexternal-table:

  CREATE EXTERNAL TABLE myexternal-table
  WITH CONNECTION `myproject.us.myconnection`
  OPTIONS (
         format = 'ICEBERG',
         uris = ["gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json"]
   )

Substitua o valor uris pelo arquivo de metadados JSON mais recente para um snapshot de tabela específico.

É possível ativar o filtro de partição definindo a sinalização require_partition_filter.

bq

Em um ambiente de linha de comando, use o comando bq mk --table com o decorador @connection para especificar a conexão a ser usada no final do parâmetro --external_table_definition. Para ativar o filtro de partição exigido, use --require_partition_filter. 

bq mk 

    --table 

    --external_table_definition=TABLE_FORMAT=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID 

    PROJECT_ID:DATASET.EXTERNAL_TABLE

Substitua:

  • TABLE_FORMAT: o formato da tabela que você quer criar

    Nesse caso, ICEBERG.

  • URI: o arquivo de metadados JSON mais recente para um snapshot de tabela específica.

    Por exemplo, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json

    O URI também pode apontar para um local externo de nuvem. como Amazon S3 ou Azure Blob Storage.

    • Exemplo para a AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Exemplo do Azure: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

  • CONNECTION_PROJECT_ID: o projeto que contém a conexão para criar a tabela externa do Iceberg. Por exemplo, myproject.

  • CONNECTION_REGION: a região que contém a conexão para criar a tabela externa do Iceberg, por exemplo, us.

  • CONNECTION_ID: o ID da conexão da tabela. Por exemplo, myconnection.

    Quando você visualiza os detalhes da conexão no console do Google Cloud , esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

  • DATASET: o nome do conjunto de dados do BigQuery em que você quer criar uma tabela

    Por exemplo, mydataset

  • EXTERNAL_TABLE: o nome da tabela que você quer criar.

    Por exemplo, mytable

Atualizar metadados de tabela

Se você usar um arquivo de metadados JSON para criar uma tabela externa do Iceberg, atualize a definição da tabela para os metadados mais recentes dela. Para atualizar o esquema ou o arquivo de metadados, selecione uma das seguintes opções:

bq

  1. Crie um arquivo de definição da tabela:

    bq mkdef --source_format=ICEBERG \
"URI" > TABLE_DEFINITION_FILE

  2. Use o comando bq update com a sinalização --autodetect_schema:

    bq update --autodetect_schema --external_table_definition=TABLE_DEFINITION_FILE
PROJECT_ID:DATASET.TABLE

    Substitua:

    • URI: o URI do Cloud Storage com o arquivo de metadados JSON mais recente

      Por exemplo, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

    • TABLE_DEFINITION_FILE: o nome do arquivo que contém o esquema da tabela

    • PROJECT_ID: o ID do projeto que contém a tabela que você quer atualizar

    • DATASET: o conjunto de dados que contém a tabela que você quer atualizar

    • TABLE: a tabela que você quer atualizar

API

Use o método tables.patch com a propriedade autodetect_schema definida como true:

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/TABLE?autodetect_schema=true

Substitua:

  • PROJECT_ID: o ID do projeto que contém a tabela que você quer atualizar
  • DATASET: o conjunto de dados que contém a tabela que você quer atualizar
  • TABLE: a tabela que você quer atualizar

No corpo da solicitação, especifique os valores atualizados dos seguintes campos:

{
     "externalDataConfiguration": {
      "sourceFormat": "ICEBERG",
      "sourceUris": [
        "URI"
      ]
    },
    "schema": null
  }'

Substitua URI pelo arquivo de metadados mais recente do Iceberg. Por exemplo, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

Configurar políticas de controle de acesso

É possível controlar o acesso a tabelas externas do Iceberg por meio de segurança no nível da coluna, segurança no nível da linha e mascaramento de dados.

Como administrador do BigQuery, é possível aplicar o controle de acesso no nível da linha e da coluna, incluindo o mascaramento de dados em tabelas. As políticas de acesso à tabela também são aplicadas quando você usa a API BigQuery Storage como fonte de dados da tabela no serviço gerenciado para Apache Spark e no Spark sem servidor.

Consultar tabelas externas do Iceberg

Para mais informações, consulte Consultar dados do Iceberg.

Consultar dados históricos

É possível acessar snapshots de tabelas externas do Iceberg que são retidos nos metadados do Iceberg usando a cláusula FOR SYSTEM_TIME AS OF.

As janelas de retenção de dados de viagem no tempo e à prova de falhas não são compatíveis com tabelas externas.

Mapeamento de dados

O BigQuery converte tipos de dados do Iceberg em tipos de dados do BigQuery, conforme mostrado na tabela a seguir:

Tipo de dados do Iceberg Tipo de dados BigQuery
boolean BOOL
int INT64
long INT64
float FLOAT64
double FLOAT64
Decimal(P/S) NUMERIC or BIG_NUMERIC depending on precision
date DATE
time TIME
timestamp DATETIME
timestamptz TIMESTAMP
string STRING
uuid BYTES
fixed(L) BYTES
binary BYTES
list<Type> ARRAY<Type>
struct STRUCT
map<KeyType, ValueType> ARRAY<Struct<key KeyType, value ValueType>>

Limitações

Além das limitações de tabelas externas, as tabelas externas do Iceberg têm as seguintes limitações:

  • As consultas que usam o VPC Service Controls não são compatíveis e resultam em um erro como NO_MATCHING_ACCESS_LEVEL.

  • As tabelas que usam a mesclagem na leitura têm as seguintes limitações:

    • Uma consulta pode processar até 100.000 entradas de vetor de exclusão na tabela. Para tabelas do Iceberg versão 3 que usam vetores de exclusão binários, cada arquivo de dados associado a um vetor de exclusão conta como uma entrada de exclusão para esse limite.
    • Cada arquivo de dados pode ser associado a até 10.000 arquivos de exclusão.
    • Não é possível aplicar mais de 100.000 exclusões de igualdade a um arquivo de dados.
    • Para contornar essas limitações, compacte os arquivos e vetores de exclusão com frequência, crie uma visualização sobre a tabela do Iceberg que evite partições modificadas com frequência ou filtre consultas em colunas particionadas para reduzir o número de arquivos de dados e vetores de exclusão verificados.

  • O BigQuery é compatível com a remoção de manifesto usando todas as funções de transformação de partição do Iceberg. Para saber mais sobre como remover partições, consulte Consultar tabelas particionadas. As consultas que fazem referência a tabelas externas do Iceberg precisam conter literais em predicados em comparação com colunas particionadas.

  • Somente arquivos de dados do Apache Parquet são compatíveis.

  • Nomes de colunas flexíveis:

    • Se uma tabela externa do Iceberg for particionada em uma coluna que contém caracteres não alfanuméricos, talvez o BigQuery não consiga extrair metadados de partição do manifesto, o que pode resultar em uma verificação completa da tabela.
    • As tabelas do Iceberg que contêm caracteres estruturais (como pontos ., cifrões $, colchetes [], parênteses () ou barras /) não podem ser consultadas diretamente pelo BigQuery. Se o fluxo de trabalho exigir o registro dessas tabelas no catálogo do ambiente de execução do Lakehouse ou em serviços de catálogo para uso exclusivo com mecanismos externos (como Spark ou Trino), entre em contato com o Cloud Customer Care para solicitar a ativação para envolvidos no projeto.

  • Os seguintes recursos do Iceberg versão 3 não são compatíveis:

    • Novos tipos de dados: carimbo de data/hora de nanossegundo(tz), desconhecido, variante, geometria, geografia
    • Valores padrão iniciais
    • Chaves de criptografia de tabela

Custos de mesclagem na leitura

O faturamento sob demanda para dados de mesclagem na leitura é a soma das verificações dos seguintes dados:

  • Todos os bytes lógicos lidos no arquivo de dados (incluindo linhas marcadas como excluídas por posição e exclusões de igualdade).
  • Bytes lógicos lidos ao carregar os arquivos de vetor de exclusão, exclusão de posição e exclusão de igualdade para encontrar as linhas excluídas em um arquivo de dados.

Exigir filtro de particionamento

É possível exigir o uso de filtros de predicado ativando a opção Exigir filtro de partição para sua tabela do Iceberg. Se você ativar essa opção, as tentativas de consultar a tabela sem especificar uma cláusula WHERE que se alinha a cada arquivo de manifesto produzirão o seguinte erro:

Cannot query over table project_id.dataset.table without a
filter that can be used for partition elimination.

Cada arquivo de manifesto requer pelo menos um predicado adequado para a eliminação de partições.

É possível ativar o require_partition_filter das seguintes maneiras ao criar uma tabela Iceberg :

SQL

Use a instrução CREATE EXTERNAL TABLE.O exemplo a seguir cria uma tabela externa do Iceberg chamada TABLE com o filtro de partição necessário ativado:

  CREATE EXTERNAL TABLE TABLE
  WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
  OPTIONS (
         format = 'ICEBERG',
         uris = [URI],
         require_partition_filter = true
   )

Substitua:

  • TABLE: o nome da tabela que você quer criar.
  • PROJECT_ID: o ID do projeto que contém a tabela que você quer criar
  • REGION: o local em que você quer criar a tabela Iceberg.

  • CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.

  • URI: o URI do Cloud Storage com o arquivo de metadados JSON mais recente

    Por exemplo, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json

    O URI também pode apontar para um local externo de nuvem. como Amazon S3 ou Azure Blob Storage.

    • Exemplo para a AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Exemplo do Azure: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

bq

Use o comando bq mk --table com o decorador @connection para especificar a conexão a ser usada no final do parâmetro --external_table_definition. Use --require_partition_filter para ativar o filtro de partição exigido. No exemplo a seguir, criamos uma tabela externa do Iceberg chamada TABLE com o recurso "Exigir filtro de partição" ativado: 

bq mk \
    --table \
    --external_table_definition=ICEBERG=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID \
    PROJECT_ID:DATASET.EXTERNAL_TABLE \
    --require_partition_filter

Substitua:

  • URI: o arquivo de metadados JSON mais recente para um snapshot de tabela específica

    Por exemplo, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json

    O URI também pode apontar para um local externo de nuvem. como Amazon S3 ou Azure Blob Storage.

    • Exemplo para a AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Exemplo do Azure: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

  • CONNECTION_PROJECT_ID: o projeto que contém a conexão para criar a tabela externa do Iceberg. Por exemplo, myproject.

  • CONNECTION_REGION: a região que contém a conexão para criar a tabela externa do Iceberg. Por exemplo, us.

  • CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.

    Quando você visualiza os detalhes da conexão no console do Google Cloud , esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

  • DATASET: o nome do BigQuery

    conjunto de dados que contém a tabela que você quer atualizar. Por exemplo, mydataset

  • EXTERNAL_TABLE: o nome da tabela que você quer criar

    Por exemplo, mytable

Você também pode atualizar sua tabela do Iceberg para ativar o filtro de partição necessário.

Se você não ativar a opção Exigir filtro de partição ao criar a tabela particionada, será possível atualizá-la para adicionar a opção.

bq

Use o comando bq update e forneça a sinalização --require_partition_filter.

Exemplo:

Para atualizar mypartitionedtable em mydataset no seu projeto padrão, insira:

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

A seguir