Criar tabelas do Amazon S3 BigLake
Este documento descreve como criar uma tabela do BigLake do Amazon Simple Storage Service (Amazon S3). Uma tabela BigLake permite usar a delegação de acesso para consultar dados no Amazon S3. 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 Amazon S3, consulte Fluxo de dados ao consultar dados.
Antes de começar
Verifique se você tem uma conexão para acessar dados do Amazon S3.
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 como conceder papéis, consulte Gerenciar acesso.
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 papéis personalizados ou outros papéis predefinidos.
crie 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.
- No painel Explorer, 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 Amazon S3 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 exemplo a seguir cria um conjunto de dados na região aws-us-east-1
:
No Console do Google Cloud, acesse a página BigQuery.
No editor de consultas, digite a seguinte instrução:
CREATE SCHEMA mydataset OPTIONS ( location = 'aws-us-east-1');
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 dadosPara 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 projetoDATASET_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
.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Criar tabelas do BigLake em dados não particionados
Selecione uma das seguintes opções:
Console
Acessar a página do 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:
- Em Criar tabela de, selecione Amazon S3.
- Em Selecionar caminho S3, insira um URI que aponta para os dados do Amazon S3 no formato
s3://BUCKET_NAME/PATH
. SubstituaBUCKET_NAME
pelo nome do bucket do Amazon S3. A região do bucket precisa ser a mesma do conjunto de dados. SubstituaPATH
pelo caminho em que você quer gravar o arquivo exportado. Ele pode conter um caractere curinga*
. - Em Formato do arquivo, selecione o formato de dados em S3. Os formatos aceitos são AVRO, AVRO, AVRO, AVRO, AVRO, AVRO e AVRO.
Na seção Destino, especifique os seguintes detalhes:
- Em Conjunto de dados, escolha o conjunto de dados adequado.
- No campo Tabela, insira o nome da tabela.
- Verifique se o Tipo de tabela está definido como Tabela externa.
- Em ID da conexão, escolha o ID apropriado no menu suspenso. Para informações sobre conexões, consulte Conectar ao Amazon S3.
Se você tiver um arquivo de origem, na seção Esquema, ative a detecção automática de esquema ou especifique manualmente um esquema. 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.
No editor de consultas, digite a seguinte instrução:
CREATE EXTERNAL TABLE DATASET_NAME.TABLE_NAME WITH CONNECTION `AWS_LOCATION.CONNECTION_NAME` OPTIONS ( format = "DATA_FORMAT", uris = ["S3_URI"], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE');
Substitua:
DATASET_NAME
: o nome do conjunto de dados que você criou.TABLE_NAME
: o nome que você quer dar a esta tabela.AWS_LOCATION
: um local da AWS no Google Cloud (por exemplo, "aws-us-east-1").CONNECTION_NAME
: o nome da conexão que você criou.DATA_FORMAT
: qualquer um dos formatos federados do BigQuery compatíveis, comoAVRO
,CSV
,DELTA_LAKE
,ICEBERG
ouPARQUET
(pré-lançamento)S3_URI
: um URI que aponta para os dados do S3 (por exemplo,s3://bucket/path
).STALENESS_INTERVAL
: especifica se os metadados em cache são usados pelas operações na tabela do BigLake e quando eles precisam ser atualizados para que a operação possa usá-los. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.
Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique
INTERVAL 4 HOUR
para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados armazenados em cache forem mais antigos que isso, a operação vai recuperar metadados do Amazon S3.CACHE_MODE
: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.Defina como
AUTOMATIC
para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.Defina como
MANUAL
se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para atualizar o cache.Defina
CACHE_MODE
seSTALENESS_INTERVAL
estiver definido como um valor maior que 0.
Clique em
Executar.
Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.
Exemplo:
CREATE EXTERNAL TABLE awsdataset.awstable WITH CONNECTION `aws-us-east-1.s3-read-connection` OPTIONS ( format="CSV", uris=["s3://s3-bucket/path/file.csv"], max_staleness = INTERVAL 1 DAY, metadata_cache_mode = 'AUTOMATIC' );
bq
Crie um arquivo de definição da tabela:
bq mkdef \ --source_format=DATA_FORMAT \ --connection_id=AWS_LOCATION.CONNECTION_NAME \ --metadata_cache_mode=CACHE_MODE \ S3_URI > table_def
Substitua:
DATA_FORMAT
: qualquer um dos formatos federados do BigQuery compatíveis, comoAVRO
,CSV
,DELTA_LAKE
,ICEBERG
ouPARQUET
.S3_URI
: um URI que aponta para os dados do S3 (por exemplo,s3://bucket/path
).AWS_LOCATION
: um local da AWS no Google Cloud (por exemplo,aws-us-east-1
).CONNECTION_NAME
: o nome da conexão que você criou.CACHE_MODE
: especifica se o cache de metadados é atualizado de forma automática ou manual. Você só precisa incluir essa flag se também planeja usar a flag--max_staleness
no comandobq mk
subsequente para ativar o armazenamento em cache de metadados. Para mais considerações sobre o armazenamento de metadados em cache, consulte Armazenamento de metadados em cache para fins de desempenho.Defina como
AUTOMATIC
para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.Defina como
MANUAL
se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para atualizar o cache. DefinaCACHE_MODE
seSTALENESS_INTERVAL
estiver definido como um valor maior que 0.
Em seguida, crie a tabela do BigLake:
bq mk --max_staleness=STALENESS_INTERVAL --external_table_definition=table_def DATASET_NAME.TABLE_NAME
Substitua:
STALENESS_INTERVAL
: especifica se os metadados em cache são usados pelas operações na tabela do BigLake e quando eles precisam ser atualizados para que a operação possa usá-los. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.
Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique
INTERVAL 4 HOUR
para um intervalo de inatividade de quatro horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados armazenados em cache forem mais antigos que isso, a operação vai recuperar metadados do Amazon S3.DATASET_NAME
: o nome do conjunto de dados que você criou.TABLE_NAME
: o nome que você quer dar a esta tabela.
Por exemplo, o comando a seguir cria uma tabela externa,
awsdataset.awstable
, que pode consultar os dados da Amazon S3 armazenados
no caminho s3://s3-bucket/path/file.csv
e tem uma conexão de leitura no
local aws-us-east-1
:
bq mkdef \ --autodetect \ --source_format=CSV \ --connection_id=aws-us-east-1.s3-read-connection \ --metadata_cache_mode=AUTOMATIC \ s3://s3-bucket/path/file.csv > table_def bq mk --max_staleness=INTERVAL "1" HOUR \ --external_table_definition=table_def awsdataset.awstable
API
Chame o método de API tables.insert
e crie um
ExternalDataConfiguration
no recurso Table
que você transmite.
Especifique a property schema
ou defina a property 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 a ser usada para se conectar ao Amazon S3.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Criar tabelas do BigLake em dados particionados
É possível criar uma tabela do BigLake para dados particionados no Hive no Amazon S3. 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.
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:
Em Criar tabela de, selecione Amazon S3.
Forneça o caminho para a pasta usando caracteres curinga. Por exemplo,
s3://mybucket/*
.A pasta precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
Na lista Formato de arquivo, selecione o tipo de arquivo.
Marque a caixa de seleção Particionamento de dados de origem e especifique os seguintes detalhes:
- Em Selecionar prefixo do URI de origem, insira o prefixo de URI. Por exemplo,
s3://mybucket/my_files
. - 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.
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.
- Inferir automaticamente os tipos: defina o modo de detecção do esquema de partição como
- Em Selecionar prefixo do URI de origem, insira o prefixo de URI. Por exemplo,
Na seção Destino, especifique os seguintes detalhes:
- Em Projeto, selecione o projeto em que você quer criar a tabela.
- Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
- Em Tabela, insira o nome da tabela que você quer criar.
- Em Tipo de tabela, verifique se Tabela externa está selecionado.
- 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.
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" max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE' );
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 particionamentoREGION
: 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/
FILE_PATH
: caminho para a fonte de dados da tabela externa que você quer criar, por exemplo,s3://mybucket/*.parquet
TABLE_FORMAT
: o formato da tabela que você quer criar, por exemplo,PARQUET
STALENESS_INTERVAL
: especifica se os metadados em cache são usados pelas operações na tabela do BigLake e quando eles precisam ser atualizados para que a operação possa usá-los. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.
Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique
INTERVAL 4 HOUR
para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados armazenados em cache forem mais antigos que isso, a operação vai recuperar metadados do Amazon S3.CACHE_MODE
: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.Defina como
AUTOMATIC
para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.Defina como
MANUAL
se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para atualizar o cache.Defina
CACHE_MODE
seSTALENESS_INTERVAL
estiver definido como um valor maior que 0.
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/*'] max_staleness = INTERVAL 1 DAY, metadata_cache_mode = 'AUTOMATIC' );
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 \ --metadata_cache_mode=CACHE_MODE \ 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
.CACHE_MODE
: especifica se o cache de metadados é atualizado de forma automática ou manual. Você só precisa incluir essa flag se também planeja usar a flag--max_staleness
no comandobq mk
subsequente para ativar o armazenamento em cache de metadados. Para mais considerações sobre o armazenamento de metadados em cache, consulte Armazenamento de metadados em cache para fins de desempenho.Defina como
AUTOMATIC
para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.Defina como
MANUAL
se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para atualizar o cache. DefinaCACHE_MODE
seSTALENESS_INTERVAL
estiver definido como um valor maior que 0.URIS
: o caminho para a pasta do Amazon S3, 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=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 --max_staleness=STALENESS_INTERVAL \ --external_table_definition=DEFINITION_FILE \ DATASET_NAME.TABLE_NAME \ SCHEMA
Substitua:
STALENESS_INTERVAL
: especifica se os metadados em cache são usados pelas operações na tabela do BigLake e quando eles precisam ser atualizados para que a operação possa usá-los. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.
Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique
INTERVAL 4 HOUR
para um intervalo de inatividade de quatro horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados armazenados em cache forem mais antigos que isso, a operação vai recuperar metadados do Amazon S3.DEFINITION_FILE
: o caminho para o arquivo de definição da tabela.DATASET_NAME
: o nome do conjunto de dados onde está a tabelaTABLE_NAME
: o nome da tabela que você está criando;SCHEMA
especifica um caminho para um arquivo de esquema JSON ou especifica o esquema no formatofield: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 --max_staleness=INTERVAL "1" HOUR \
--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 \
--metadata_cache_mode=AUTOMATIC \
s3://mybucket/myTable/* > mytable_def
bq mk --max_staleness=INTERVAL "1" HOUR \
--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 atualizarDATASET
: o conjunto de dados que contém a tabela que você quer atualizarTABLE
: 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 do Amazon S3.
Ver metadados do recurso
É possível consultar os metadados do recurso com visualizaçõesINFORMATION_SCHEMA
. Ao consultar visualizações
JOBS_BY_*
,
JOBS_TIMELINE_BY_*
e
RESERVATION*
,
você precisa especificar 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.
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
, especifiqueus-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-aws-us-east-1.INFORMATION_SCHEMA.JOBS limit 10;"
bq query --use_legacy_sql=false --location=asia-northeast3 \
"SELECT * FROM region-aws-ap-northeast-2.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
.
O exemplo a seguir lista os jobs de atualização de metadados:
SELECT * FROM `region-aws-us-east-1.INFORMATION_SCHEMA.JOBS_BY_PROJECT` WHERE job_id LIKE '%metadata_cache_refresh%' AND creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 6 HOUR) ORDER BY start_time desc LIMIT 10;
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.
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:
No painel Regras de saída, clique em Adicionar regra.
Na seção De atributos do cliente da API, selecione uma opção na lista Identidade.
Selecione Para atributos de recursos externos.
Para adicionar um recurso externo, clique em Adicionar recursos externos.
Na caixa de diálogo Adicionar recurso externo, em Nome do recurso externo, insira um nome de recurso válido. 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.
Selecione os métodos que você quer permitir nos recursos externos:
- Se você quiser permitir todos os métodos, selecione Todos os métodos na lista Métodos.
- 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.
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 blocofrom
tem permissão para acessar.serviceName
: definabigquery.googleapis.com
para o BigQuery Omni.methodSelectors
: lista métodos que um cliente que atende às condições defrom
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étodosserviceName
.permission
: uma permissão de serviço válida, como\"*\"
,externalResource.read
ouexternalResource.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, comos3://bucket_name
, ou por um caminho de contêiner do Armazenamento de Blobs, comoazure://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
ouidentities
: 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 acesso à VPC Omni do BigQuery ao Amazon S3
Para solicitar feedback ou suporte para este recurso, envie um e-mail para [email protected].
Como administrador do BigQuery, você pode criar uma política de bucket S3 para conceder ao BigQuery Omni acesso aos seus recursos do Amazon S3. Isso garante que apenas VPCs do BigQuery Omni autorizadas possam interagir com o Amazon S3, aumentando a segurança dos dados.
Aplicar uma política de bucket S3 à VPC Omni do BigQuery
Para aplicar uma política de bucket do S3, use a CLI da AWS ou o Terraform:
CLI da AWS
Execute o comando a seguir para aplicar uma política de bucket S3 que inclui uma
condição usando o atributo aws:SourceVpc
:
aws s3api put-bucket-policy \ --bucket=BUCKET_NAME \ --policy "{ \"Version\": \"2012-10-17\", \"Id\": \"RestrictBucketReads\", \"Statement\": [ { \"Sid\": \"AccessOnlyToOmniVPC\", \"Principal\": \"*\", \"Action\": [\"s3:ListBucket\", \"s3:GetObject\"], \"Effect\": \"Allow\", \"Resource\": [\"arn:aws:s3:::BUCKET_NAME\", \"arn:aws:s3:::BUCKET_NAME/*\"], \"Condition\": { \"StringEquals\": { \"aws:SourceVpc\": \"VPC_ID\" } } } ] }"
Substitua:
BUCKET_NAME
: o bucket do Amazon S3 que você quer que o BigQuery acesse.VPC_ID
: o ID da VPC Omni do BigQuery da região do BigQuery Omni alocada com o bucket Amazon S3. Você encontra essas informações na tabela desta página.
Terraform
Adicione o seguinte ao seu arquivo de configuração do Terraform:
resource "aws_s3_bucket" "example" { bucket = "BUCKET_NAME" } resource "aws_s3_bucket_policy" "example" { bucket = aws_s3_bucket.example.id policy = jsonencode({ Version = "2012-10-17" Id = "RestrictBucketReads" Statement = [ { Sid = "AccessOnlyToOmniVPC" Effect = "Allow" Principal = "*" Action = ["s3:GetObject", "s3:ListBucket"] Resource = [ aws_s3_bucket.example.arn, "${aws_s3_bucket.example.arn}/*" ] Condition = { StringEquals = { "aws:SourceVpc": "VPC_ID" } } }, ] }) }
Substitua:
BUCKET_NAME
: o bucket do Amazon S3 que você quer que o BigQuery acesse.VPC_ID
: o ID da VPC Omni do BigQuery da região do BigQuery Omni alocada com o bucket Amazon S3.
IDs de recursos da VPC BigQuery Omni
Região | ID da VPC |
---|---|
aws-ap-northeast-2 | vpc-0b488548024288af2 |
aws-ap-southeast-2 | vpc-0726e08afef3667ca |
aws-eu-central-1 | vpc-05c7bba12ad45558f |
aws-eu-west-1 | vpc-0e5c646979bbe73a0 |
aws-us-east-1 | vpc-0bf63a2e71287dace |
aws-us-west-2 | vpc-0cc24e567b9d2c1cb |
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.
- Use o laboratório do BigQuery Omni com a AWS
- Saiba mais sobre as tabelas BigLake.
- Saiba como exportar resultados de consultas para o Amazon S3.
- Saiba como criar visualizações materializadas em tabelas com cache de metadados do Amazon Simple Storage Service (Amazon S3).
- Saiba como disponibilizar localmente os dados do Amazon S3 em uma visualização materializada para mesclagens ao criar uma réplica da visualização materializada.