Criar tabelas do BigLake no armazenamento de blobs

Este documento descreve como criar uma tabela BigLake de armazenamento de blobs do Azure. Uma tabela BigLake permite que você use a delegação de acesso para consultar dados Blob Storage. A delegação de acesso desacopla o acesso à tabela do BigLake ao acesso ao armazenamento de dados subjacente.

Para informações sobre como os dados fluem entre o BigQuery e o Armazenamento de Blobs, consulte Fluxo de dados ao consultar dados.

Antes de começar

Verifique se você tem uma conexão para acessar dados no Blob Storage.

Funções exigidas

Para receber as permissões necessárias a fim de criar uma tabela externa, peça ao administrador para conceder a você o papel do IAM de Administrador do BigQuery (roles/bigquery.admin) no seu conjunto de dados. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar uma tabela externa. Para conferir 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:

bigquery.tables.create
bigquery.connections.delegate

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

Criar um conjunto de dados

Antes de criar uma tabela externa, você precisa criar um conjunto de dados na região compatível. Selecione uma destas opções:

Console

Acessar a página do BigQuery.

Acessar o BigQuery
No painel Explorador, selecione o projeto em que você quer criar o conjunto de dados.
Expanda a opção Ver ações e clique em Criar conjunto de dados.
Na página Criar conjunto de dados, especifique os seguintes detalhes:

Em ID do conjunto de dados, insira um nome exclusivo para o conjunto de dados.
Em Local dos dados, escolha uma região compatível.
Para excluir tabelas automaticamente, marque a caixa de seleção Ativar expiração da tabela e defina a idade máxima da tabela padrão em dias. Os dados no Azure não são excluídos quando a tabela expira.
Se você quiser usar a ordenação padrão, expanda a seção Opções avançadas e selecione Ativar a ordenação padrão.
Clique em Criar conjunto de dados.

SQL

Use a instrução DDL CREATE SCHEMA. O seguinte exemplo cria um conjunto de dados na região azure-eastus2:

No console do Google Cloud, acesse a página BigQuery.

Ir para o BigQuery

No editor de consultas, digite a seguinte instrução:

CREATE SCHEMA mydataset
OPTIONS (
  location = 'azure-eastus2');

Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Em um ambiente de linha de comando, crie um conjunto de dados usando o comando bq mk:

bq --location=LOCATION mk \
    --dataset \
PROJECT_ID:DATASET_NAME

O parâmetro --project_id substitui o projeto padrão.

Substitua:

LOCATION: o local do conjunto de dados

Para informações sobre regiões com suporte, consulte Locais. Depois de criar um conjunto de dados, não será possível alterar o local dele. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.
PROJECT_ID: ID do projeto
DATASET_NAME: o nome da imagem que você quer criar.

Para criar um conjunto de dados em um projeto diferente do projeto padrão, adicione a ID do projeto ao nome do conjunto de dados no seguinte formato: PROJECT_ID:DATASET_NAME.

Criar tabelas do BigLake em dados não particionados

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Ir para o BigQuery
No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
Na seção Informações do conjunto de dados, clique em Criar tabela.
Na página Criar tabela, na seção Origem, faça o seguinte:
1. Em Criar tabela em, selecione Armazenamento de Blobs do Azure.
2. Em Selecionar caminho do Armazenamento de Blobs do Azure, insira um caminho do Armazenamento de Blobs usando este formato: azure://AZURE_STORAGE_ACCOUNT_NAME.blob.core.windows.net/CONTAINER_NAME/FILE_PATH.
  
  Substitua:
  - AZURE_STORAGE_ACCOUNT_NAME: o nome da conta do Blob Storage. A região da conta precisa ser a mesma do conjunto de dados.
  - CONTAINER_NAME: o nome do contêiner do Blob Storage.
  - FILE_PATH: o caminho de dados que aponta para os dados do Blob Storage. Por exemplo, para um único arquivo CSV, FILE_PATH pode ser myfile.csv.
