Crie tabelas externas do BigLake para o Cloud Storage

Este documento descreve como criar uma tabela do BigLake do Cloud Storage. Uma tabela do BigLake permite-lhe usar a delegação de acesso para consultar dados estruturados no Cloud Storage. A delegação de acesso desassocia o acesso à tabela do BigLake do acesso ao repositório de dados subjacente.

Antes de começar

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the BigQuery Connection API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    Se quiser ler tabelas do BigLake a partir de motores de código aberto, como o Apache Spark, tem de ativar a API BigQuery Storage Read.

  4. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

  5. Certifique-se de que tem um conjunto de dados do BigQuery.

  6. Certifique-se de que a versão do Google Cloud SDK é a 366.0.0 ou posterior:

    gcloud version

    Se necessário, atualize o SDK do Google Cloud.

    1. Opcional: para o Terraform, é necessária a versão 4.25.0 ou posterior.terraform-provider-google As versões do terraform-provider-google estão listadas no GitHub. Pode transferir a versão mais recente do Terraform a partir das transferências do HashiCorp Terraform.

  7. Crie uma associação de recursos da nuvem ou configure uma associação predefinida à sua origem de dados externa. As associações requerem funções e autorizações adicionais. Para mais informações, consulte o artigo Crie uma ligação de recursos do Google Cloud e a vista geral da ligação predefinida.

    8. Funções necessárias

    Para criar uma tabela do BigLake, precisa das seguintes autorizações de gestão de identidade e acesso (IAM) do BigQuery:

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

    A função predefinida de administrador do BigQuery (roles/bigquery.admin) do Identity and Access Management inclui estas autorizações.

    Se não for um principal nesta função, peça ao seu administrador para lhe conceder acesso ou criar a tabela do BigLake por si.

    Para mais informações sobre as funções e as autorizações de gestão de identidades e acessos no BigQuery, consulte o artigo Funções e autorizações predefinidas.

    Consideração da localização

    Quando usa o Cloud Storage para armazenar ficheiros de dados, pode melhorar o desempenho usando contentores de região única ou dupla região do Cloud Storage em vez de contentores multirregionais.

    Crie tabelas BigLake em dados não particionados

    Se já criou tabelas no BigQuery, o processo de criação de uma tabela do BigLake é semelhante. A sua tabela pode usar qualquer formato de ficheiro suportado pelo BigLake. Para mais informações, consulte Limitações.

    Antes de criar uma tabela do BigLake, tem de ter um conjunto de dados e uma ligação de recursos da nuvem que possa aceder ao Cloud Storage.

    Para criar uma tabela do BigLake, 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. Expanda a opção Ações e clique em Criar tabela.

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

      1. Em Criar tabela a partir de, selecione Google Cloud Storage

      2. Para Selecionar ficheiro do contentor do GCS ou usar um padrão de URI, procure selecione um contentor e um ficheiro a usar ou escreva o caminho no formato gs://bucket_name/[folder_name/]file_name.

        Não pode especificar vários URIs na consola Google Cloud , mas pode selecionar vários ficheiros especificando um caráter universal (*). Por exemplo, gs://mybucket/file_name*. Para mais informações, consulte o artigo Suporte de carateres universais para URIs do Cloud Storage.

        O contentor do Cloud Storage tem de estar na mesma localização que o conjunto de dados que contém a tabela que está a criar.

      3. Em Formato de ficheiro, selecione o formato que corresponde ao seu ficheiro.

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

      1. Para Projeto, escolha o projeto no qual criar a tabela.

      2. Para Conjunto de dados, escolha o conjunto de dados no qual criar a tabela.

      3. Em Tabela, introduza o nome da tabela que está a criar.

      4. Para Tipo de tabela, selecione Tabela externa.

      5. Selecione Criar uma tabela do BigLake com uma ligação de recursos da nuvem.

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

    Depois de criar a tabela permanente, pode executar uma consulta na tabela como se fosse uma tabela nativa do BigQuery. Depois de a consulta ser concluída, pode exportar os resultados como ficheiros CSV ou JSON, guardar os resultados como uma tabela ou guardar os resultados no Google Sheets.

    SQL

    Use a CREATE EXTERNAL TABLE declaração DDL. Pode especificar o esquema explicitamente ou usar a deteção automática de esquemas para inferir o esquema dos dados externos.

    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 CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID` | DEFAULT}
  OPTIONS (
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'[,...]],
    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
      • REGION: a região que contém a ligação, por exemplo, us
      • CONNECTION_ID: o ID de associação, por exemplo, myconnection

        Quando vê os detalhes da associação na Google Cloud consola, o ID da associação é o valor na última secção do ID da associação totalmente qualificado que é apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

        Para usar uma ligação predefinida, especifique DEFAULT em vez da string de ligação que contém PROJECT_ID.REGION.CONNECTION_ID.

      • TABLE_FORMAT: o formato da tabela que quer criar, por exemplo, PARQUET

        Para mais informações sobre os formatos suportados, consulte as Limitações.

      • BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém os dados da tabela externa, no formato ['gs://bucket_name/[folder_name/]file_name'].

        Pode selecionar vários ficheiros do contentor especificando um caráter universal de asterisco (*) no caminho. Por exemplo, ['gs://mybucket/file_name*']. Para mais informações, consulte o artigo Suporte de carateres universais para URIs do Cloud Storage.

        Pode especificar vários contentores para a opção uris fornecendo vários caminhos.

        Os exemplos seguintes mostram valores uris válidos:

        • ['gs://bucket/path1/myfile.csv']
        • ['gs://bucket/path1/*.csv']
        • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

        Quando especifica valores uris que segmentam vários ficheiros, todos esses ficheiros têm de partilhar um esquema compatível.

        Para mais informações sobre a utilização de URIs do Cloud Storage no BigQuery, consulte o artigo Caminho de recurso do Cloud Storage.

      • 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 relativas ao armazenamento em cache de metadados, consulte o artigo Armazenamento 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 os metadados do Cloud Storage.

      • CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente. Para mais informações sobre considerações de colocação em cache de metadados, consulte Colocação 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.

    bq

    Opção 1: ficheiro de definição da tabela

    Use o comando bq mkdef para criar um ficheiro de definição de tabela e, em seguida, transmita o caminho para o comando bq mk da seguinte forma:

    bq mkdef \
    --connection_id=CONNECTION_ID \
    --source_format=SOURCE_FORMAT \
  BUCKET_PATH > DEFINITION_FILE

bq mk --table \
    --external_table_definition=DEFINITION_FILE \
    --max_staleness=STALENESS_INTERVAL \
    PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \
    SCHEMA

    Substitua o seguinte:

    • CONNECTION_ID: o ID da associação, por exemplo, myconnection

      Quando vê os detalhes da associação na Google Cloud consola, o ID da associação é o valor na última secção do ID da associação totalmente qualificado que é apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

      Para usar uma ligação predefinida, especifique DEFAULT em vez da string de ligação que contém PROJECT_ID.REGION.CONNECTION_ID.

    • SOURCE_FORMAT: o formato da origem de dados externa. Por exemplo, PARQUET.

    • BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém os dados da tabela, no formato gs://bucket_name/[folder_name/]file_pattern.

      Pode selecionar vários ficheiros do contentor especificando um caráter universal (*) no file_pattern. Por exemplo, gs://mybucket/file00*.parquet. Para mais informações, consulte o artigo Suporte de carateres universais para URIs do Cloud Storage.

      Pode especificar vários contentores para a opção uris fornecendo vários caminhos.

      Os exemplos seguintes mostram valores uris válidos:

      • gs://bucket/path1/myfile.csv
      • gs://bucket/path1/*.parquet
      • gs://bucket/path1/file1*, gs://bucket1/path1/*

      Quando especifica valores uris que segmentam vários ficheiros, todos esses ficheiros têm de partilhar um esquema compatível.

      Para mais informações sobre a utilização de URIs do Cloud Storage no BigQuery, consulte o caminho de recurso do Cloud Storage.

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

    • STALENESS_INTERVAL: especifica se as operações contra a tabela do BigLake usam metadados em cache e qual a antiguidade máxima dos metadados em cache para que a operação os use. Para mais informações sobre considerações relativas ao armazenamento em cache de metadados, consulte o artigo Armazenamento 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 intervalo entre 30 minutos e 7 dias, usando o formato Y-M D H:M:S descrito na documentação do tipo de dados INTERVAL. Por exemplo, especifique 0-0 0 4:0:0 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 os metadados do Cloud Storage.

    • DATASET: o nome do conjunto de dados do BigQuery no qual quer criar uma tabela. Por exemplo, mydataset

    • EXTERNAL_TABLE_NAME: o nome da tabela que quer criar, por exemplo, mytable

    • SCHEMA: o esquema da tabela do BigLake

    Exemplo:

    bq mkdef
    --connection_id=myconnection
    --metadata_cache_mode=CACHE_MODE
    --source_format=CSV 'gs://mybucket/*.csv' > mytable_def

bq mk
    --table
    --external_table_definition=mytable_def='gs://mybucket/*.csv'
    --max_staleness=0-0 0 4:0:0
    myproject:mydataset.mybiglaketable
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

    Para usar a deteção automática de esquemas, defina a flag --autodetect=true no comando mkdef e omita o esquema:

    bq mkdef \
    --connection_id=myconnection \
    --metadata_cache_mode=CACHE_MODE \
    --source_format=CSV --autodetect=true \
    gs://mybucket/*.csv > mytable_def

bq mk \
    --table \
    --external_table_definition=mytable_def=gs://mybucket/*.csv \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable

    Opção 2: definição de tabela inline

    Em vez de criar um ficheiro de definição de tabela, pode transmitir a definição de tabela diretamente para o comando bq mk. Use o decorador @connection para especificar a ligação a usar no final do indicador --external_table_definition.

    bq mk --table \
  --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

    Substitua o seguinte:

    • SOURCE_FORMAT: o formato da origem de dados externa

      Por exemplo, CSV.

    • BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém os dados da tabela, no formato gs://bucket_name/[folder_name/]file_pattern.

      Pode selecionar vários ficheiros do contentor especificando um caráter universal (*) no file_pattern. Por exemplo, gs://mybucket/file00*.parquet. Para mais informações, consulte o artigo Suporte de carateres universais para URIs do Cloud Storage.

      Pode especificar vários contentores para a opção uris fornecendo vários caminhos.

      Os exemplos seguintes mostram valores uris válidos:

      • gs://bucket/path1/myfile.csv
      • gs://bucket/path1/*.parquet
      • gs://bucket/path1/file1*, gs://bucket1/path1/*

      Quando especifica valores uris que segmentam vários ficheiros, todos esses ficheiros têm de partilhar um esquema compatível.

      Para mais informações sobre a utilização de URIs do Cloud Storage no BigQuery, consulte o caminho de recurso do Cloud Storage.

    • PROJECT_ID: o nome do projeto no qual quer criar a tabela, por exemplo, myproject

    • REGION: a região que contém a ligação, us

    • CONNECTION_ID: o ID da associação, por exemplo, myconnection

      Quando vê os detalhes da associação na Google Cloud consola, o ID da associação é o valor na última secção do ID da associação totalmente qualificado que é apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

      Para usar uma ligação predefinida, especifique DEFAULT em vez da string de ligação que contém PROJECT_ID.REGION.CONNECTION_ID.

    • DATASET_NAME: o nome do conjunto de dados onde quer criar a tabela do BigLake

    • TABLE_NAME: o nome da tabela do BigLake

    • SCHEMA: o esquema da tabela do BigLake

    Exemplo:

    bq mk --table \
    --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable \
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

    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 connectionId para identificar a ligação a usar para se ligar ao Cloud Storage.

    Terraform

    Este exemplo cria uma tabela do BigLake em dados não particionados.

    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.

    # This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This queries the provider for project information.
data "google_project" "project" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.project.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding.
# This lets IAM permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with
# default expiration times for partitions and tables, a
# description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}


# This creates a BigQuery Table with automatic metadata caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema = jsonencode([
    { "name" : "country", "type" : "STRING" },
    { "name" : "product", "type" : "STRING" },
    { "name" : "price", "type" : "INT64" }
  ])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/data/*"]
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [time_sleep.default]
}

    Para aplicar a configuração do Terraform num Google Cloud projeto, conclua os passos nas secções seguintes.

    Prepare o Cloud Shell

    1. Inicie o Cloud Shell.

    2. Defina o Google Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.

      Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.

      export GOOGLE_CLOUD_PROJECT=PROJECT_ID

      As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.

    Prepare o diretório

    Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).

    1. No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o ficheiro é denominado main.tf. 
      mkdir DIRECTORY && cd DIRECTORY && touch main.tf

    2. Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.

      Copie o exemplo de código para o ficheiro main.tf criado recentemente.

      Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.

    3. Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
    4. Guarde as alterações.
    5. Inicialize o Terraform. Só tem de fazer isto uma vez por diretório. 
      terraform init

      Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção -upgrade: 

      terraform init -upgrade

    Aplique as alterações

    1. Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas: 
      terraform plan

      Faça as correções necessárias à configuração.

    2. Aplique a configuração do Terraform executando o seguinte comando e introduzindo yes no comando: 
      terraform apply

      Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).

    3. Abra o seu Google Cloud projeto para ver os resultados. Na Google Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.

    O BigLake suporta a deteção automática de esquemas. No entanto, se não tiver fornecido um esquema e não tiver sido concedido acesso à conta de serviço nos passos anteriores, estes passos falham com uma mensagem de acesso negado se tentar detetar automaticamente o esquema.

    Crie tabelas BigLake em dados particionados do Apache Hive

    Pode criar uma tabela BigLake para dados particionados do Hive no Cloud Storage. 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 no Cloud Storage, 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 Google Cloud Storage.

      2. Indique o caminho para a pasta através de caracteres universais. Por exemplo, my_bucket/my_files*. 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, gs://my_bucket/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 Forneça um 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, selecione Tabela externa.
      5. Selecione a caixa de verificação Criar uma tabela do BigLake com uma ligação de recursos da nuvem.
      6. Em ID da associação, selecione a associação que criou anteriormente.

    6. Na secção Esquema, ative a deteção automática de esquemas selecionando a opção Deteção automática.

    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` | DEFAULT}
