Crie tabelas externas do BigLake no Amazon S3

Este documento descreve como criar uma tabela BigLake do Amazon Simple Storage Service (Amazon S3). Uma tabela do BigLake permite-lhe usar a delegação de acesso para consultar dados no Amazon S3. A delegação de acesso dissocia o acesso à tabela do BigLake do acesso ao repositório de dados subjacente.

Para obter 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

Certifique-se de que tem uma ligação para aceder aos dados do Amazon S3.

Funções necessárias

Para receber as autorizações de que precisa para criar uma tabela externa, peça ao seu administrador para lhe conceder a função Administrador do BigQuery (roles/bigquery.admin) do IAM no seu conjunto de dados. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para criar uma tabela externa. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

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

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

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

Crie um conjunto de dados

Antes de criar uma tabela externa, tem de criar um conjunto de dados na região suportada. Selecione uma das seguintes opções:

Consola

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, selecione o projeto onde 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. Para ID do conjunto de dados, introduza um nome exclusivo do conjunto de dados.
2. Para Localização de dados, escolha uma região suportada.
3. Opcional: para eliminar tabelas automaticamente, selecione a caixa de verificação Ativar validade da tabela e defina a Idade máxima predefinida da tabela em dias. Os dados no Amazon S3 não são eliminados quando a tabela expira.
4. Se quiser usar a colação predefinida, expanda a secção Opções avançadas e, em seguida, selecione a opção Ativar colação predefinida.
5. Clique em Criar conjunto de dados.

SQL

Use a CREATE SCHEMA declaração DDL. O exemplo seguinte cria um conjunto de dados na região aws-us-east-1:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração:

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

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Num ambiente de linha de comandos, crie um conjunto de dados com o bq mk comando:

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

O parâmetro --project_id substitui o projeto predefinido.

Substitua o seguinte:

• LOCATION: a localização do seu conjunto de dados

  Para ver informações sobre as regiões suportadas, consulte o artigo Localizações. Depois de criar um conjunto de dados, não pode alterar a respetiva localização. Pode definir um valor predefinido para a localização através do ficheiro .bigqueryrc.

• PROJECT_ID: o ID do seu projeto

• DATASET_NAME: o nome do conjunto de dados que quer criar

  Para criar um conjunto de dados num projeto que não seja o projeto predefinido, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: PROJECT_ID:DATASET_NAME.

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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());
    }
  }
}

Crie tabelas BigLake em dados não particionados

Selecione uma das seguintes opções:

Consola

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, expanda o seu projeto e, de seguida, selecione um conjunto de dados.

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

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

   1. Em Criar tabela a partir de, selecione Amazon S3.
   2. Para Selecionar caminho do S3, introduza um URI que aponte para os dados do Amazon S3 no formato s3://BUCKET_NAME/PATH. Substitua BUCKET_NAME pelo nome do contentor do Amazon S3; a região do contentor deve ser a mesma que a região do conjunto de dados. Substitua PATH pelo caminho para o qual quer escrever o ficheiro exportado. Este pode conter um caráter universal *.
   3. Em Formato de ficheiro, selecione o formato de dados no Amazon S3. Os formatos suportados são AVRO, CSV, DELTA_LAKE, ICEBERG, JSONL, ORC e PARQUET.

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

   1. Para Conjunto de dados, escolha o conjunto de dados adequado.
   2. No campo Tabela, introduza o nome da tabela.
   3. Verifique se o Tipo de tabela está definido como Tabela externa.
   4. Para o ID da associação, escolha o ID da associação adequado no menu pendente. Para obter informações sobre associações, consulte o artigo Ligar ao Amazon S3.

6. Na secção Esquema, pode ativar a deteção automática de esquemas ou especificar manualmente um esquema se tiver um ficheiro de origem. Se não tiver um ficheiro de origem, tem de especificar manualmente um esquema.

   • Para ativar a deteção automática do esquema, selecione a opção Deteção automática.

   • Para especificar manualmente um esquema, desmarque a opção Deteção automática. Ative a opção Editar como texto e introduza o esquema de tabela como uma matriz JSON.

