Criar tabelas de objetos

Neste documento, descrevemos como tornar os dados não estruturados no Cloud Storage acessíveis no BigQuery criando uma tabela de objetos.

Para criar uma tabela de objetos, conclua as seguintes tarefas:

1. Crie um conjunto de dados para conter a tabela de objetos.
2. Crie uma conexão para ler informações do objeto do Cloud Storage.
3. Conceda o papel Leitor de objetos do Storage (roles/storage.objectViewer) à conta de serviço associada à conexão.
4. Crie e associe a tabela de objetos à conexão usando a instruçã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 role (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 role (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

Funções exigidas

Para criar tabelas de objetos, você precisa ter os seguintes papéis no projeto:

• Para criar conjuntos de dados e tabelas, você precisa ter o papel de editor de dados do BigQuery (roles/bigquery.dataEditor).
• Para criar uma conexão, você precisa ter o papel de Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin).
• Para conceder um papel à conta de serviço da conexão, você precisa ter o papel de Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin).

Para consultar tabelas de objetos, você precisa ter as seguintes funções no projeto:

• Papel de leitor de dados do BigQuery (roles/bigquery.dataViewer)
• Papel de usuário de conexão do BigQuery (roles/bigquery.connectionUser)

Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

• bigquery.datasets.create
• bigquery.tables.create
• bigquery.tables.update
• bigquery.connections.create
• bigquery.connections.get
• bigquery.connections.list
• bigquery.connections.update
• bigquery.connections.use
• bigquery.connections.delete
• bigquery.connections.delegate
• storage.bucket.*
• storage.object.*
• bigquery.jobs.create
• bigquery.tables.get
• bigquery.tables.getData
• bigquery.readsessions.create

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Cuidado:os usuários que só podem consultar os dados não podem ter o seguinte:

• A capacidade de ler objetos diretamente no Cloud Storage, concedida pelo papel Leitor de objetos do Storage.
• A capacidade de vincular tabelas a conexões, concedida pelo papel de administrador de conexão do BigQuery.

Caso contrário, os usuários poderão criar novas tabelas de objetos que não têm controles de acesso, burlando os controles feitos pelos administradores do data warehouse.

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para conter a tabela de objetos:

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Explorer, clique no nome do seu projeto.

4. Clique em Conferir ações > Criar conjunto de dados.

5. Na página Criar conjunto de dados, faça o seguinte:

   1. Em ID do conjunto de dados, digite um nome para o conjunto de dados.

   2. Em Tipo de local, selecione Região ou Multirregião.

      • Se você selecionou Região, escolha um local na lista Região.
      • Se você selecionou Multirregião, escolha EUA ou Europa na lista Multirregião.

   3. Clique em Criar conjunto de dados.

Crie uma conexão

Pule esta etapa se você tiver uma conexão padrão configurada ou a função de administrador do BigQuery.

Crie uma Conexão de recursos do Cloud para uso da tabela de objetos e tenha acesso à conta de serviço da conexão.

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, clique em Adicionar dados.

   A caixa de diálogo Adicionar dados é aberta.

4. No painel Filtrar por, na seção Tipo de fonte de dados, selecione Aplicativos comerciais.

   Como alternativa, no campo Pesquisar fontes de dados, insira Vertex AI.

5. Na seção Fontes de dados em destaque, clique em Vertex AI.

6. Clique no card da solução Modelos da Vertex AI: federação do BigQuery.

7. Na lista Tipo de conexão, selecione Modelos remotos da Vertex AI, funções remotas, BigLake e Spanner (recurso do Cloud).

8. No campo ID da conexão, digite um nome para a conexão.

9. Em Tipo de local, selecione Região ou Multirregião.

   • Se você selecionou Região, escolha um local na lista Região.
   • Se você selecionou Multirregião, escolha EUA ou Europa na lista Multirregião.

10. Clique em Criar conexão.

11. Clique em Ir para conexão.

12. No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa seguinte.

Conceder acesso à conta de serviço

Conceda à conta de serviço da conexão o papel de Leitor de objetos do Storage:

Console

1. Acesse a página IAM e administrador.

   Acessar IAM e administrador

2. Clique em Adicionar.

   A caixa de diálogo Adicionar principais é aberta.

3. No campo Novos principais, digite o ID da conta de serviço que você copiou anteriormente.

4. No campo Selecionar papel, escolha Cloud Storage e, em seguida, Visualizador de objetos do Storage.

5. Clique em Salvar.

gcloud

Use o comando gcloud projects add-iam-policy-binding.

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