OPTIONS (
  hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
  uris=['FILE_PATH'],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE',
  format ="TABLE_FORMAT"
);

      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 ID de associação, por exemplo, myconnection

        Quando vê os detalhes da associação na consola Google Cloud , o ID da associação é o valor na última secção do ID da associação totalmente qualificado que é apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

        Para usar uma ligação predefinida, especifique DEFAULT em vez da string de ligação que contém PROJECT_ID.REGION.CONNECTION_ID.

      • HIVE_PARTITION_URI_PREFIX: particionamento de colmeias prefixo do URI, por exemplo, gs://mybucket/
      • FILE_PATH: caminho para a origem de dados da tabela externa que quer criar, por exemplo, gs://mybucket/*.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 relativas ao armazenamento em cache de metadados, consulte o artigo Armazenamento 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 os metadados do Cloud Storage.

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

      • TABLE_FORMAT: o formato da tabela que quer criar, por exemplo, PARQUET

    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 onde:

    • O esquema é detetado automaticamente.
    • O intervalo de desatualização da cache de metadados para a tabela é de 1 dia.
    • A cache de metadados é atualizada automaticamente.
    CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

    O exemplo seguinte cria uma tabela do BigLake sobre dados particionados onde:

    • O esquema está especificado.
    • O intervalo de desatualização da cache de metadados para a tabela é de 8 horas.
    • A cache de metadados tem de ser atualizada manualmente.
    CREATE EXTERNAL TABLE `my_dataset.my_table`