3. Em Formato do arquivo, selecione o formato de dados no Azure. Os formatos aceitos são AVRO, CSV, DELTA_LAKE, ICEBERG, JSONL, ORC e PARQUET.
Na seção Destino, faça o seguinte:
1. Em Conjunto de dados, escolha o conjunto de dados adequado.
2. No campo Tabela, insira o nome da tabela.
3. Verifique se o Tipo de tabela está definido como Tabela externa.
4. Em ID da conexão, escolha o ID apropriado na lista suspensa. Para informações sobre conexões, consulte Conectar-se ao armazenamento de Blob Storage.
Na seção Esquema, é possível ativar a detecção automática de esquema ou especificar manualmente um esquema se você tiver um arquivo de origem. Se você não tiver um arquivo de origem, especifique um esquema manualmente.
- Para ativar a detecção automática de esquema, selecione a opção Detectar automaticamente.
- Para especificar um esquema manualmente, deixe a opção Detectar automaticamente desmarcada. Ative Editar como texto e insira o esquema da tabela como uma matriz JSON.
Selecione Criar tabela.

SQL

Para criar uma tabela do BigLake, use a instrução CREATE EXTERNAL TABLE com a cláusula WITH CONNECTION:

No Console do Google Cloud, acesse a página BigQuery.

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
CREATE EXTERNAL TABLE DATASET_NAME.TABLE_NAME
WITH CONNECTION `AZURE_LOCATION.CONNECTION_NAME`
  OPTIONS (
    format = 'DATA_FORMAT',
    uris = ['azure://AZURE_STORAGE_ACCOUNT_NAME.blob.core.windows.net/CONTAINER_NAME/FILE_PATH']);