Substitua:

• PROJECT_NUMBER: o número do projeto em que a função será concedida.
• MEMBER: o ID da conta de serviço que você copiou anteriormente.

criar uma tabela de objetos

Para criar uma tabela de objetos:

SQL

Use a instrução CREATE EXTERNAL TABLE.

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

   Acessar o BigQuery

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

   • PROJECT_ID: o ID do projeto
   • DATASET_ID: o ID do conjunto de dados que vai conter a tabela de objetos.
   • TABLE_NAME: o nome da tabela de objetos.
   • REGION: a região ou multirregião que contém a conexão.
   • CONNECTION_ID: o ID da conexão de recursos da nuvem a ser usada com essa tabela de objetos. A conexão determina qual conta de serviço é usada para ler dados a partir do Cloud Storage.

     Quando você visualiza os detalhes da conexão no console do Google Cloud , o ID da conexão é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

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

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

     É possível usar um caractere curinga de asterisco (*) em cada caminho para limitar os objetos incluídos na tabela de objetos. Por exemplo, se o bucket contiver vários tipos de dados não estruturados, crie a tabela de objetos usando apenas objetos PDF especificando ['gs://bucket_name/*.pdf']. Para mais informações, consulte Compatibilidade de caracteres curinga com URIs do Cloud Storage.

     É possível especificar vários buckets para a opção uris fornecendo vários caminhos, por exemplo, ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].

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

   • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela de objetos e se eles precisam ser atualizados para que possam ser usados pela operação. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

     Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

   • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

     Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

     Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

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

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

Exemplos

O exemplo a seguir cria uma tabela de objetos com um intervalo de inatividade do 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 a seguir cria uma tabela de objetos sobre os objetos em três Buckets 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 a seguir cria uma tabela de objetos apenas sobre os objetos PDF em um bucket 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:

• PROJECT_ID: o ID do projeto
• DATASET_ID: o ID do conjunto de dados que vai conter a tabela de objetos.
• TABLE_NAME: o nome da tabela de objetos.
• REGION: a região ou multirregião que contém a conexão.
• CONNECTION_ID: o ID da conexão de recursos da nuvem a ser usada com essa tabela externa. A conexão determina qual conta de serviço é usada para ler dados a partir do Cloud Storage.

  Quando você visualiza os detalhes da conexão no console do Google Cloud , o ID da conexão é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

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

  É possível usar um caractere curinga de asterisco (*) em cada caminho para limitar os objetos incluídos na tabela de objetos. Por exemplo, se o bucket contiver vários tipos de dados não estruturados, crie a tabela de objetos usando apenas objetos PDF especificando gs://bucket_name/*.pdf. Para mais informações, consulte Compatibilidade de caracteres curinga com URIs do Cloud Storage.

  É possível especificar vários buckets para a opção uris fornecendo vários caminhos, por exemplo, gs://mybucket1/*,gs://mybucket2/folder5/*.

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

• STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela de objetos e se eles precisam ser atualizados para que possam ser usados pela operação. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

  Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

  Para ativar o armazenamento em cache de metadados, especifique um valor de 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 inatividade de quatro horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

• CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

  Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

  Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

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

Exemplos

O exemplo a seguir cria uma tabela de objetos com um intervalo de inatividade do 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 a seguir cria uma tabela de objetos sobre os objetos em três Buckets 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 a seguir cria uma tabela de objetos apenas sobre os objetos PDF em um bucket 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 você transmitir.

O exemplo a seguir mostra como chamar esse método usando 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

Neste exemplo, criamos uma tabela de objetos com o armazenamento em cache de metadados ativado com atualização manual.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Os principais campos a serem especificados 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 de dois minutos. Para mais informações sobre cada recurso, consulte a documentação do Terraform no 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 em um projeto Google Cloud , siga as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto Google Cloud padrão em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

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

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

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

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu Google Cloud projeto para conferir os resultados. No console do Google Cloud , navegue até seus recursos na interface para verificar se foram criados ou atualizados pelo Terraform.

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu projeto Google Cloud .

Consultar tabelas de objetos

É possível consultar uma tabela de objetos como qualquer outro BigQuery, por exemplo:

SELECT *
FROM mydataset.myobjecttable;

Consultar uma tabela de objetos retorna metadados para eles. Para mais informações, consulte Esquema da tabela de objetos.

A seguir

• Saiba como executar inferência em tabelas de objetos de imagem.
• Saiba como analisar tabelas de objetos usando funções remotas.