(
  ProductId INTEGER,
  ProductName STRING,
  ProductType STRING
)
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 8 HOUR,
  metadata_cache_mode = 'MANUAL'
);

    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=GCS_URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 GCS_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 ID da associação, por exemplo, myconnection.

      Quando vê os detalhes da associação na Google Cloud consola, o ID da associação é o valor na última secção do ID da associação totalmente qualificado que é apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

      Para usar uma ligação predefinida, especifique DEFAULT em vez da string de ligação que contém PROJECT_ID.REGION.CONNECTION_ID.

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

    • GCS_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ó tem de incluir esta sinalização se também planear usar a sinalização --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.

    • GCS_URIS: o caminho para a pasta do Cloud Storage, 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=GCS_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 --external_table_definition=DEFINITION_FILE \
--max_staleness=STALENESS_INTERVAL \
DATASET_NAME.TABLE_NAME \
SCHEMA

    Substitua o seguinte:

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

    • STALENESS_INTERVAL: especifica se as operações contra a tabela do BigLake usam metadados em cache e qual a antiguidade máxima dos metadados em cache para que a operação os use. Se incluir esta flag, também tem de ter especificado um valor para a flag --metadata_cache_mode no comando bq mkdef anterior. 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 de intervalo entre 30 minutos e 7 dias, usando o formato Y-M D H:M:S descrito na documentação do INTERVAL tipo de dados. Por exemplo, especifique 0-0 0 4:0:0 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 os metadados do Cloud Storage.

    • 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 AUTO Hive e também define a cache de metadados com um intervalo de desatualização de 12 horas e para ser atualizada automaticamente:

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

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

    O exemplo seguinte usa o modo de partição do Hive STRING:

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

