Esta página foi traduzida pela API Cloud Translation.

Criar tabelas externas do BigLake para o Delta Lake

Com o BigLake, é possível acessar as tabelas do Delta Lake com controle de acesso mais granular. Delta Lake é um formato de armazenamento de dados tabulares de código aberto desenvolvido pelo Databricks que oferece suporte a tabelas de dados em escala de petabytes.

O BigQuery oferece suporte aos seguintes recursos com as tabelas Delta Lake:

Delegação de acesso: consulte dados estruturados em repositórios de dados externos com delegação de acesso. A delegação de acesso separa o acesso à tabela Delta Lake do acesso ao armazenamento de dados subjacente.
Controle de acesso granular: aplique uma segurança refinada no nível da tabela, incluindo segurança de nível de linha e nível de coluna. Para tabelas Delta Lake baseadas no Cloud Storage, também é possível usar máscara de dados dinâmica.
Evolução do esquema: as alterações de esquema nas tabelas de Delta Lake são detectadas automaticamente. As alterações no esquema são refletidas na tabela do BigQuery.

As tabelas do Delta Lake também são compatíveis com todos os recursos do BigLake quando você os configura como tabelas do BigLake.

Antes de começar

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Make sure that billing is enabled for your Google Cloud project.
Enable the BigQuery Connection and BigQuery Reservation APIs.
Enable the APIs
In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell
Verifique se você tem um conjunto de dados do BigQuery.
Verifique se a versão do SDK Google Cloud é a 366.0.0 ou mais recente:
```
gcloud version
```
Se necessário, atualize o SDK Google Cloud.
Crie uma conexão de recursos do Cloud com base na sua fonte de dados externa e conceda a ela acesso ao Cloud Storage. Se você não tiver as permissões apropriadas para criar uma conexão, peça ao administrador do BigQuery para criar uma conexão e compartilhá-la com você.

Funções exigidas

As seguintes permissões são necessárias para criar uma tabela Delta Lake:

bigquery.tables.create
bigquery.connections.delegate

O papel predefinido do Identity and Access Management do BigQuery Admin (roles/bigquery.admin) inclui essas permissões.

Se você não for o principal nesse papel, peça ao administrador que conceda essas permissões ou crie a tabela Delta Lake para você.

Além disso, para permitir que os usuários do BigQuery consultem a tabela, a conta de serviço associada à conexão precisa ter as seguintes permissões e acesso:

Papel de leitor do BigQuery (roles/bigquery.viewer)
Papel de usuário de conexão do BigQuery (roles/bigquery.connectionUser)
Acesso ao bucket do Cloud Storage que contém os dados

Para mais informações sobre os papéis e as permissões do Identity and Access Management no BigQuery, consulte Papéis e permissões predefinidos.

Criar tabelas com o Delta Lake

Para criar tabelas de Delta Lake, siga estas etapas.

SQL

Use a instrução CREATE EXTERNAL TABLE para criar a tabela do Delta Lake:

CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.DELTALAKE_TABLE_NAME`
WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (
  format ="DELTA_LAKE",
  uris=['DELTA_TABLE_GCS_BASE_PATH']);

Substitua os seguintes valores:

PROJECT_ID: o ID do projeto em que você quer criar a tabela do Delta Lake
DATASET: o conjunto de dados do BigQuery para conter a tabela do Delta Lake
DELTALAKE_TABLE_NAME: o nome da sua tabela do Delta Lake
REGION: a região que contém a conexão para criar a tabela do Delta Lake, 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, o ID da conexão é o valor na última seção do ID totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.
DELTA_TABLE_GCS_BASE_PATH: o prefixo da tabela do Delta Lake.

bq

Em um ambiente de linha de comando, use o comando bq mk para criar a tabela do Delta Lake:

bq mk --table --external_table_definition=DEFINITION_FILE PROJECT_ID:DATASET.DELTALAKE_TABLE_NAME

Substitua os seguintes valores:

DEFINITION_FILE: o caminho para um arquivo de definição da tabela
PROJECT_ID: o ID do projeto em que você quer criar a tabela do Delta Lake
DATASET: o conjunto de dados do BigQuery para conter a tabela do Delta Lake
DELTALAKE_TABLE_NAME: o nome da sua tabela do Delta Lake

REST

Use a API BigQuery para criar uma tabela do Delta Lake chamando o método da API tables.insert:

REQUEST='{
  "autodetect": true,
  "externalDataConfiguration": {
  "sourceFormat": "DELTA_LAKE",
  "connectionId": "PROJECT_ID.REGION.CONNECTION_ID",
  "sourceUris": [
    "DELTA_TABLE_GCS_BASE_PATH"
  ],
 },
"tableReference": {
"tableId": "DELTALAKE_TABLE_NAME"
}
}'

echo $REQUEST | curl -X POST -d @- -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables?autodetect_schema=true

Substitua os seguintes valores:

PROJECT_ID: o ID do projeto em que você quer criar a tabela do Delta Lake
REGION: a região que contém a conexão para criar a tabela do Delta Lake, 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, o ID da conexão é o valor na última seção do ID totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.
DELTA_TABLE_GCS_BASE_PATH: o prefixo da tabela do Delta Lake.
DELTALAKE_TABLE_NAME: o nome da sua tabela do Delta Lake
DATASET: o conjunto de dados do BigQuery para conter a tabela do Delta Lake

Quando você cria tabelas do Delta Lake, o prefixo Delta Lake é usado como o URI da tabela. Por exemplo, para uma tabela que tem registros no bucket gs://bucket/warehouse/basictable/_delta_log, o URI da tabela é gs://bucket/warehouse/basictable. Quando você executa consultas na tabela do Delta Lake, o BigQuery lê dados sob o prefixo para identificar a versão atual da tabela e, em seguida, calcula os metadados e os arquivos da tabela.

Embora seja possível criar tabelas externas do Delta Lake sem uma conexão, não é recomendável por estes motivos:

Os usuários podem ter erros ACCESS_DENIED ao tentar acessar arquivos no Cloud Storage.
Recursos como o controle de acesso granular só estão disponíveis nas tabelas do Delta Lake BigLake.

Atualizar tabelas do Delta Lake

Para atualizar o esquema das tabelas do Delta Lake, siga estas etapas.

bq

Em um ambiente de linha de comando, use o comando bq update para atualizar o esquema da tabela do Delta Lake:

bq update --autodetect_schema PROJECT_ID:DATASET.DELTALAKE_TABLE_NAME

Substitua os seguintes valores:

PROJECT_ID: o ID do projeto em que você quer criar a tabela do Delta Lake
DATASET: o conjunto de dados do BigQuery para conter a tabela do Delta Lake
DELTALAKE_TABLE_NAME: o nome da sua tabela do Delta Lake

REST

Use a API BigQuery para atualizar uma tabela do Delta Lake chamando o método da API tables.patch:

REQUEST='{
  "externalDataConfiguration": {
    "sourceFormat": "DELTA_LAKE",
    "sourceUris": [
      "DELTA_TABLE_GCS_BASE_PATH"
    ],
    "connectionId": "PROJECT_ID.REGION.CONNECTION_ID",
    "autodetect": true
  },
  "tableReference": {
    "tableId": "DELTALAKE_TABLE_NAME"
  }
}'
echo $REQUEST |curl -X POST -d @- -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables

Substitua os seguintes valores:

DELTA_TABLE_GCS_BASE_PATH: o prefixo da tabela do Delta Lake.
PROJECT_ID: o ID do projeto em que você quer criar a tabela do Delta Lake
REGION: a região que contém a conexão para criar a tabela do Delta Lake, 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, o ID da conexão é o valor na última seção do ID totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.
DELTALAKE_TABLE_NAME: o nome da sua tabela do Delta Lake
DATASET: o conjunto de dados do BigQuery para conter a tabela do Delta Lake

Consultar tabelas do Delta Lake

Depois de criar uma tabela do BigLake do Delta Lake, será possível consultá-la usando a sintaxe do GoogleSQL, da mesma forma que você faria com uma tabela padrão do BigQuery. Por exemplo:

SELECT field1, field2 FROM mydataset.my_cloud_storage_table;

Para mais informações, consulte Consultar dados do Cloud Storage em tabelas do BigLake.

Uma conexão externa associada a uma conta de serviço é usada para se conectar ao repositório de dados. Como a conta de serviço recupera dados do repositório de dados, os usuários só precisam acessar a tabela do Delta Lake.

Mapeamento de dados

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

Tipo do Delta Lake	Tipo do BigQuery
`boolean`	`BOOL`
`byte`	`INT64`
`int`	`INT64`
`long`	`INT64`
`float`	`FLOAT64`
`double`	`FLOAT64`
`Decimal(P/S)`	`NUMERIC` ou `BIG_NUMERIC`, dependendo da precisão
`date`	`DATE`
`time`	`TIME`
`timestamp (not partition column)`	`TIMESTAMP`
`timestamp (partition column)`	`DATETIME`
`string`	`STRING`
`binary`	`BYTES`
`array<Type>`	`ARRAY<Type>`
`struct`	`STRUCT`
`map<KeyType, ValueType>`	`ARRAY<Struct<key KeyType, value ValueType>>`

Limitações

As tabelas do Delta Lake têm limitações das tabelas do BigLake e também as seguintes limitações:

Oferece suporte à versão de leitor 3 do Delta Lake com vetores de exclusão e mapeamento de colunas.
Não oferece suporte a pontos de verificação do Delta Lake V2.
Liste a versão do leitor no último arquivo de entrada de registro. Por exemplo, novas tabelas precisam incluir 00000..0.json.
As operações de captura de dados alterados (CDC) não são compatíveis. Todas as operações de CDC existentes serão ignoradas.
O esquema é detectado automaticamente. Não é possível modificar o esquema usando o BigQuery.
Os nomes das colunas da tabela precisam aderir às restrições de nome de coluna do BigQuery.
Não há suporte para visualizações materializadas.
A API Read não é compatível com o Delta Lake.

Solução de problemas

Esta seção oferece ajuda com as tabelas do Delta Lake BigLake. Para mais ajuda geral com a solução de problemas de consultas do BigQuery, consulte Resolver problemas de consulta.

Tempo limite da consulta e erros de recursos

Verifique o diretório de registros (gs://bucket/warehouse/basictable/_delta_log) da tabela Delta Lake e procure arquivos JSON com um número de versão maior que o ponto de verificação anterior. É possível conferir o número da versão listando o diretório ou inspecionando o arquivo _delta_log/_last_checkpoint. Arquivos JSON maiores que 10 MiB podem retardar a expansão da tabela, o que pode levar a problemas de tempo limite e recursos. Para resolver esse problema, use o comando abaixo para criar um novo ponto de verificação para que as consultas ignorem a leitura dos arquivos JSON:

  spark.sql("ALTER TABLE delta.`gs://bucket/mydeltatabledir` SET TBLPROPERTIES ('delta.checkpointInterval' = '1')");