7. Clique em Criar tabela.

SQL

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

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaraçã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 o seguinte:

   • DATASET_NAME: o nome do conjunto de dados que criou
   • TABLE_NAME: o nome que quer dar a esta tabela
   • AWS_LOCATION: uma localização da AWS em Google Cloud (por exemplo, `aws-us-east-1`)
   • CONNECTION_NAME: o nome da associação que criou
   • DATA_FORMAT: qualquer um dos formatos federados do BigQuery suportados (como AVRO, CSV, DELTA_LAKE, ICEBERG ou PARQUET [pré-visualização])
   • S3_URI: um URI que aponta para os dados do Amazon S3 (por exemplo, s3://bucket/path)
   • STALENESS_INTERVAL: especifica se as operações contra a tabela do BigLake usam metadados em cache e qual a atualização dos metadados em cache necessária para que a operação os use. Para mais informações sobre considerações de colocação em cache de metadados, consulte o artigo Colocação em cache de metadados para desempenho.

     Para desativar a colocação em cache de metadados, especifique 0. Esta é a predefinição.

     Para ativar o armazenamento em cache de metadados, especifique um valor literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de desatualização de 4 horas. Com este valor, as operações na tabela usam metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem mais antigos, a operação obtém metadados do Amazon S3.

   • CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente. Para mais informações acerca das considerações sobre o armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Definido como AUTOMATIC para que a cache de metadados seja atualizada a um intervalo definido pelo sistema, normalmente entre 30 e 60 minutos.

     Defina como MANUAL se quiser atualizar a cache de metadados de acordo com uma programação que determinar. Neste caso, pode chamar o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar a cache.

     Tem de definir CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor superior a 0.

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute 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 ficheiro de definição de tabela:

bq mkdef  \
--source_format=DATA_FORMAT \
--connection_id=AWS_LOCATION.CONNECTION_NAME \
--metadata_cache_mode=CACHE_MODE \
S3_URI > table_def

Substitua o seguinte:

• DATA_FORMAT: qualquer um dos formatos federados do BigQuery suportados (como AVRO, CSV, DELTA_LAKE, ICEBERG ou PARQUET).
• S3_URI: um URI que aponta para os dados do Amazon S3 (por exemplo, s3://bucket/path).
• AWS_LOCATION: uma localização da AWS em Google Cloud (por exemplo, aws-us-east-1).

• CONNECTION_NAME: o nome da associação que criou.

• CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente. Só precisa de incluir esta flag se também planear usar a flag --max_staleness no comando bq mk subsequente para ativar o armazenamento em cache de metadados. Para mais informações sobre considerações relativas ao armazenamento em cache de metadados, consulte o artigo Armazenamento em cache de metadados para desempenho.

  Defina como AUTOMATIC para que a cache de metadados seja atualizada num intervalo definido pelo sistema, normalmente entre 30 e 60 minutos.

  Defina como MANUAL se quiser atualizar a cache de metadados de acordo com uma programação que determinar. Neste caso, pode chamar o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar a cache. Tem de definir CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor superior a 0.

Nota: para substituir o projeto predefinido, use o parâmetro --project_id=PROJECT_ID. Substitua PROJECT_ID pelo ID do seu Google Cloud projeto.

Em seguida, crie a tabela do BigLake:

bq mk --max_staleness=STALENESS_INTERVAL --external_table_definition=table_def DATASET_NAME.TABLE_NAME

Substitua o seguinte:

• STALENESS_INTERVAL: especifica se as operações na tabela do BigLake usam metadados em cache e qual a atualização dos metadados em cache necessária para que a operação os use. Para mais informações sobre considerações relativas à colocação em cache de metadados, consulte o artigo Colocação em cache de metadados para desempenho.

  Para desativar a colocação em cache de metadados, especifique 0. Esta é a predefiniçã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 desatualização de 4 horas. Com este valor, as operações na tabela usam metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem mais antigos, a operação obtém metadados do Amazon S3.

• DATASET_NAME: o nome do conjunto de dados que criou.

• TABLE_NAME: o nome que quer dar a esta tabela.

Por exemplo, o comando seguinte cria uma nova tabela do BigLake, awsdataset.awstable, que pode consultar os seus dados do Amazon S3 armazenados no caminho s3://s3-bucket/path/file.csv e tem uma associação de leitura na localização 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 tables.insert da API e crie um ExternalDataConfiguration no recurso Table que transmite.

Especifique a propriedade schema ou defina a propriedade autodetect como true para ativar a deteção automática do esquema para origens de dados suportadas.

Especifique a propriedade da connectionId para identificar a associação a usar para estabelecer ligação ao Amazon S3.

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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());
    }
  }
}