```
Substitua:
- DATASET_NAME: o nome do conjunto de dados que você criou.
- TABLE_NAME: o nome que você quer dar a esta tabela.
- AZURE_LOCATION: um local do Azure no Google Cloud, como azure-eastus2.
- CONNECTION_NAME: o nome da conexão que você criou.
- DATA_FORMAT: qualquer um dos formatos federados do BigQuery compatíveis, como AVRO, CSV, DELTA_LAKE ou ICEBERG (pré-lançamento)
- AZURE_STORAGE_ACCOUNT_NAME: o nome da conta do armazenamento de blobs.
- CONTAINER_NAME: o nome do contêiner do Blob Storage.
- FILE_PATH: o caminho de dados que aponta para os dados do Blob Storage.
Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

Exemplo:

CREATE EXTERNAL TABLE absdataset.abstable
WITH CONNECTION `azure-eastus2.abs-read-conn`
  OPTIONS (
    format = 'CSV', uris = ['azure://account_name.blob.core.windows.net/container/path/file.csv']);

bq

Crie um arquivo de definição da tabela:

bq mkdef  \
    --source_format=DATA_FORMAT \
    --connection_id=AZURE_LOCATION.CONNECTION_NAME \
    "azure://AZURE_STORAGE_ACCOUNT_NAME.blob.core.windows.net/CONTAINER_NAME/FILE_PATH" > table_def

Substitua:

DATA_FORMAT: qualquer um dos formatos federados do BigQuery compatíveis, como AVRO, CSV, ICEBERG ou PARQUET
AZURE_LOCATION: um local do Azure no Google Cloud, como azure-eastus2.
CONNECTION_NAME: o nome da conexão que você criou.
AZURE_STORAGE_ACCOUNT_NAME: o nome da conta do armazenamento de blobs.
CONTAINER_NAME: o nome do contêiner do Blob Storage.
FILE_PATH: o caminho de dados que aponta para os dados do Blob Storage.

Em seguida, crie a tabela do BigLake:

bq mk --external_table_definition=table_def DATASET_NAME.TABLE_NAME

Substitua:

DATASET_NAME: o nome do conjunto de dados que você criou.
TABLE_NAME: o nome que você quer dar a essa tabela.

Por exemplo, os comandos a seguir criam uma nova tabela do BigLake, my_dataset.my_table, que pode consultar os dados do Armazenamento de Blobs armazenados no caminho azure://account_name.blob.core.windows.net/container/path e tem uma conexão de leitura no local azure-eastus2:

bq mkdef \
    --source_format=AVRO \
    --connection_id=azure-eastus2.read-conn \
    "azure://account_name.blob.core.windows.net/container/path" > table_def

bq mk \
    --external_table_definition=table_def my_dataset.my_table

API

Chame o método de API tables.insert e crie um ExternalDataConfiguration no recurso Table que você transmite.

Especifique a propriedade schema ou defina a propriedade autodetect como true para ativar a detecção automática de esquema para fontes de dados compatíveis.

Especifique a propriedade connectionId para identificar a conexão que será usada para se conectar ao Blob Storage.

Criar tabelas do BigLake em dados particionados

É possível criar uma tabela do BigLake para dados particionados no Hive, no Blob Storage. Depois de criar uma tabela particionada externamente, não será possível alterar a chave de partição. Você precisa recriar a tabela para alterar a chave de partição.

Para criar uma tabela do BigLake com base nos dados particionados do Hive, selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Ir para o BigQuery
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Clique em Acessar ações e depois em Criar tabela. O painel Criar tabela será aberto.
Na seção Origem, especifique os seguintes campos:
1. Em Criar tabela de, selecione uma das seguintes opções:
  - Amazon S3
  - Armazenamento de blobs do Azure
2. Forneça o caminho para a pasta usando caracteres curinga. Por exemplo:
  - Para o Amazon S3: s3://mybucket/*
  - Para armazenamento de blobs: azure://mystorageaccount.blob.core.windows.net/mycontainer/*
  A pasta precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
3. Na lista Formato de arquivo, selecione o tipo de arquivo.
4. Marque a caixa de seleção Particionamento de dados de origem e especifique os seguintes detalhes:
  1. Em Selecionar prefixo do URI de origem, insira o prefixo de URI. Por exemplo, s3://mybucket/my_files.
  2. Opcional: para exigir um filtro de partição em todas as consultas desta tabela, marque a caixa de seleção Exigir filtro de partição. A exigência de um filtro de partição pode reduzir custos e melhorar o desempenho. Para mais informações, consulte Como exigir filtros de predicado em chaves de partição em consultas.
  3. Na seção Modo de inferência de partição, selecione uma das seguintes opções:
    - Inferir automaticamente os tipos: defina o modo de detecção do esquema de partição como AUTO.
    - Todas as colunas são strings: defina o modo de detecção de esquema de partição como STRINGS.
    - Forneça meu próprio: defina o modo de detecção de esquema de partição como CUSTOM e insira manualmente as informações do esquema para as chaves de partição. Para mais informações, consulte Fornecer um esquema de chave de partição personalizado.
Na seção Destino, especifique os seguintes detalhes:
1. Em Projeto, selecione o projeto em que você quer criar a tabela.
2. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
3. Em Tabela, insira o nome da tabela que você quer criar.
4. Em Tipo de tabela, verifique se Tabela externa está selecionado.
5. Em ID da conexão, selecione a conexão que você criou anteriormente.
Na seção Esquema, é possível ativar a detecção automática de esquema ou especificar manualmente um esquema se você tiver um arquivo de origem. Se você não tiver um arquivo de origem, especifique um esquema manualmente.
- Para ativar a detecção automática de esquema, selecione a opção Detectar automaticamente.
- Para especificar um esquema manualmente, deixe a opção Detectar automaticamente desmarcada. Ative Editar como texto e insira o esquema da tabela como uma matriz JSON.
Para ignorar linhas com valores de colunas extras que não correspondem ao esquema, expanda a seção Opções avançadas e selecione Valores desconhecidos.
Selecione Criar tabela.

SQL

Use a instrução DDL CREATE EXTERNAL TABLE:

No Console do Google Cloud, acesse a página BigQuery.

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
WITH PARTITION COLUMNS
(
  PARTITION_COLUMN PARTITION_COLUMN_TYPE,
)
WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (
  hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
  uris=['FILE_PATH'],
  format ="TABLE_FORMAT"
);
```
Substitua:
- PROJECT_ID: o nome do projeto em que você quer criar a tabela, por exemplo, myproject
- DATASET: o nome do conjunto de dados do BigQuery em que você quer criar a tabela (por exemplo, mydataset)
- EXTERNAL_TABLE_NAME: o nome da tabela que você quer criar, por exemplo, mytable
- PARTITION_COLUMN: o nome da coluna de particionamento.
- PARTITION_COLUMN_TYPE: o tipo da coluna de particionamento
- REGION: a região que contém a conexão, por exemplo, us.
- CONNECTION_ID: o nome da conexão. Por exemplo, myconnection
- HIVE_PARTITION_URI_PREFIX: prefixo do URI de particionamento do Hive, por exemplo,
  - s3://mybucket/
  - azure://mystorageaccount.blob.core.windows.net/mycontainer/