Os usuários podem usar o mesmo comando para redefinir o intervalo de pontos de controle para o valor padrão de 10 ou para um valor que evite ter mais de 50 MB de arquivos JSON entre os pontos de controle.

Nome de coluna inválido

Verifique se o mapeamento de colunas está ativado para a tabela do Delta Lake. O mapeamento de colunas é compatível com a versão 2 ou mais recente do Reader. Para a versão 1 do Reader, defina "delta.columnMapping.mode" como "name" usando o seguinte comando:

spark.sql("ALTER TABLE delta.`gs://bucket/mydeltatabledir` SET TBLPROPERTIES ('delta.columnMapping.mode' = 'name', 'delta.minReaderVersion' = '3', 'delta.minWriterVersion' = '7')");

Se o nome da coluna inválido atender às restrições flexíveis de nome de coluna, entre em contato com o Suporte do Google Cloud ou com biglake-help@google.com.

Erros de acesso negado

Para diagnosticar problemas com as tabelas do Delta Lake BigLake, verifique o seguinte:

Verifique se você está usando tabelas do Delta Lake BigLake (com uma conexão).
Os usuários têm a permissão necessária definida.

Desempenho

Para melhorar a performance da consulta, siga estas etapas:

Use os utilitários do Delta Lake para compactar os arquivos de dados e remover arquivos redundantes, como dados e metadados.
Verifique se delta.checkpoint.writeStatsAsStruct está definido como true.
Verifique se as variáveis usadas com frequência em cláusulas de predicado estão em colunas de partição.

Conjuntos de dados grandes (maiores que 100 TB) podem se beneficiar de outras configurações e recursos. Se as etapas anteriores não resolverem seus problemas, entre em contato com o atendimento ao cliente ou envie um e-mail para biglake-help@google.com, especialmente para conjuntos de dados maiores que 100 TB.