Crie tabelas do BigLake em dados particionados

Pode criar uma tabela BigLake para dados particionados do Hive no Amazon S3. Depois de criar uma tabela particionada externamente, não pode alterar a chave de partição. Tem de recriar a tabela para alterar a chave de partição.

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

Consola

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

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

3. Clique em Ver ações e, de seguida, em Criar tabela. É apresentado o painel Criar tabela.

4. Na secção Origem, especifique os seguintes detalhes:

   1. Em Criar tabela a partir de, selecione Amazon S3.

   2. Indique o caminho para a pasta através de caracteres universais. Por exemplo, s3://mybucket/*.

      A pasta tem de estar na mesma localização que o conjunto de dados que contém a tabela que quer criar, acrescentar ou substituir.

   3. Na lista Formato de ficheiro, selecione o tipo de ficheiro.

   4. Selecione a caixa de verificação Particionamento de dados de origem e, de seguida, especifique os seguintes detalhes:

      1. Para Selecionar prefixo de URI de origem, introduza o prefixo de URI. Por exemplo, s3://mybucket/my_files.
      2. Opcional: para exigir um filtro de partição em todas as consultas para esta tabela, selecione a caixa de verificação Exigir filtro de partição. A exigência de um filtro de partição pode reduzir o custo e melhorar o desempenho. Para mais informações, consulte o artigo Exigir filtros de predicados em chaves de partição em consultas.

      3. Na secção Modo de inferência de partição, selecione uma das seguintes opções:

         • Inferir automaticamente tipos: defina o modo de deteção do esquema de partição como AUTO.
         • Todas as colunas são strings: defina o modo de deteção do esquema de partição como STRINGS.
         • Fornecer os meus próprios: defina o modo de deteção do esquema de partição como CUSTOM e introduza manualmente as informações do esquema para as chaves de partição. Para mais informações, consulte o artigo Esquema de chave de partição personalizado.

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

   1. Para Projeto, selecione o projeto no qual quer criar a tabela.
   2. Em Conjunto de dados, selecione o conjunto de dados no qual quer criar a tabela.
   3. Para Tabela, introduza o nome da tabela que quer criar.
   4. Para Tipo de tabela, verifique se a opção Tabela externa está selecionada.
   5. Em ID da associação, selecione a associação que criou anteriormente.

6. Na secção Esquema, pode ativar a deteção automática de esquemas ou especificar manualmente um esquema se tiver um ficheiro de origem. Se não tiver um ficheiro de origem, tem de especificar manualmente um esquema.

   • Para ativar a deteção automática do esquema, selecione a opção Deteção automática.

   • Para especificar manualmente um esquema, desmarque a opção Deteção automática. Ative a opção Editar como texto e introduza o esquema de tabela como uma matriz JSON.

7. Para ignorar linhas com valores de colunas adicionais que não correspondem ao esquema, expanda a secção Opções avançadas e selecione Valores desconhecidos.

8. Clique em Criar tabela.

SQL

