Crear tablas de objetos

En este documento se describe cómo hacer que los datos no estructurados de Cloud Storage sean accesibles en BigQuery creando una tabla de objetos.

Para crear una tabla de objetos, debes completar las siguientes tareas:

1. Crea un conjunto de datos que contenga el objeto table.
2. Crea una conexión para leer información de objetos de Cloud Storage.
3. Asigna el rol Lector de objetos de Storage (roles/storage.objectViewer) a la cuenta de servicio asociada a la conexión.
4. Crea la tabla de objetos y asóciala a la conexión mediante la instrucción CREATE EXTERNAL TABLE.

Antes de empezar

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

Roles obligatorios

Para crear tablas de objetos, debes tener los siguientes roles en el proyecto:

• Para crear conjuntos de datos y tablas, debe tener el rol Editor de datos de BigQuery (roles/bigquery.dataEditor).
• Para crear una conexión, debes tener el rol Administrador de conexión de BigQuery (roles/bigquery.connectionAdmin).
• Para asignar un rol a la cuenta de servicio de la conexión, debes tener el rol Administrador de gestión de identidades y accesos de proyectos (roles/resourcemanager.projectIamAdmin).

Para consultar tablas de objetos, debes tener los siguientes roles en el proyecto:

• Rol Lector de datos de BigQuery (roles/bigquery.dataViewer)
• Rol Usuario de conexión de BigQuery (roles/bigquery.connectionUser)

Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

• 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

También puedes obtener estos permisos con roles personalizados u otros roles predefinidos.

Precaución: Los usuarios que solo deban consultar los datos no deben tener lo siguiente:

• Permite leer objetos directamente de Cloud Storage. Se concede con el rol Lector de objetos de Storage.
• La capacidad de vincular tablas a conexiones, que otorga el rol Administrador de conexiones de BigQuery.

De lo contrario, los usuarios pueden crear tablas de objetos que no tengan ningún control de acceso, lo que les permitiría eludir los controles establecidos por los administradores del almacén de datos.

Crear conjunto de datos

Crea un conjunto de datos de BigQuery que contenga la tabla de objetos:

1. En la Google Cloud consola, ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorador:

   

   Si no ves el panel de la izquierda, haz clic en Ampliar panel de la izquierda para abrirlo.

3. En el panel Explorador, haz clic en el nombre de tu proyecto.

4. Haz clic en Ver acciones > Crear conjunto de datos.

5. En la página Crear conjunto de datos, haz lo siguiente:

   1. En ID del conjunto de datos, escribe un nombre para el conjunto de datos.

   2. En Tipo de ubicación, selecciona Región o Multirregión.

      • Si has seleccionado Región, elige una ubicación de la lista Región.
      • Si has seleccionado Multirregión, elige EE. UU. o Europa en la lista Multirregión.

   3. Haz clic en Crear conjunto de datos.

Crear una conexión

Puedes saltarte este paso si tienes una conexión predeterminada configurada o si tienes el rol Administrador de BigQuery.

Crea una conexión de recursos de Cloud para que la use la tabla de objetos y obtén la cuenta de servicio de la conexión.

1. Ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorador:

   

3. En el panel Explorador, haz clic en Añadir datos.

   Se abrirá el cuadro de diálogo Añadir datos.

4. En el panel Filtrar por, en la sección Tipo de fuente de datos, selecciona Aplicaciones empresariales.

   También puede introducir Vertex AI en el campo Buscar fuentes de datos.

5. En la sección Fuentes de datos destacadas, haga clic en Vertex AI.

6. Haz clic en la tarjeta de solución Modelos de Vertex AI: federación de BigQuery.

7. En la lista Tipo de conexión, selecciona Modelos remotos y funciones remotas de Vertex AI, BigLake y Spanner (recurso de Cloud).

8. En el campo ID de conexión, escriba un nombre para la conexión.

9. En Tipo de ubicación, selecciona Región o Multirregión.

   • Si has seleccionado Región, elige una ubicación de la lista Región.
   • Si has seleccionado Multirregión, elige EE. UU. o Europa en la lista Multirregión.

10. Haga clic en Crear conexión.

11. Haz clic en Ir a la conexión.

12. En el panel Información de conexión, copia el ID de la cuenta de servicio para usarlo en un paso posterior.

Dar acceso a la cuenta de servicio

Asigna el rol Lector de objetos de Storage a la cuenta de servicio de la conexión:

Consola

1. Ve a la página IAM y administración.

   Ir a IAM y administración

2. Haz clic en Añadir.

   Se abrirá el cuadro de diálogo Añadir principales.

3. En el campo Nuevos principales, introduce el ID de la cuenta de servicio que has copiado anteriormente.

4. En el campo Selecciona un rol, elige Cloud Storage y, a continuación, Visor de objetos de Storage.

5. Haz clic en Guardar.

gcloud

Usa el comando gcloud projects add-iam-policy-binding.

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