- FILE_PATH: caminho para a fonte de dados da tabela externa que você quer criar, por exemplo,
  - s3://mybucket/*.parquet
  - azure://mystorageaccount.blob.core.windows.net/mycontainer/*.parquet
- TABLE_FORMAT: o formato da tabela que você quer criar, por exemplo, PARQUET
Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

Exemplos

O exemplo a seguir cria uma tabela do BigLake com base em dados particionados no Amazon S3. O esquema é detectado automaticamente.

CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "s3://mybucket/products",
  uris = ['s3://mybucket/products/*']
);

O exemplo a seguir cria uma tabela do BigLake com base em dados particionados no armazenamento de blobs. O esquema é especificado.

CREATE EXTERNAL TABLE `my_dataset.my_table`
(
  ProductId INTEGER,
  ProductName, STRING,
  ProductType, STRING
)
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "azure://mystorageaccount.blob.core.windows.net/mycontainer/products",
  uris = ['azure://mystorageaccount.blob.core.windows.net/mycontainer/*']
);

bq

Primeiro, use o comando bq mkdef para criar um arquivo de definição de tabela:

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
 URIS > DEFINITION_FILE

Substitua:

SOURCE_FORMAT: o formato da fonte de dados externa. Por exemplo, CSV.
REGION: a região que contém a conexão, por exemplo, us.
CONNECTION_ID: o nome da conexão. Por exemplo, myconnection.
PARTITIONING_MODE: o modo de particionamento do Hive. Use um dos seguintes valores:
- AUTO: detecta automaticamente os nomes e tipos de chaves.
- STRINGS: converte automaticamente os nomes das chaves em strings.
- CUSTOM: codifique o esquema da chave no prefixo do URI de origem.
URI_SHARED_PREFIX: o prefixo de URI de origem.
BOOLEAN: especifica se um filtro de predicado é necessário no momento da consulta. Essa flag é opcional. O valor padrão é false.
URIS é o caminho para o Amazon S3 ou a pasta do armazenamento de blobs usando o formato de caractere curinga.
DEFINITION_FILE: o caminho para o arquivo de definição de tabelas na máquina local.

Se PARTITIONING_MODE for CUSTOM, inclua o esquema da chave de partição no prefixo do URI de origem, usando este formato:

--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Depois de criar o arquivo de definição de tabela, use o comando bq mk para criar a tabela do BigLake:

bq mk --external_table_definition=DEFINITION_FILE \
DATASET_NAME.TABLE_NAME \
SCHEMA

Substitua:

DEFINITION_FILE: o caminho para o arquivo de definição da tabela.
DATASET_NAME: o nome do conjunto de dados onde está a tabela
TABLE_NAME: o nome da tabela que você está criando;
SCHEMA especifica um caminho para um arquivo de esquema JSON ou especifica o esquema no formato field:data_type,field:data_type,.... Para usar a detecção automática de esquema, omita esse argumento.

Exemplos

Confira no exemplo a seguir como usar o modo de particionamento do Hive AUTO para dados do Amazon S3:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

Confira no exemplo a seguir como usar o modo de particionamento do Hive STRING para dados do Amazon S3:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  s3://mybucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

Confira no exemplo a seguir como usar o modo de particionamento do Hive CUSTOM para dados de armazenamento de blobs:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=CUSTOM \
  --hive_partitioning_source_uri_prefix=azure://mystorageaccount.blob.core.windows.net/mycontainer/{dt:DATE}/{val:STRING} \
  azure://mystorageaccount.blob.core.windows.net/mycontainer/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Para definir o particionamento do Hive usando a API do BigQuery, inclua o objeto hivePartitioningOptions no objeto ExternalDataConfiguration ao criar o arquivo de definição de tabela. Para criar uma tabela do BigLake, especifique também um valor para o campo connectionId.

Se você definir o campo hivePartitioningOptions.mode como CUSTOM, será necessário codificar o esquema da chave de partição no campo hivePartitioningOptions.sourceUriPrefix da seguinte maneira: s3://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Para aplicar o uso de um filtro de predicado no momento da consulta, defina o campo hivePartitioningOptions.requirePartitionFilter como true.