Use a CREATE EXTERNAL TABLE declaração DDL:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaraçã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 o seguinte:

   • PROJECT_ID: o nome do seu projeto no qual quer criar a tabela, por exemplo, myproject
   • DATASET: o nome do conjunto de dados do BigQuery no qual quer criar a tabela, por exemplo, mydataset
   • EXTERNAL_TABLE_NAME: o nome da tabela que quer criar, por exemplo, mytable
   • PARTITION_COLUMN: o nome da coluna de partição
   • PARTITION_COLUMN_TYPE: o tipo da coluna de partição
   • REGION: a região que contém a ligação, por exemplo, us
   • CONNECTION_ID: o nome da associação, por exemplo, myconnection
   • HIVE_PARTITION_URI_PREFIX: particionamento de colmeias prefixo do URI, por exemplo: s3://mybucket/
   • FILE_PATH: caminho para a origem de dados da tabela externa que quer criar, por exemplo: s3://mybucket/*.parquet
   • TABLE_FORMAT: o formato da tabela que quer criar, por exemplo, PARQUET
   • STALENESS_INTERVAL: especifica se as operações contra a tabela do BigLake usam metadados em cache e qual a atualização dos metadados em cache necessária para que a operação os use. Para mais informações sobre considerações de colocação em cache de metadados, consulte o artigo Colocação em cache de metadados para desempenho.

     Para desativar a colocação em cache de metadados, especifique 0. Esta é a predefinição.

     Para ativar o armazenamento em cache de metadados, especifique um valor literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de desatualização de 4 horas. Com este valor, as operações na tabela usam metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem mais antigos, a operação obtém metadados do Amazon S3.

   • CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente. Para mais informações acerca das considerações sobre o armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Definido como AUTOMATIC para que a cache de metadados seja atualizada a um intervalo definido pelo sistema, normalmente entre 30 e 60 minutos.

     Defina como MANUAL se quiser atualizar a cache de metadados de acordo com uma programação que determinar. Neste caso, pode chamar o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar a cache.

     Tem de definir CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor superior a 0.

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

Exemplos

O exemplo seguinte cria uma tabela do BigLake sobre dados particionados no Amazon S3. O esquema é detetado 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 ficheiro 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 o seguinte:

• SOURCE_FORMAT: o formato da origem de dados externa. Por exemplo, CSV.
• REGION: a região que contém a ligação, por exemplo, us.
• CONNECTION_ID: o nome da associação, por exemplo, myconnection.
• PARTITIONING_MODE: o modo de partição do Hive. Use um dos seguintes valores:
  • AUTO: detetar automaticamente os nomes e os tipos das chaves.
  • STRINGS: converta automaticamente os nomes das chaves em strings.
  • CUSTOM: codifique o esquema de chaves no prefixo do URI de origem.
• URI_SHARED_PREFIX: o prefixo do URI de origem.

• BOOLEAN: especifica se é necessário um filtro de predicado no momento da consulta. Esta flag é opcional. O valor predefinido é false.

• CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente. Só precisa de incluir esta flag se também planear usar a flag --max_staleness no comando bq mk subsequente para ativar o armazenamento em cache de metadados. Para mais informações sobre considerações relativas ao armazenamento em cache de metadados, consulte o artigo Armazenamento em cache de metadados para desempenho.

  Defina como AUTOMATIC para que a cache de metadados seja atualizada num intervalo definido pelo sistema, normalmente entre 30 e 60 minutos.

  Defina como MANUAL se quiser atualizar a cache de metadados de acordo com uma programação que determinar. Neste caso, pode chamar o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar a cache. Tem de definir CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor superior a 0.

• URIS: o caminho para a pasta do Amazon S3, usando o formato de carateres universais.

• DEFINITION_FILE: o caminho para o ficheiro de definição da tabela no seu computador local.

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

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

Depois de criar o ficheiro de definição da 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 o seguinte:

• STALENESS_INTERVAL: especifica se as operações na tabela do BigLake usam metadados em cache e qual a atualização dos metadados em cache necessária para que a operação os use. Para mais informações sobre considerações relativas à colocação em cache de metadados, consulte o artigo Colocação em cache de metadados para desempenho.

  Para desativar a colocação em cache de metadados, especifique 0. Esta é a predefiniçã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 desatualização de 4 horas. Com este valor, as operações na tabela usam metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem mais antigos, a operação obtém metadados do Amazon S3.

• DEFINITION_FILE: o caminho para o ficheiro de definição da tabela.

• DATASET_NAME: o nome do conjunto de dados que contém a tabela.