Haz los cambios siguientes:

• PROJECT_NUMBER: número del proyecto en el que se va a conceder el rol.
• MEMBER: el ID de la cuenta de servicio que has copiado anteriormente.

Crear una tabla de objetos

Para crear una tabla de objetos, sigue estos pasos:

SQL

Usa la instrucción CREATE EXTERNAL TABLE.

1. En la Google Cloud consola, ve a la página BigQuery.

   Ir a BigQuery

2. En el editor de consultas, introduce la siguiente instrucción:

   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');

   Haz los cambios siguientes:

   • PROJECT_ID: tu ID de proyecto.
   • DATASET_ID: el ID del conjunto de datos que contiene la tabla de objetos.
   • TABLE_NAME: el nombre de la tabla de objetos.
   • REGION: la región o multirregión que contiene la conexión.
   • CONNECTION_ID: ID de la conexión de recursos de nube que se va a usar con esta tabla de objetos. La conexión determina qué cuenta de servicio se usa para leer datos de Cloud Storage.

     Cuando consultas los detalles de la conexión en la consola de Google Cloud , el ID de conexión es el valor de la última sección del ID de conexión completo que se muestra en ID de conexión, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.

     Para usar una conexión predeterminada, especifica DEFAULT en lugar de la cadena de conexión que contiene PROJECT_ID.REGION.CONNECTION_ID.

   • BUCKET_PATH: ruta al segmento de Cloud Storage que contiene los objetos representados por la tabla de objetos, con el formato ['gs://bucket_name/[folder_name/]*'].

     Puede usar un carácter comodín de asterisco (*) en cada ruta para limitar los objetos incluidos en la tabla de objetos. Por ejemplo, si el contenedor contiene varios tipos de datos no estructurados, puede crear la tabla de objetos solo con objetos PDF especificando ['gs://bucket_name/*.pdf']. Para obtener más información, consulta Compatibilidad con comodines para URIs de Cloud Storage.

     Puedes especificar varios contenedores para la opción uris proporcionando varias rutas, por ejemplo, ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].

     Para obtener más información sobre cómo usar URIs de Cloud Storage en BigQuery, consulta Ruta de recursos de Cloud Storage.

   • STALENESS_INTERVAL: especifica si las operaciones en la tabla de objetos usan metadatos almacenados en caché y cómo de actualizados deben estar los metadatos almacenados en caché para que la operación los use. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para mejorar el rendimiento.

     Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Este es el valor predeterminado.

     Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica INTERVAL 4 HOUR para un intervalo de obsolescencia de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se han actualizado en las últimas 4 horas. Si los metadatos almacenados en caché son anteriores a ese periodo, la operación recupera los metadatos de Cloud Storage.

   • CACHE_MODE: especifica si la caché de metadatos se actualiza automáticamente o manualmente. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta el artículo Almacenamiento en caché de metadatos para mejorar el rendimiento.

     Selecciona AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, normalmente entre 30 y 60 minutos.

     Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

     Debes definir CACHE_MODE si STALENESS_INTERVAL tiene un valor superior a 0.

3. Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

Ejemplos

En el siguiente ejemplo se crea una tabla de objetos con un intervalo de obsolescencia de la caché de metadatos de 1 día:

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'
);