bq mk --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 CUSTOM:

    bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=CUSTOM \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
  gs://myBucket/myTable/* > mytable_def

bq mk --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: gs://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.

    Terraform

    Este exemplo cria uma tabela do BigLake em dados particionados.

    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.

    
# This creates a bucket in the US region named "my-bucket" with a pseudorandom
# suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

resource "google_storage_bucket_object" "default" {
  # This creates a fake message to create partition locations on the table.
  # Otherwise, the table deployment fails.
  name    = "publish/dt=2000-01-01/hr=00/min=00/fake_message.json"
  content = "{\"column1\": \"XXX\"}"
  bucket  = google_storage_bucket.default.name
}

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding. This lets IAM
# permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with default expiration times for
# partitions and tables, a description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery table with partitioning and automatic metadata
# caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema     = jsonencode([{ "name" : "column1", "type" : "STRING", "mode" : "NULLABLE" }])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/publish/*"]
    # This configures Hive partitioning for the BigQuery table,
    # partitioning the data by date and time.
    hive_partitioning_options {
      mode                     = "CUSTOM"
      source_uri_prefix        = "gs://${google_storage_bucket.default.name}/publish/{dt:STRING}/{hr:STRING}/{min:STRING}"
      require_partition_filter = false
    }
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }


  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [
    time_sleep.default,
    google_storage_bucket_object.default
  ]
}

    Para aplicar a configuração do Terraform num Google Cloud projeto, conclua os passos nas secções seguintes.

    Prepare o Cloud Shell

    1. Inicie o Cloud Shell.

    2. Defina o Google Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.

      Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.

      export GOOGLE_CLOUD_PROJECT=PROJECT_ID

      As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.

    Prepare o diretório

    Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).

    1. No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o ficheiro é denominado main.tf. 
      mkdir DIRECTORY && cd DIRECTORY && touch main.tf

    2. Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.

      Copie o exemplo de código para o ficheiro main.tf criado recentemente.

      Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.

    3. Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
    4. Guarde as alterações.
    5. Inicialize o Terraform. Só tem de fazer isto uma vez por diretório. 
      terraform init

      Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção -upgrade: 

      terraform init -upgrade

    Aplique as alterações

    1. Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas: 
      terraform plan

      Faça as correções necessárias à configuração.

    2. Aplique a configuração do Terraform executando o seguinte comando e introduzindo yes no comando: 
      terraform apply

      Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).

    3. Abra o seu Google Cloud projeto para ver os resultados. Na Google Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.

    Configure políticas de controlo de acesso

    Pode usar vários métodos para controlar o acesso a tabelas do BigLake:

    Por exemplo, suponhamos que quer limitar o acesso a linhas para a tabela mytable no conjunto de dados mydataset:

    +---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
