Crie tabelas externas do Apache Iceberg

As tabelas externas do Apache Iceberg permitem-lhe aceder a tabelas do Apache Iceberg com um controlo de acesso mais detalhado num formato só de leitura. Esta capacidade contrasta com as tabelas do BigLake para o Apache Iceberg no BigQuery, que lhe permitem criar tabelas Iceberg no BigQuery num formato gravável.

O Iceberg é um formato de tabela de código aberto que suporta tabelas de dados à escala de petabytes. A especificação aberta do Iceberg permite-lhe executar vários motores de consulta numa única cópia de dados armazenados num arquivo de objetos. As tabelas externas do Apache Iceberg (doravante denominadas tabelas externas do Iceberg) suportam a versão 2 da especificação do Iceberg, incluindo a funcionalidade de união na leitura.

Enquanto administrador do BigQuery, pode aplicar o controlo de acesso ao nível da linha e da coluna, incluindo a ocultação de dados em tabelas. Para obter informações sobre como configurar o controlo de acesso ao nível da tabela, consulte o artigo Configure políticas de controlo de acesso. As políticas de acesso às tabelas também são aplicadas quando usa a API BigQuery Storage como origem de dados para a tabela no Dataproc e Serverless Spark.

Pode criar tabelas externas Iceberg das seguintes formas:

• Com o metastore do BigLake (recomendado para Google Cloud). O metastore do BigLake baseia-se no catálogo do BigQuery e integra-se diretamente com o BigQuery. As tabelas no metastore do BigLake são mutáveis a partir de vários motores de código aberto e as mesmas tabelas podem ser consultadas a partir do BigQuery. O metastore do BigLake também suporta a integração direta com o Apache Spark. As tabelas externas do Iceberg que usam o metastore do BigLake são, por vezes, denominadas tabelas do Iceberg do BigLake.

• Com o AWS Glue Data Catalog (recomendado para a AWS). O AWS Glue é o método recomendado para a AWS porque é um repositório de metadados centralizado onde define a estrutura e a localização dos seus dados armazenados em vários serviços da AWS e oferece capacidades como a deteção automática de esquemas e a integração com ferramentas de estatísticas da AWS.

• Com ficheiros de metadados JSON do Iceberg (recomendado para o Azure). Se usar um ficheiro de metadados JSON do Iceberg, tem de atualizar manualmente o ficheiro de metadados mais recente sempre que houver atualizações da tabela. Pode usar um procedimento armazenado do BigQuery para o Apache Spark para criar tabelas externas do Iceberg que referenciam um ficheiro de metadados do Iceberg.

Para ver uma lista completa de limitações, consulte a secção Limitações.

Antes de começar

Enable the BigQuery Connection and BigQuery Reservation APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

• Se usar um procedimento armazenado para o Spark no BigQuery para criar tabelas externas do Iceberg, tem de seguir estes passos:

  1. Crie uma associação do Spark.
  2. Configurar o controlo de acesso para essa ligação.

• Para armazenar os metadados da tabela externa Iceberg e os ficheiros de dados no Cloud Storage, crie um contentor do Cloud Storage. Tem de se ligar ao seu contentor do Cloud Storage para aceder aos ficheiros de metadados. Para o fazer, siga estes passos:

  1. Crie uma associação de recursos da nuvem.
  2. Configurar o acesso para essa ligação.

Funções necessárias

Para receber as autorizações de que precisa para criar uma tabela externa do Iceberg, peça ao seu administrador que lhe conceda as seguintes funções de IAM no projeto:

• Administrador do BigQuery (roles/bigquery.admin)
• Administrador de objetos de armazenamento (roles/storage.objectAdmin)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Estas funções predefinidas contêm as autorizações necessárias para criar uma tabela externa do Iceberg. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para criar uma tabela externa do Iceberg:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Crie tabelas com o metastore do BigLake

Recomendamos que crie tabelas externas do Iceberg com o metastore do BigLake. Pode usar o Apache Spark para criar estas tabelas. Uma forma conveniente de o fazer é usar procedimentos armazenados do BigQuery. Para ver um exemplo, consulte o artigo Crie e execute um procedimento armazenado.

Crie tabelas com um ficheiro de metadados

Pode criar tabelas externas do Iceberg com um ficheiro de metadados JSON. No entanto, este não é o método recomendado porque tem de atualizar manualmente o URI do ficheiro de metadados JSON para manter a tabela externa do Iceberg atualizada. Se o URI não for mantido atualizado, as consultas no BigQuery podem falhar ou fornecer resultados diferentes de outros motores de consulta que usam diretamente um catálogo do Iceberg.

Os ficheiros de metadados de tabelas Iceberg são criados no contentor do Cloud Storage que especifica quando cria uma tabela Iceberg com o Spark.

Selecione uma das seguintes opções:

SQL

Use a declaração CREATE EXTERNAL TABLE. O exemplo seguinte cria uma tabela externa do Iceberg denominada 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 ficheiro de metadados JSON mais recente de uma captura instantânea de tabela específica.

Pode ativar a opção Exigir filtro de partição definindo a flag require_partition_filter.

bq

Num ambiente de linha de comandos, use o comando bq mk --table com o decorador @connection para especificar a ligação a usar no final do parâmetro --external_table_definition. Para ativar o filtro de partição obrigatório, 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 o seguinte:

• TABLE_FORMAT: o formato da tabela que quer criar

  Neste caso, ICEBERG.

• URI: o ficheiro de metadados JSON mais recente para uma captura de ecrã específica de uma tabela.

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

  O URI também pode apontar para uma localização na nuvem externa, como o Amazon S3 ou o Azure Blob Storage.

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