En el siguiente ejemplo se crea una tabla de objetos a partir de los objetos de tres segmentos de 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/*']
);

En el siguiente ejemplo se crea una tabla de objetos que contiene solo los objetos PDF de un segmento de Cloud Storage:

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

bq

Usa el 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

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto.
• DATASET_ID: el ID del conjunto de datos que contiene la tabla de objetos.
• TABLE_NAME: el nombre de la tabla de objetos.
• REGION: la región o multirregión que contiene la conexión.
• CONNECTION_ID: ID de la conexión de recurso en la nube que se va a usar con esta tabla externa. La conexión determina qué cuenta de servicio se usa para leer datos de Cloud Storage.

  Cuando consultas los detalles de la conexión en la consola de Google Cloud , el ID de conexión es el valor de la última sección del ID de conexión completo que se muestra en ID de conexión, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.

• BUCKET_PATH: ruta al segmento de Cloud Storage que contiene los objetos representados por la tabla de objetos, con el formato gs://bucket_name/[folder_name/]*.

  Puede usar un carácter comodín de asterisco (*) en cada ruta para limitar los objetos incluidos en la tabla de objetos. Por ejemplo, si el contenedor contiene varios tipos de datos no estructurados, puede crear la tabla de objetos solo con objetos PDF especificando gs://bucket_name/*.pdf. Para obtener más información, consulta Compatibilidad con comodines para URIs de Cloud Storage.

  Puedes especificar varios contenedores para la opción uris proporcionando varias rutas, por ejemplo, gs://mybucket1/*,gs://mybucket2/folder5/*.

  Para obtener más información sobre cómo usar URIs de Cloud Storage en BigQuery, consulta Ruta de recursos de Cloud Storage.

• STALENESS_INTERVAL: especifica si las operaciones en la tabla de objetos usan metadatos almacenados en caché y cómo de actualizados deben estar los metadatos almacenados en caché para que la operación los use. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para mejorar el rendimiento.

  Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Este es el valor predeterminado.

  Para habilitar el almacenamiento en caché de metadatos, especifica un valor de intervalo entre 30 minutos y 7 días con el formato Y-M D H:M:S descrito en la documentación del tipo de datos INTERVAL. Por ejemplo, especifica 0-0 0 4:0:0 para un intervalo de obsolescencia de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se han actualizado en las últimas 4 horas. Si los metadatos almacenados en caché son anteriores a esa fecha, la operación recupera los metadatos de Cloud Storage.

• CACHE_MODE: especifica si la caché de metadatos se actualiza automáticamente o manualmente. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta el artículo Almacenamiento en caché de metadatos para mejorar el rendimiento.

  Selecciona AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, normalmente entre 30 y 60 minutos.

  Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

  Debes definir CACHE_MODE si STALENESS_INTERVAL tiene un valor superior a 0.

Ejemplos

En el siguiente ejemplo se crea una tabla de objetos con un intervalo de obsolescencia de la caché de metadatos de 1 día:

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

En el siguiente ejemplo se crea una tabla de objetos a partir de los objetos de tres segmentos de 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

En el siguiente ejemplo se crea una tabla de objetos que contiene solo los objetos PDF de un segmento de Cloud Storage:

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

API

Llama al método tables.insert. Incluye un objeto ExternalDataConfiguration con el campo objectMetadata definido como SIMPLE en el recurso Table que envíes.

En el siguiente ejemplo se muestra cómo llamar a este método mediante 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

En este ejemplo se crea una tabla de objetos con el almacenamiento en caché de metadatos habilitado y la actualización manual.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configurar la autenticación para bibliotecas de cliente.

Los campos clave que se deben especificar en una tabla de objetos son google_bigquery_table.external_data_configuration.object_metadata, google_bigquery_table.external_data_configuration.metadata_cache_mode y google_bigquery_table.max_staleness. Para obtener más información sobre cada recurso, consulta la documentación de 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 la configuración de Terraform en un Google Cloud proyecto, sigue los pasos que se indican en las siguientes secciones.

Preparar Cloud Shell

1. Abre Cloud Shell.

2. Define el Google Cloud proyecto predeterminado en el que quieras aplicar tus configuraciones de Terraform.

   Solo tienes que ejecutar este comando una vez por proyecto y puedes hacerlo en cualquier directorio.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Las variables de entorno se anulan si defines valores explícitos en el archivo de configuración de Terraform.

Preparar el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

1. En Cloud Shell, crea un directorio y un archivo nuevo en ese directorio. El nombre del archivo debe tener la extensión .tf. Por ejemplo, main.tf. En este tutorial, nos referiremos al archivo como main.tf.

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

2. Si estás siguiendo un tutorial, puedes copiar el código de ejemplo de cada sección o paso.

   Copia el código de ejemplo en el archivo main.tf que acabas de crear.

   También puedes copiar el código de GitHub. Se recomienda cuando el fragmento de Terraform forma parte de una solución integral.

3. Revisa y modifica los parámetros de ejemplo para aplicarlos a tu entorno.
4. Guarda los cambios.
5. Inicializa Terraform. Solo tienes que hacerlo una vez por directorio.

   terraform init

   Si quieres usar la versión más reciente del proveedor de Google, incluye la opción -upgrade:

   terraform init -upgrade

Aplica los cambios

1. Revisa la configuración y comprueba que los recursos que va a crear o actualizar Terraform se ajustan a tus expectativas:

   terraform plan

   Haz las correcciones necesarias en la configuración.

2. Aplica la configuración de Terraform ejecutando el siguiente comando e introduciendo yes en la petición:

   terraform apply

   Espera hasta que Terraform muestre el mensaje "Apply complete!".

3. Abre tu Google Cloud proyecto para ver los resultados. En la Google Cloud consola, ve a tus recursos en la interfaz de usuario para comprobar que Terraform los ha creado o actualizado.

Nota: Los ejemplos de Terraform suelen presuponer que las APIs necesarias están habilitadas en tu proyecto Google Cloud .

Consultar tablas de objetos

Puedes consultar una tabla de objetos como cualquier otra tabla de BigQuery. Por ejemplo:

SELECT *
FROM mydataset.myobjecttable;

Al consultar una tabla de objetos, se devuelven los metadatos de los objetos subyacentes. Para obtener más información, consulta el esquema de la tabla de objetos.

Siguientes pasos

• Consulta cómo ejecutar inferencias en tablas de objetos de imagen.
• Consulta cómo analizar tablas de objetos mediante funciones remotas.