• TABLE_NAME: o nome da tabela que está a criar.

• SCHEMA: especifica um caminho para um ficheiro de esquema JSON, ou especifica o esquema no formulário field:data_type,field:data_type,.... Para usar a deteção automática do esquema, omita este argumento.

Exemplos

O exemplo seguinte usa o modo de partição do Hive para dados do Amazon S3:AUTO

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

O exemplo seguinte usa o modo de partição do Hive para dados do Amazon S3:STRING

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 a partição do Hive através da API BigQuery, inclua o objeto hivePartitioningOptions no objeto ExternalDataConfiguration quando criar o ficheiro de definição de tabelas. Para criar uma tabela do BigLake, também tem de especificar um valor para o campo connectionId.

Se definir o campo hivePartitioningOptions.mode como CUSTOM, tem de codificar o esquema da chave de partição no campo hivePartitioningOptions.sourceUriPrefix da seguinte forma: s3://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Para aplicar a utilização de um filtro de predicado no momento da consulta, defina o campo hivePartitioningOptions.requirePartitionFilter como true.

Tabelas do Delta Lake

O Delta Lake é um formato de tabela de código aberto que suporta tabelas de dados à escala de petabytes. As tabelas Delta Lake podem ser consultadas como tabelas temporárias e permanentes e são suportadas como uma tabela do BigLake.

Sincronização de esquemas

O Delta Lake mantém um esquema canónico como parte dos respetivos metadados. Não pode atualizar um esquema através de um ficheiro de metadados JSON. Para atualizar o esquema:

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

   bq update --autodetect_schema
   PROJECT_ID:DATASET.TABLE
   

   Substitua o seguinte:

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

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

   • TABLE: a tabela que quer atualizar

Conversão de tipo

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

Tipo de Delta Lake	Tipo do BigQuery
boolean	BOOL
byte	INT64
int	INT64
long	INT64
float	FLOAT64
double	FLOAT64
Decimal(P/S)	NUMERIC ou BIG_NUMERIC, consoante a 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 aplicam-se às tabelas Delta Lake:

• Aplicam-se limitações de tabelas externas às tabelas Delta Lake.

• As tabelas Delta Lake só são suportadas no BigQuery Omni e têm as limitações associadas.

• Não pode atualizar uma tabela com um novo ficheiro de metadados JSON. Tem de usar uma operação de atualização da tabela de esquemas de deteção automática. Consulte a secção Sincronização do esquema para mais informações.

• As funcionalidades de segurança do BigLake só protegem as tabelas do Delta Lake quando acedidas através dos serviços do BigQuery.

Crie uma tabela Delta Lake

O exemplo seguinte cria uma tabela externa através da declaraçã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 o seguinte:

• table_name: o nome da tabela.

• connection_name: o nome da associação. A associação tem de identificar uma origem Amazon S3 ou Blob Storage.

• parent_directory: o URI do diretório principal.

Transferência entre nuvens com o Delta Lake

O exemplo seguinte usa a declaração LOAD DATA para carregar dados para a tabela adequada:

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

Para ver mais exemplos de transferências de dados entre nuvens, consulte o artigo Carregue dados com operações entre nuvens.

Consultar tabelas do BigLake

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

Veja os metadados dos recursos

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Pode ver os metadados dos recursos com as visualizações INFORMATION_SCHEMA. Quando consulta as vistas JOBS_BY_*, JOBS_TIMELINE_BY_* e RESERVATION*, tem de especificar a localização de processamento da consulta que está localizada na mesma região que a tabela. Para informações sobre as localizações do BigQuery Omni, consulte o artigo Localizações. Para todas as outras tabelas do sistema, especificar a localização da tarefa de consulta é opcional.

Para informações sobre as tabelas do sistema suportadas pelo BigQuery Omni, consulte as Limitações.

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

Consola

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. Se o separador Editor não estiver visível, clique em Redigir nova consulta.

3. Clique em Mais > Definições de consulta. É apresentada a caixa de diálogo Definições de consulta.