Tabelas do Delta Lake

Delta Lake é um formato de tabela de código aberto compatível com tabelas de dados em escala de petabytes. As tabelas do Delta Lake podem ser consultadas como tabelas temporárias e permanentes e são compatíveis como tabelas do BigLake.

Sincronização de esquema

O Delta Lake mantém um esquema canônico como parte dos metadados. Não é possível atualizar um esquema usando um arquivo de metadados JSON. Para atualizar o esquema:

Use o comando bq update com a sinalização --autodetect_schema:
```
bq update --autodetect_schema
PROJECT_ID:DATASET.TABLE
```
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

Conversão de tipo

O BigQuery converte os tipos de dados do Delta Lake nos seguintes tipos de dados do BigQuery:

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 seguintes limitações se aplicam às tabelas do Delta Lake:

As limitações de tabelas externas se aplicam às tabelas do Delta Lake.
As tabelas do Delta Lake só são compatíveis com o BigQuery Omni e têm as limitações associadas.
Não é possível atualizar uma tabela com um novo arquivo de metadados JSON. Você precisa usar uma operação de atualização de tabela do esquema de detecção automática. Consulte Sincronização de esquema para mais informações.
Os recursos de segurança do BigLake só protegem as tabelas do Delta Lake quando acessados pelos serviços do BigQuery.

Criar uma tabela Delta Lake

No exemplo a seguir, criamos uma tabela externa usando a instrução CREATE EXTERNAL TABLE com o formato Delta Lake:

CREATE [OR REPLACE] EXTERNAL TABLE table_name
WITH CONNECTION connection_name
OPTIONS (
         format = 'DELTA_LAKE',
         uris = ["parent_directory"]
       );

Substitua:

table_name: o nome da tabela.
connection_name: o nome da conexão. A conexão precisa identificar uma fonte do Amazon S3 ou de uma fonte de Armazenamento de blobs.
parent_directory: o URI do diretório pai.

Transferência entre nuvens com Delta Lake

O exemplo a seguir usa a instrução LOAD DATA para carregar dados na tabela apropriada:

LOAD DATA [INTO | OVERWRITE] table_name
FROM FILES (
        format = 'DELTA_LAKE',
        uris = ["parent_directory"]
)
WITH CONNECTION connection_name;

Para mais exemplos de transferência de dados entre nuvens, consulte Carregar dados com operações entre nuvens.

Consultar tabelas do BigLake

Para mais informações, consulte Consultar dados de armazenamento de blobs.

Ver metadados do recurso com `INFORMATION_SCHEMA`

É possível consultar os metadados do recurso com visualizações INFORMATION_SCHEMA. Ao consultar as visualizações JOBS_BY_*, JOBS_TIMELINE_BY_* e RESERVATION*, especifique o local de processamento da consulta que é colocado com a região da tabela. Para informações sobre locais do BigQuery Omni, consulte Locais. Para todas as outras tabelas do sistema, especificar o local do job de consulta é opcional.

Para informações sobre as tabelas do sistema compatíveis com o BigQuery Omni, consulte Limitações.

Para consultar as tabelas do sistema JOBS_* e RESERVATION*, selecione um dos métodos a seguir para especificar o local de processamento:

Console

Acessar a página do BigQuery.

Ir para o BigQuery
Se a guia Editor não estiver visível, clique em Criar nova consulta.
Clique em Mais > Configurações de consulta. A caixa de diálogo Configurações de consulta é aberta.
Na caixa de diálogo Configurações de consulta, em Outras configurações > Local dos dados, selecione a opção Região do BigQuery que é colocalizada com a região do BigQuery Omni. Por exemplo, se a região do BigQuery Omni for aws-us-east-1, especifique us-east4.
Selecione os campos restantes e clique em Salvar.

bq

Use a flag --location para definir o local de processamento do job como a região do BigQuery que é colocalizada com a região do BigQuery Omni. Por exemplo, se a região do BigQuery Omni for aws-us-east-1, especifique us-east4.

Exemplo

bq query --use_legacy_sql=false --location=us-east4 \
"SELECT * FROM region-azure-eastus2.INFORMATION_SCHEMA.JOBS limit 10;"

