Crie tabelas de objetos

Este documento descreve como aceder a dados não estruturados no BigQuery criando uma tabela de objetos.

Para criar uma tabela de objetos, tem de concluir as seguintes tarefas:

1. Crie uma associação para ler informações de objetos do Cloud Storage.
2. Conceda a função Storage Object Viewer (roles/storage.objectViewer) à conta de serviço associada à ligação.
3. Crie a tabela de objetos e associe-a à ligação através da declaração CREATE EXTERNAL TABLE.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

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 APIs

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

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 APIs

1. Certifique-se de que o administrador do BigQuery criou uma ligação e configurou o acesso ao Cloud Storage.

Funções necessárias

Para trabalhar com tabelas de objetos, os seus utilizadores precisam das seguintes autorizações do IAM com base na respetiva função na sua organização. Para mais informações sobre as funções de utilizador, consulte o artigo Modelo de segurança. Para mais informações sobre a atribuição de autorizações, consulte o artigo Ver as funções atribuíveis nos recursos.

• Administrador do lago de dados

  Para receber as autorizações de que precisa para estabelecer ligação ao Cloud Storage, peça ao seu administrador para lhe conceder a função de administrador da ligação do BigQuery (roles/bigquery.connectionAdmin) no projeto.

  Para receber as autorizações necessárias para criar e gerir contentores do Cloud Storage, peça ao seu administrador para lhe conceder a função de administrador do armazenamento (roles/storage.admin) no projeto.

  Esta função predefinida contém as autorizações necessárias para estabelecer ligação ao Cloud Storage e criar e gerir contentores do Cloud Storage. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

  Autorizações necessárias

  • bigquery.connections.create
  • bigquery.connections.get
  • bigquery.connections.list
  • bigquery.connections.update
  • bigquery.connections.use
  • bigquery.connections.delete
  • storage.bucket.*
  • storage.object.*

• Administrador do armazém de dados

  Para receber as autorizações necessárias para criar tabelas de objetos, peça ao seu administrador que lhe conceda as seguintes funções no projeto:

  • Função de editor de dados do BigQuery (roles/bigquery.dataEditor).
  • Função de administrador da associação do BigQuery (roles/bigquery.connectionAdmin).

  Esta função predefinida contém as autorizações necessárias para criar tabelas de objetos. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

  Autorizações necessárias

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

• Analista de dados

  Para receber as autorizações necessárias para consultar tabelas de objetos, peça ao administrador que lhe conceda as seguintes funções no projeto:

  • Função de visualizador de dados do BigQuery (roles/bigquery.dataViewer)
  • Função de utilizador de ligação do BigQuery (roles/bigquery.connectionUser)

  Esta função predefinida contém as autorizações necessárias para consultar tabelas de objetos. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

  Autorizações necessárias

  • bigquery.jobs.create
  • bigquery.tables.get
  • bigquery.tables.getData
  • bigquery.readsessions.create

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

Atenção: os analistas de dados não devem ter o seguinte:

• A capacidade de ler objetos diretamente do Cloud Storage (consulte a função do IAM Storage Object Viewer), que permite aos analistas de dados contornar os controlos de acesso definidos pelos administradores do data warehouse.

• A capacidade de associar tabelas a ligações (como o administrador de ligações do BigQuery).

  Caso contrário, os analistas de dados podem criar novas tabelas de objetos que não tenham controlos de acesso, contornando assim os controlos colocados pelos administradores do data warehouse.

Crie tabelas de objetos

Antes de criar uma tabela de objetos, tem de ter um conjunto de dados existente para a conter. Para mais informações, consulte o artigo Criar conjuntos de dados.

Para criar uma tabela de objetos:

SQL