4. Na caixa de diálogo Definições de consulta, em Definições adicionais > Localização dos dados, selecione a região do BigQuery que está localizada na mesma região do BigQuery Omni. Por exemplo, se a sua região do BigQuery Omni for aws-us-east-1, especifique us-east4.

5. Selecione os restantes campos e clique em Guardar.

bq

Use a flag --location para definir a localização de processamento da tarefa para a região do BigQuery que está localizada na mesma região que o BigQuery Omni. Por exemplo, se a sua 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 estiver a executar tarefas programaticamente, defina o argumento de localização para a região do BigQuery que está localizada na mesma região que a região do BigQuery Omni. Por exemplo, se a sua região do BigQuery Omni for aws-us-east-1, especifique us-east4.

O exemplo seguinte apresenta as tarefas de atualização de metadados nas últimas seis horas:

SELECT
 *
FROM
 `region-REGION_NAME`.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;

Substitua REGION_NAME pela sua região.

VPC Service Controls

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

Para saber mais acerca do VPC Service Controls, consulte o artigo Vista geral do VPC Service Controls.

Autorização necessária

Certifique-se de que tem as autorizações necessárias para configurar perímetros de serviço. Para ver uma lista das funções da IAM necessárias para configurar os VPC Service Controls, consulte o artigo Controlo de acesso com a IAM na documentação dos VPC Service Controls.

Configure os VPC Service Controls através da Google Cloud consola

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

   Aceda aos VPC Service Controls

2. Para configurar os VPC Service Controls para o BigQuery Omni, siga os passos no guia Crie um perímetro de serviço e, quando estiver no painel Regras de saída, siga estes passos:

   1. No painel Regras de saída, clique em Adicionar regra.

   2. Na secção A partir dos 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, para Nome do recurso externo, introduza 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 contentor do Amazon S3.

      • Para o armazenamento de blobs do Azure: azure://myaccount.blob.core.windows.net/CONTAINER_NAME

        Substitua CONTAINER NAME pelo nome do contentor do Blob Storage.

      Para ver uma lista dos atributos das regras de saída, consulte a referência das regras de saída.

   6. Selecione os métodos que quer permitir nos seus recursos externos:

      1. Se quiser permitir todos os métodos, selecione Todos os métodos na lista Métodos.
      2. Se quiser permitir métodos específicos, selecione Método selecionado, clique em Selecionar métodos e, de seguida, selecione os métodos que quer permitir nos seus recursos externos.

   7. Clique em Criar perímetro.

Configure os VPC Service Controls através da CLI gcloud

Para configurar os VPC Service Controls através da CLI gcloud, siga estes passos:

1. Defina a política de acesso predefinida.
2. Crie o ficheiro de entrada da política de saída.
3. Adicione a política de saída.

Defina a política de acesso predefinida

Uma política de acesso é um contentor ao nível da organização para níveis de acesso e perímetros de serviço. Para ver informações sobre como definir uma política de acesso predefinida ou obter o nome de uma política de acesso, consulte o artigo Gerir uma política de acesso.

Crie o ficheiro de entrada da política de saída

Um bloco de regras de saída define o acesso permitido a partir de um perímetro a recursos fora desse perímetro. Para recursos externos, a propriedade externalResources define os caminhos de recursos externos com acesso permitido a partir do seu perímetro dos VPC Service Controls.

As regras de saída podem ser configuradas através de um ficheiro JSON ou um ficheiro YAML. O exemplo seguinte 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: indica as operações de serviço permitidas em Google Cloud recursos em projetos especificados fora do perímetro.

• operations: lista os serviços e as ações ou os métodos acessíveis aos quais um cliente que satisfaça as condições de bloqueio from tem permissão para aceder.

• serviceName: defina bigquery.googleapis.com para o BigQuery Omni.

• methodSelectors: lista os métodos aos quais um cliente que satisfaça as from condições pode aceder. Para ver os métodos e as autorizações restritivas para serviços, consulte o artigo Restrições de métodos de serviços suportados.

• method : um método de serviço válido ou \"*\" para permitir todos os métodos serviceName.

• permission: uma autorizaçã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 requerem esta autorização.