API

Se você estiver executando jobs de maneira programática, defina o argumento do local como a região do BigQuery que é colocalizada com a região BigQuery Omni. Por exemplo, se a região do BigQuery Omni for aws-us-east-1, especifique us-east4.

VPC Service Controls

É possível usar os perímetros do VPC Service Controls para restringir o acesso do BigQuery Omni a um serviço de nuvem externo como uma camada extra de defesa. Por exemplo, os perímetros do VPC Service Controls podem limitar as exportações das tabelas do BigQuery Omni para um bucket específico do Amazon S3 ou um contêiner de armazenamento de blobs.

Para saber mais sobre o VPC Service Controls, consulte a Visão geral do VPC Service Controls.

Permissão necessária

Verifique se você tem as permissões necessárias para configurar os perímetros de serviço. Para ver uma lista de papéis do IAM necessários para configurar o VPC Service Controls, consulte Controle de acesso com o IAM na documentação do VPC Service Controls.

Configurar o VPC Service Controls usando o console do Google Cloud

No menu de navegação do console do Google Cloud, clique em Segurança e em VPC Service Controls.

Acessar o VPC Service Controls
Para configurar o VPC Service Controls para o BigQuery Omni, siga as etapas do guia Criar um perímetro de serviço e, quando estiver nas Regras de saída, siga estas etapas:
1. No painel Regras de saída, clique em Adicionar regra.
2. Na seção De atributos do cliente da API, selecione uma opção na lista Identidade.
3. Selecione Para atributos de recursos externos.
4. Para adicionar um recurso externo, clique em Adicionar recursos externos.
5. Na caixa de diálogo Adicionar recurso externo, em Nome do recurso externo, insira um nome de recurso válido. Por exemplo:
  - Para o Amazon Simple Storage Service (Amazon S3): s3://BUCKET_NAME
    
    Substitua BUCKET_NAME pelo nome do seu bucket do Amazon S3.
  - Para o Armazenamento de Blobs do Azure: azure://myaccount.blob.core.windows.net/CONTAINER_NAME
    
    Substitua CONTAINER NAME pelo nome do seu contêiner do Armazenamento do Azure.
  Para uma lista de atributos de regra de saída, consulte Referência de regras de saída.
6. Selecione os métodos que você quer permitir nos recursos externos:
  1. Se você quiser permitir todos os métodos, selecione Todos os métodos na lista Métodos.
  2. Para permitir métodos específicos, selecione Método selecionado, clique em Selecionar métodos e depois selecione os métodos que você quer permitir nos recursos externos.
7. Clique em Criar perímetro.

Configurar o VPC Service Controls usando a CLI gcloud

Para configurar o VPC Service Controls usando a CLI gcloud, siga estas etapas:

Defina a política de acesso padrão.
Crie o arquivo de entrada da política de saída.
Adicione a política de saída.

Definir a política de acesso padrão

Uma política de acesso é um contêiner de toda a organização para níveis de acesso e perímetros de serviço. Para informações sobre como definir uma política de acesso padrão ou conseguir um nome de política de acesso, consulte Como gerenciar uma política de acesso.

Criar o arquivo de entrada da política de saída

Um bloco de regra de saída define o acesso permitido de dentro um perímetro para recursos fora dele. Para recursos externos, a propriedade externalResources define os caminhos de recursos externos permitidos no perímetro do VPC Service Controls.

As regras de saída podem ser configuradas usando um arquivo JSON ou YAML. A amostra a seguir usa o formato .yaml:

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
      *OR*
      - permission: "externalResource.read"
    externalResources:
      - EXTERNAL_RESOURCE_PATH
  egressFrom:
    identityType: IDENTITY_TYPE
    *OR*
    identities:
    - serviceAccount:SERVICE_ACCOUNT