Use a declaração CREATE EXTERNAL TABLE.

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_ID.TABLE_NAME`
   WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
   OPTIONS(
     object_metadata = 'SIMPLE',
     uris = ['BUCKET_PATH'[,...]],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE');

   Substitua o seguinte:

   • PROJECT_ID: o ID do seu projeto.
   • DATASET_ID: o ID do conjunto de dados que contém a tabela de objetos.
   • TABLE_NAME: o nome da tabela de objetos.
   • REGION: a região ou região múltipla que contém a ligação.
   • CONNECTION_ID: o ID da associação de recursos da nuvem a usar com esta tabela de objetos. A associação determina que conta de serviço é usada para ler dados do Cloud Storage.

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

   • BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém os objetos representados pela tabela de objetos, no formato ['gs://bucket_name/[folder_name/]*'].

     Pode usar um caráter universal de asterisco (*) em cada caminho para limitar os objetos incluídos na tabela de objetos. Por exemplo, se o contentor tiver vários tipos de dados não estruturados, pode criar a tabela de objetos apenas sobre objetos PDF especificando ['gs://bucket_name/*.pdf']. 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, por exemplo, ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].

     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 na tabela de objetos usam metadados em cache e a antiguidade máxima dos metadados em cache 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 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 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.

Exemplos

O exemplo seguinte cria uma tabela de objetos com um intervalo de desatualização da cache de metadados de 1 dia:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://mybucket/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

O exemplo seguinte cria uma tabela de objetos sobre os objetos em três contentores do Cloud Storage:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*']
);

O exemplo seguinte cria uma tabela de objetos apenas com os objetos PDF num contentor do Cloud Storage:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*.pdf']
);

bq

Use o comando bq mk.

bq mk --table \
--external_table_definition=[e-mail]_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

Substitua o seguinte:

• PROJECT_ID: o ID do seu projeto.
• DATASET_ID: o ID do conjunto de dados que contém a tabela de objetos.
• TABLE_NAME: o nome da tabela de objetos.
• REGION: a região ou região múltipla que contém a ligação.
• CONNECTION_ID: o ID da ligação de recursos da nuvem a usar com esta tabela externa. A associação determina que conta de serviço é usada para ler dados do Cloud Storage.

  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.

• BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém os objetos representados pela tabela de objetos, no formato gs://bucket_name/[folder_name/]*.

  Pode usar um caráter universal de asterisco (*) em cada caminho para limitar os objetos incluídos na tabela de objetos. Por exemplo, se o contentor tiver vários tipos de dados não estruturados, pode criar a tabela de objetos apenas sobre objetos PDF especificando gs://bucket_name/*.pdf. 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, por exemplo, gs://mybucket1/*,gs://mybucket2/folder5/*.

  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 na tabela de objetos usam metadados em cache e a antiguidade máxima dos metadados em cache 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 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.

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

Exemplos

O exemplo seguinte cria uma tabela de objetos com um intervalo de desatualização da cache de metadados de 1 dia:

bq mk --table \
--external_table_definition=gs://mybucket/*@us.my-connection \
--object_metadata=SIMPLE \
--max_staleness=0-0 1 0:0:0 \
--metadata_cache_mode=AUTOMATIC \
my_dataset.object_table

O exemplo seguinte cria uma tabela de objetos sobre os objetos em três contentores do Cloud Storage:

bq mk --table \
--external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

O exemplo seguinte cria uma tabela de objetos apenas com os objetos PDF num contentor do Cloud Storage:

bq mk --table \
--external_table_definition=gs://bucket1/*[e-mail]-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

API

Chame o método tables.insert. Inclua um objeto ExternalDataConfiguration com o campo objectMetadata definido como SIMPLE no recurso Table que transmite.

O exemplo seguinte mostra como chamar este método através de curl:

ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables

Terraform

Este exemplo cria uma tabela de objetos com a colocação em cache de metadados ativada com atualização manual.

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.

Os campos de chave a especificar para uma tabela de objetos são google_bigquery_table.external_data_configuration.object_metadata, google_bigquery_table.external_data_configuration.metadata_cache_mode, e google_bigquery_table.max_staleness. Para mais informações sobre cada recurso, consulte a documentação do Terraform BigQuery.

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

# This creates a connection in the US region named "my-connection-id".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection-id"
  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.project_id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This defines a Google BigQuery dataset.
resource "google_bigquery_dataset" "default" {
  dataset_id = "my_dataset_id"
}

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

# This defines a BigQuery object table with manual metadata caching.
resource "google_bigquery_table" "default" {
  deletion_protection = false
  table_id            = "my-table-id"
  dataset_id          = google_bigquery_dataset.default.dataset_id
  external_data_configuration {
    connection_id = google_bigquery_connection.default.name
    autodetect    = false
    # `object_metadata is` required for object tables. For more information, see
    # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#object_metadata
    object_metadata = "SIMPLE"
    # This defines the source for the prior object table.
    source_uris = [
      "gs://${google_storage_bucket.default.name}/*",
    ]

    metadata_cache_mode = "MANUAL"
  }

  # This ensures that the connection can access the bucket
  # before Terraform creates a table.
  depends_on = [
    google_project_iam_member.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.

Nota: normalmente, os exemplos do Terraform partem do princípio de que as APIs necessárias estão ativadas no seu Google Cloud projeto.

Consultar tabelas de objetos

Pode consultar uma tabela de objetos como qualquer outra tabela do BigQuery, por exemplo:

SELECT *
FROM mydataset.myobjecttable;

A consulta de uma tabela de objetos devolve metadados para os objetos subjacentes. Para mais informações, consulte o esquema da tabela de objetos.

O que se segue?

• Saiba como executar a inferência em tabelas de objetos de imagens.
• Saiba como analisar tabelas de objetos através de funções remotas.