| JP      | tablet  |   300 |
| UK      | laptop  |   200 |
+---------+---------+-------+

    Pode criar um filtro ao nível da linha para a Kim (kim@example.com) que restringe o respetivo acesso a linhas em que country é igual a US.

    CREATE ROW ACCESS POLICY only_us_filter
ON mydataset.mytable
GRANT TO ('user:kim@example.com')
FILTER USING (country = 'US');

    Em seguida, a Kim executa a seguinte consulta:

    SELECT * FROM projectid.mydataset.mytable;

    A saída mostra apenas as linhas em que country é igual a US:

    +---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
+---------+---------+-------+

    Consultar tabelas do BigLake

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

    Atualize tabelas do BigLake

    Pode atualizar as tabelas do BigLake, se necessário, por exemplo, para alterar a colocação em cache de metadados. Para obter detalhes da tabela, como o formato de origem e o URI de origem, consulte o artigo Obtenha informações da tabela.

    Também pode usar este mesmo procedimento para atualizar tabelas externas baseadas no Cloud Storage para tabelas BigLake associando a tabela externa a uma ligação. Para mais informações, consulte o artigo Atualize tabelas externas para tabelas BigLake.

    Para atualizar uma tabela do BigLake, selecione uma das seguintes opções:

    SQL

    Use a declaração DDL CREATE OR REPLACE EXTERNAL TABLE para atualizar uma tabela:

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

      Aceda ao BigQuery

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

      CREATE OR REPLACE EXTERNAL TABLE
  `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION {`REGION.CONNECTION_ID` | DEFAULT}
  OPTIONS(
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );

      Substitua o seguinte:

      • PROJECT_ID: o nome do projeto que contém a tabela
      • DATASET: o nome do conjunto de dados que contém a tabela
      • EXTERNAL_TABLE_NAME: o nome da tabela
      • REGION: a região que contém a ligação
      • CONNECTION_ID: o nome da ligação a usar

        Para usar uma associação predefinida, especifique DEFAULT em vez da string de associação que contém REGION.CONNECTION_ID.

      • TABLE_FORMAT: o formato usado pela tabela

        Não pode alterar esta opção quando atualiza a tabela.

      • BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém os dados da tabela externa, no formato ['gs://bucket_name/[folder_name/]file_name'].

        Pode selecionar vários ficheiros do contentor especificando um caráter universal de asterisco (*) no caminho. Por exemplo, ['gs://mybucket/file_name*']. Para mais informações, consulte o artigo Suporte de carateres universais para URIs do Cloud Storage.

        Pode especificar vários contentores para a opção uris fornecendo vários caminhos.

        Os exemplos seguintes mostram valores uris válidos:

        • ['gs://bucket/path1/myfile.csv']
        • ['gs://bucket/path1/*.csv']
        • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

        Quando especifica valores uris que segmentam vários ficheiros, todos esses ficheiros têm de partilhar um esquema compatível.

        Para mais informações sobre a utilização de URIs do Cloud Storage no BigQuery, consulte o artigo Caminho de recurso do Cloud Storage.

      • STALENESS_INTERVAL: especifica se os metadados em cache são usados por operações na tabela e qual a atualidade dos metadados em cache para que a operação os use

        Para mais informações sobre considerações relativas ao armazenamento em cache de metadados, consulte o artigo Armazenamento 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 os metadados do Cloud Storage.

      • CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente

        Para mais informações sobre considerações de colocação em cache de metadados, consulte Colocação 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.

    bq

    Use os comandos bq mkdef e bq update para atualizar uma tabela:

    1. Gere uma definição de tabela externa, que descreve os aspetos da tabela a alterar:

      bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
--source_format=TABLE_FORMAT \
--metadata_cache_mode=CACHE_MODE \
"BUCKET_PATH" > /tmp/DEFINITION_FILE

      Substitua o seguinte:

      • PROJECT_ID: o nome do projeto que contém a associação
      • REGION: a região que contém a ligação
      • CONNECTION_ID: o nome da associação a usar
      • TABLE_FORMAT: o formato usado pela tabela. Não pode alterar esta opção quando atualiza a tabela.

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

        Defina 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 um horário 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.

      • BUCKET_PATH: o caminho para o contentor de armazenamento na nuvem que contém os dados da tabela externa, no formato gs://bucket_name/[folder_name/]file_name.

        Pode limitar os ficheiros selecionados do contentor especificando um caráter universal (*) no caminho. Por exemplo, gs://mybucket/file_name*. Para mais informações, consulte o artigo Suporte de carateres universais para URIs do Cloud Storage.

        Pode especificar vários contentores para a opção uris fornecendo vários caminhos.

        Os exemplos seguintes mostram valores uris válidos:

        • gs://bucket/path1/myfile.csv
        • gs://bucket/path1/*.csv
        • gs://bucket/path1/*,gs://bucket/path2/file00*

        Quando especifica valores uris que segmentam vários ficheiros, todos esses ficheiros têm de partilhar um esquema compatível.

        Para mais informações sobre a utilização de URIs do Cloud Storage no BigQuery, consulte o caminho de recurso do Cloud Storage.

      • DEFINITION_FILE: o nome do ficheiro de definição da tabela que está a criar.

    2. Atualize a tabela com a nova definição de tabela externa:

      bq update --max_staleness=STALENESS_INTERVAL \
--external_table_definition=/tmp/DEFINITION_FILE \
PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME

      Substitua o seguinte:

      • STALENESS_INTERVAL: especifica se as operações contra a tabela usam metadados em cache e qual a antiguidade máxima dos metadados em cache 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 de intervalo entre 30 minutos e 7 dias, usando o formato Y-M D H:M:S descrito na documentação do tipo de dados INTERVAL. Por exemplo, especifique 0-0 0 4:0:0 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 os metadados do Cloud Storage.

      • DEFINITION_FILE: o nome do ficheiro de definição da tabela que criou ou atualizou.

      • PROJECT_ID: o nome do projeto que contém a tabela

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

      • EXTERNAL_TABLE_NAME: o nome da tabela

    Exemplo

    O exemplo seguinte atualiza mytable para usar metadados em cache, desde que tenham sido atualizados nas últimas 4,5 horas, e também para atualizar automaticamente os metadados em cache:

    bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable

    Em que enable_metadata.json tem o seguinte conteúdo: json { "metadataCacheMode": "AUTOMATIC" }

    Registo de auditoria

    Para informações sobre a registo no BigQuery, consulte o artigo Introdução à monitorização do BigQuery. Para saber mais sobre como iniciar sessão Google Cloud, consulte o Cloud Logging.

    O que se segue?