egressTo: lista as operações de serviço permitidas nos recursos do Google Cloud em projetos especificados fora do perímetro.
operations: a lista de ações e serviços acessíveis ou métodos que um cliente que atende às condições do bloco from tem permissão para acessar.
serviceName: defina bigquery.googleapis.com para o BigQuery Omni.
methodSelectors: lista métodos que um cliente que atende às condições de from pode acessar. Para métodos e permissões que podem ser restritos para serviços, consulte Restrições de métodos de serviço compatíveis.
method : um método de serviço válido, ou \"*\" para permitir todos os métodos serviceName.
permission: uma permissão de serviço válida, como \"*\", externalResource.read ou externalResource.write. O acesso a recursos fora do perímetro é permitido para operações que exigem essa permissão.
externalResources: lista os recursos externos que os clientes dentro de um perímetro podem acessar. Substitua EXTERNAL_RESOURCE_PATH por um bucket válido do Amazon S3, como s3://bucket_name, ou por um caminho de contêiner do Armazenamento de Blobs, como azure://myaccount.blob.core.windows.net/container_name.
egressFrom: lista as operações de serviço permitidas nos recursos do Google Cloud em projetos especificados dentro do perímetro.
identityType ou identities: define os tipos de identidade que podem acessar os recursos especificados fora do perímetro. Substitua IDENTITY_TYPE por um dos seguintes valores:
- ANY_IDENTITY: para permitir todas as identidades.
- ANY_USER_ACCOUNT: para permitir todos os usuários.
- ANY_SERVICE_ACCOUNT: para permitir todas as contas de serviço.
identities: lista as contas de serviço que podem acessar os recursos especificados fora do perímetro.
serviceAccount (opcional): substitua SERVICE_ACCOUNT pela conta de serviço que pode acessar os recursos especificados fora do perímetro.

Exemplos

O exemplo a seguir é uma política que permite operações de saída de dentro do perímetro para o local s3://mybucket do S3 na AWS.

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - s3://mybucket
      - s3://mybucket2
  egressFrom:
    identityType: ANY_IDENTITY

O seguinte exemplo permite operações de saída em um contêiner do Armazenamento de Blobs:

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - azure://myaccount.blob.core.windows.net/mycontainer
  egressFrom:
    identityType: ANY_IDENTITY

Para mais informações sobre como políticas de saída, consulte a Referência de regras de saída.

Adicionar a política de saída

Para adicionar a política de saída ao criar um novo perímetro de serviço, use o comando gcloud access-context-manager perimeters create. Por exemplo, o comando a seguir cria um novo perímetro chamado omniPerimeter que inclui o projeto com o número 12345, restringe a API BigQuery e adiciona uma política de saída definida no arquivo egress.yaml:

gcloud access-context-manager perimeters create omniPerimeter \
    --title="Omni Perimeter" \
    --resources=projects/12345 \
    --restricted-services=bigquery.googleapis.com \
    --egress-policies=egress.yaml

Para adicionar a política de saída a um perímetro de serviço que já existe, use o comando gcloud access-context-manager perimeters update. Por exemplo, o comando a seguir adiciona uma política de saída definida no arquivo egress.yaml a um perímetro de serviço que já existe chamado omniPerimeter:

gcloud access-context-manager perimeters update omniPerimeter
    --set-egress-policies=egress.yaml

Verificar o perímetro

Para verificar o perímetro, use o comando gcloud access-context-manager perimeters describe:

gcloud access-context-manager perimeters describe PERIMETER_NAME

Substitua PERIMETER_NAME pelo nome do perímetro.

Por exemplo, o comando a seguir descreve o perímetro omniPerimeter:

gcloud access-context-manager perimeters describe omniPerimeter

Para mais informações, consulte Como gerenciar perímetros de serviço.

Permitir o acesso da VPC do BigQuery Omni ao Armazenamento de Blobs

Para solicitar feedback ou suporte para este recurso, envie um e-mail para bq-omni-customer-support@google.com.

Como administrador do BigQuery, você pode criar uma regra de rede para conceder ao BigQuery Omni acesso aos seus recursos do Armazenamento de blobs. Isso garante que apenas VPCs do BigQuery Omni autorizadas possam interagir com o Amazon S3, aumentando a segurança dos dados.

Aplicar uma regra de rede à VPC Omni do BigQuery

Para aplicar uma regra de rede, use o Azure PowerShell ou o Terraform:

Azure PowerShell