• externalResources: lista os recursos externos aos quais os clientes dentro de um perímetro podem aceder. Substitua EXTERNAL_RESOURCE_PATH por um contentor do Amazon S3 válido, como s3://bucket_name, ou um caminho do contentor de armazenamento de blobs, como azure://myaccount.blob.core.windows.net/container_name.

• egressFrom: lista as operações de serviço permitidas em Google Cloud recursos em projetos especificados dentro do perímetro.

• identityType ou identities: define os tipos de identidade que podem aceder aos recursos especificados fora do perímetro. Substitua IDENTITY_TYPE por um dos seguintes valores válidos:

  • ANY_IDENTITY: para permitir todas as identidades.
  • ANY_USER_ACCOUNT: para permitir todos os utilizadores.
  • ANY_SERVICE_ACCOUNT: para permitir todas as contas de serviço

• identities: indica as contas de serviço que podem aceder aos recursos especificados fora do perímetro.

• serviceAccount (opcional): substitua SERVICE_ACCOUNT pela conta de serviço que pode aceder aos recursos especificados fora do perímetro.

Exemplos

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

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

O exemplo seguinte permite operações de saída para um contentor 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 acerca das políticas de saída, consulte a Referência das regras de saída.

Adicione a política de saída

Para adicionar a política de saída quando cria um novo perímetro de serviço, use o comando gcloud access-context-manager perimeters create. Por exemplo, o seguinte comando cria um novo perímetro denominado omniPerimeter que inclui o projeto com o número do projeto 12345, restringe a API BigQuery e adiciona uma política de saída definida no ficheiro 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 existente, use o comando gcloud access-context-manager perimeters update. Por exemplo, o comando seguinte adiciona uma política de saída definida no ficheiro egress.yaml a um perímetro de serviço existente denominado omniPerimeter:

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

Valide o seu perímetro

Para validar 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 seguinte descreve o perímetro omniPerimeter:

gcloud access-context-manager perimeters describe omniPerimeter

Para mais informações, consulte o artigo Faça a gestão dos perímetros de serviço.

Permita o acesso VPC do BigQuery Omni ao Amazon S3

Como administrador do BigQuery, pode criar uma política de contentor do S3 para conceder acesso do BigQuery Omni aos seus recursos do Amazon S3. Isto garante que apenas as VPCs do BigQuery Omni autorizadas podem interagir com o seu Amazon S3, o que melhora a segurança dos seus dados.

Aplique uma política de contentor do S3 para a VPC do BigQuery Omni

Para aplicar uma política de contentor do S3, use a CLI do AWS ou o Terraform:

AWS CLI

Execute o seguinte comando para aplicar uma política de contentor do S3 que inclua uma condição com 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 o seguinte:

• BUCKET_NAME: o contentor do Amazon S3 ao qual quer que o BigQuery aceda.
• VPC_ID: o ID da VPC do BigQuery Omni da região do BigQuery Omni colocada juntamente com o contentor do Amazon S3. Pode encontrar estas informações na tabela desta página.

Terraform

Adicione o seguinte ao ficheiro 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 o seguinte:

• BUCKET_NAME: o contentor do Amazon S3 ao qual quer que o BigQuery aceda.
• VPC_ID: o ID da VPC do BigQuery Omni da região do BigQuery Omni colocada juntamente com o contentor do Amazon S3.

IDs de recursos da VPC do 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 ver uma lista completa das limitações aplicáveis às tabelas BigLake com base no Amazon S3 e no armazenamento de blobs, consulte o artigo Limitações.

O que se segue?

• Saiba mais acerca do BigQuery Omni.
• Use o laboratório do BigQuery Omni com a AWS.
• Saiba mais sobre as tabelas do BigLake.
• Saiba como exportar resultados de consultas para o Amazon S3.
• Saiba como criar vistas materializadas sobre tabelas com a cache de metadados do Amazon Simple Storage Service (Amazon S3) ativada.
• Saiba como disponibilizar os dados do Amazon S3 numa vista materializada localmente para junções através da criação de uma réplica da vista materializada.