• CONNECTION_PROJECT_ID: o projeto que contém a ligação para criar a tabela externa Iceberg, por exemplo, myproject

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

• CONNECTION_ID: o ID da associação de tabelas, por exemplo, myconnection

  Quando vê os detalhes da associação na Google Cloud consola, o ID da associação é o valor na última secção do ID da associação totalmente qualificado apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection

• DATASET: o nome do conjunto de dados do BigQuery no qual quer criar uma tabela

  Por exemplo, mydataset.

• EXTERNAL_TABLE: o nome da tabela que quer criar

  Por exemplo, mytable.

Atualize os metadados da tabela

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

bq

1. Crie um ficheiro de definição de tabela:

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

2. Use o comando bq update com a flag --autodetect_schema:

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

   Substitua o seguinte:

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

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

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

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

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

   • TABLE: a tabela que 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 o seguinte:

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

No corpo do pedido, especifique os valores atualizados para os seguintes campos:

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

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

Configure políticas de controlo de acesso

Pode controlar o acesso a tabelas externas do Iceberg através da segurança ao nível da coluna, segurança ao nível da linha> e da ocultação de dados.

Consultar tabelas externas do Iceberg

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

Consultar dados do histórico

Pode aceder a instantâneos de tabelas externas do Iceberg que são retidas nos metadados do Iceberg através da cláusula FOR SYSTEM_TIME AS OF.

A viagem no tempo e os períodos de retenção de dados à prova de falhas não são suportados para tabelas externas.

Mapeamento de dados

O BigQuery converte os tipos de dados do Iceberg em tipos de dados do BigQuery, conforme mostrado na tabela seguinte:

Tipo de dados Iceberg	Tipo de dados do 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

As tabelas externas do Iceberg têm limitações de tabelas externas e as seguintes limitações:

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

  • Cada ficheiro de dados pode ser associado a um máximo de 10 000 ficheiros de eliminação.
  • Não é possível aplicar mais de 100 000 IDs de igualdade a um ficheiro de eliminação.
  • Pode contornar estas limitações compactando os ficheiros de eliminação com frequência ou criando uma vista na parte superior da tabela Iceberg que evite partições mutadas com frequência.

• O BigQuery suporta a eliminação de manifestos através de todas as funções de transformação de partições do Iceberg, exceto Bucket. Para obter informações sobre como remover partições, consulte o artigo Consulte tabelas particionadas. As consultas que fazem referência a tabelas externas do Iceberg têm de conter literais em predicados comparados com colunas particionadas.

• Apenas são suportados ficheiros de dados Apache Parquet.

Custos de união na leitura

A faturação a pedido dos dados de união na leitura é a soma das análises dos seguintes dados:

• Todos os bytes lógicos lidos no ficheiro de dados (incluindo linhas marcadas como eliminadas por posição e eliminações por igualdade).
• Bytes lógicos lidos ao carregar os ficheiros de eliminação por igualdade e eliminação por posição para encontrar as linhas eliminadas num ficheiro de dados.

Exigir filtro de partição

Pode exigir a utilização de filtros de predicados ativando a opção require partition filter para a sua tabela Iceberg. Se ativar esta opção, as tentativas de consultar a tabela sem especificar uma cláusula WHERE que se alinhe com cada ficheiro de manifesto vão produzir o seguinte erro:

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

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

Pode ativar o require_partition_filter das seguintes formas ao criar uma tabela Iceberg :

SQL

Use a declaração CREATE EXTERNAL TABLE.O exemplo seguinte cria uma tabela externa do Iceberg denominada TABLE com o filtro de partição obrigatório ativado:

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

Substitua o seguinte:

• TABLE: o nome da tabela que quer criar.
• PROJECT_ID: o ID do projeto que contém a tabela que quer criar.
• REGION: a localização onde quer criar a tabela Iceberg.

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

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

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

  O URI também pode apontar para uma localização na nuvem externa, como o Amazon S3 ou o Azure Blob Storage.

  • Exemplo para a AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
  • Exemplo para o 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 ligação a usar no final do parâmetro --external_table_definition. Use --require_partition_filter para ativar o filtro de partição obrigatório. O exemplo seguinte cria uma tabela externa do Iceberg denominada TABLE com o filtro de partição obrigatório 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 o seguinte:

• URI: o ficheiro de metadados JSON mais recente para um instantâneo de tabela específico

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

  O URI também pode apontar para uma localização na nuvem externa, como o Amazon S3 ou o Azure Blob Storage.

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

• CONNECTION_PROJECT_ID: o projeto que contém a associação para criar a tabela externa do Iceberg, por exemplo, myproject

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

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

  Quando vê os detalhes da associação na Google Cloud consola, o ID da associação é o valor na última secção do ID da associação totalmente qualificado apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection

• DATASET: o nome do

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

• EXTERNAL_TABLE: o nome da tabela que quer criar

  Por exemplo, mytable.

Também pode atualizar a tabela Iceberg para ativar o filtro de partição obrigatório.

Se não ativar a opção Exigir filtro de partição quando cria a tabela particionada, pode atualizar a tabela para adicionar a opção.

bq

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

Por exemplo:

Para atualizar mypartitionedtable em mydataset no seu projeto predefinido, introduza:

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

O que se segue?

• Saiba mais sobre o procedimento armazenado para o Spark.
• Saiba mais sobre as políticas de controlo de acesso.
• Saiba como executar consultas no BigQuery.
• Saiba mais sobre as declarações e os dialetos de SQL suportados no BigQuery.