Execute o comando abaixo para adicionar uma regra de rede à sua conta de armazenamento que especifica os IDs de sub-rede do BigQuery Omni recuperados como VirtualNetworkResourceId.

  Add-AzStorageAccountNetworkRule`
   -ResourceGroupName "RESOURCE_GROUP_NAME"`
   -Name "STORAGE_ACCOUNT_NAME"`
   -VirtualNetworkResourceId "SUBNET_ID1","SUBNET_ID2"

Substitua:

RESOURCE_GROUP_NAME: o nome do grupo de recursos.
STORAGE_ACCOUNT_NAME: o nome da conta de armazenamento.
SUBNET_ID1,SUBNET_ID1: os IDs da sub-rede. Você encontra essas informações na tabela desta página.

Terraform

Adicione o seguinte ao seu arquivo de configuração do Terraform:

  resource "azurerm_storage_account_network_rules" "example" {
    storage_account_name       = "STORAGE_ACCOUNT_NAME"
    resource_group_name        = "RESOURCE_GROUP_NAME"
    default_action             = "Allow"
    bypass                     = ["Logging", "Metrics", "AzureServices"]
    virtual_network_subnet_ids = ["SUBNET_ID1","SUBNET_ID2"]
  }

Substitua:

STORAGE_ACCOUNT_NAME: o nome da conta de armazenamento.
RESOURCE_GROUP_NAME: o nome do grupo de recursos.
SUBNET_ID1,SUBNET_ID1: os IDs da sub-rede. Você encontra essas informações na tabela desta página.

IDs de recursos da VPC BigQuery Omni

Região	IDs da sub-rede
azure-eastus2	/subscriptions/95f30708-58d1-48ba-beac-d71870c3b2f5/resourceGroups/bqe-prod-eastus2-resource-group/providers/Microsoft.Network/virtualNetworks/bqe-prod-eastus2-network/subnets/azure-prod-eastus21-yurduaaaaa-private /subscriptions/95f30708-58d1-48ba-beac-d71870c3b2f5/resourceGroups/bqe-prod-eastus2-resource-group/providers/Microsoft.Network/virtualNetworks/bqe-prod-eastus2-network/subnets/azure-prod-eastus22-yurduaaaab-private

Região

IDs da sub-rede

azure-eastus2

/subscriptions/95f30708-58d1-48ba-beac-d71870c3b2f5/resourceGroups/bqe-prod-eastus2-resource-group/providers/Microsoft.Network/virtualNetworks/bqe-prod-eastus2-network/subnets/azure-prod-eastus21-yurduaaaaa-private
/subscriptions/95f30708-58d1-48ba-beac-d71870c3b2f5/resourceGroups/bqe-prod-eastus2-resource-group/providers/Microsoft.Network/virtualNetworks/bqe-prod-eastus2-network/subnets/azure-prod-eastus22-yurduaaaab-private

Limitações

Para acessar uma lista completa de limitações que se aplicam a tabelas do BigLake baseadas no Amazon S3 e no Armazenamento de Blobs, consulte Limitações.

A seguir

Saiba mais sobre o BigQuery Omni.
Saiba mais sobre as tabelas BigLake.
Saiba como exportar resultados de consultas para o Blob Storage.

Criar tabelas do BigLake no armazenamento de blobs

Antes de começar

Funções exigidas

Permissões necessárias

Criar um conjunto de dados

Console

SQL

bq

Criar tabelas do BigLake em dados não particionados

Console

SQL

bq

API

Criar tabelas do BigLake em dados particionados

Console

SQL

bq

API

Tabelas do Delta Lake

Sincronização de esquema

Conversão de tipo

Limitações

Criar uma tabela Delta Lake

Transferência entre nuvens com Delta Lake

Consultar tabelas do BigLake

Ver metadados do recurso com INFORMATION_SCHEMA

Console

bq

API

VPC Service Controls

Permissão necessária

Configurar o VPC Service Controls usando o console do Google Cloud

Configurar o VPC Service Controls usando a CLI gcloud

Definir a política de acesso padrão

Criar o arquivo de entrada da política de saída

Exemplos

Adicionar a política de saída

Verificar o perímetro

Permitir o acesso da VPC do BigQuery Omni ao Armazenamento de Blobs

Aplicar uma regra de rede à VPC Omni do BigQuery

Azure PowerShell

Terraform

IDs de recursos da VPC BigQuery Omni

Limitações

A seguir

Ver metadados do recurso com `INFORMATION_SCHEMA`