Criar tabelas externas 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 do 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 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

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorador, selecione o projeto em que você quer criar o conjunto de dados.
3. Expanda a opção Ver ações e clique em Criar conjunto de dados.
4. Na página Criar conjunto de dados, especifique os seguintes detalhes:
1. Em ID do conjunto de dados, insira um nome exclusivo para o conjunto de dados.
2. Em Local dos dados, escolha uma região compatível.
3. 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.
4. 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.
5. 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:

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

   Ir para o BigQuery

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

   CREATE SCHEMA mydataset
   OPTIONS (
     location = 'aws-us-east-1');

3. 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.

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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetInfo;

// Sample to create a aws dataset
public class CreateDatasetAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Note: As of now location only supports aws-us-east-1
    String location = "aws-us-east-1";
    createDatasetAws(projectId, datasetName, location);
  }

  public static void createDatasetAws(String projectId, String datasetName, String location) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      DatasetInfo datasetInfo =
          DatasetInfo.newBuilder(projectId, datasetName).setLocation(location).build();

      Dataset dataset = bigquery.create(datasetInfo);
      System.out.println(
          "Aws dataset created successfully :" + dataset.getDatasetId().getDataset());
    } catch (BigQueryException e) {
      System.out.println("Aws dataset was not created. \n" + e.toString());
    }
  }
}

Criar tabelas do BigLake em dados não particionados

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, expanda seu projeto e selecione um conjunto de dados.

3. Na seção Informações do conjunto de dados, clique em Criar tabela.

4. Na página Criar tabela, na seção Origem, faça o seguinte:

   1. Em Criar tabela de, selecione Amazon S3.
   2. Em Selecionar caminho S3, insira um URI que aponta para os dados do Amazon S3 no formato s3://BUCKET_NAME/PATH. Substitua BUCKET_NAME pelo nome do bucket do Amazon S3. A região do bucket precisa ser a mesma do conjunto de dados. Substitua PATH pelo caminho em que você quer gravar o arquivo exportado. Ele pode conter um caractere curinga *.
   3. Em Formato do arquivo, selecione o formato de dados em S3. Os formatos aceitos são AVRO, CSV, DELTA_LAKE, ICEBERG, JSONL, ORC e PARQUET.

5. Na seção Destino, especifique os seguintes detalhes:

   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 no menu suspenso. Para informações sobre conexões, consulte Conectar ao Amazon S3.

6. 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.

7. Selecione Criar tabela.

SQL

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

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

   Ir para o BigQuery

2. 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, como AVRO, CSV, DELTA_LAKE, ICEBERG ou PARQUET (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 sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

     Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

3. 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, como AVRO, CSV, DELTA_LAKE, ICEBERG ou PARQUET.
• 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 comando bq 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 sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache. Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

Observação: para substituir o projeto padrão, use o parâmetro --project_id=PROJECT_ID. Substitua PROJECT_ID pelo ID do seu projeto do Google Cloud.

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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create an external aws table
public class CreateExternalTableAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String connectionId = "MY_CONNECTION_ID";
    String sourceUri = "s3://your-bucket-name/";
    CsvOptions options = CsvOptions.newBuilder().setSkipLeadingRows(1).build();
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    ExternalTableDefinition externalTableDefinition =
        ExternalTableDefinition.newBuilder(sourceUri, options)
            .setConnectionId(connectionId)
            .setSchema(schema)
            .build();
    createExternalTableAws(projectId, datasetName, tableName, externalTableDefinition);
  }

  public static void createExternalTableAws(
      String projectId,
      String datasetName,
      String tableName,
      ExternalTableDefinition externalTableDefinition) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(projectId, datasetName, tableName);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, externalTableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Aws external table created successfully");

      // Clean up
      bigquery.delete(TableId.of(projectId, datasetName, tableName));
    } catch (BigQueryException e) {
      System.out.println("Aws external was not created." + e.toString());
    }
  }
}

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

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

3. Clique em Acessar ações e depois em Criar tabela. O painel Criar tabela será aberto.

4. Na seção Origem, especifique os seguintes campos:

   1. Em Criar tabela de, selecione Amazon S3.

   2. 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.

   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 Esquema de chave de partição personalizado.

5. 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.

6. 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.

7. 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.

8. Selecione Criar tabela.

SQL

Use a instrução DDL CREATE EXTERNAL TABLE:

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

   Ir para o BigQuery

2. 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 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/
   • 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 sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

     Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

3. 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 comando bq 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 sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache. Defina CACHE_MODE se STALENESS_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 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 --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:

1. 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 do Amazon S3.

Ver metadados do recurso

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

É possível consultar os metadados do recurso com visualizações INFORMATION_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

1. Acessar a página do BigQuery.

   Ir para o BigQuery

2. Se a guia Editor não estiver visível, clique em Criar nova consulta.

3. Clique em Mais > Configurações de consulta. A caixa de diálogo Configurações de consulta é aberta.

4. 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.

5. 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

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

   Acessar o VPC Service Controls

2. 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. 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:

1. Defina a política de acesso padrão.
2. Crie o arquivo de entrada da política de saída.
3. 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 acesso à VPC Omni do BigQuery ao Amazon S3

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para solicitar feedback ou suporte para este recurso, envie um e-mail para [e-mail].

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.