Crea 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 para que contenga la tabla de objetos.
2. Crea una conexión para leer la información del objeto desde Cloud Storage.
3. Otorga el rol de visualizador de objetos de almacenamiento (roles/storage.objectViewer) a la cuenta de servicio asociada con la conexión.
4. Crea la tabla de objetos y asóciala con la conexión mediante la declaración CREATE EXTERNAL TABLE.

Antes de comenzar

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, debes tener el rol de editor de datos de BigQuery (roles/bigquery.dataEditor).
• Para crear una conexión, debes tener el rol de administrador de conexión de BigQuery (roles/bigquery.connectionAdmin).
• Para otorgar un rol a la cuenta de servicio de la conexión, debes tener el rol de administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin).

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

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

Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

• 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 o con otros roles predefinidos.

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

• La capacidad de leer objetos directamente desde Cloud Storage, que otorga el rol de visualizador de objetos de Storage.
• La capacidad de vincular tablas a conexiones, que otorga el rol de administrador de conexiones de BigQuery

De lo contrario, los usuarios pueden crear tablas de objetos nuevas que no tienen controles de acceso, de manera que eluden los controles que colocan los administradores de almacenes de datos.

Crea un conjunto de datos

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

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

   Ir a BigQuery

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

   

   Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo 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 de conjunto de datos, escribe un nombre para el conjunto de datos.

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

      • Si seleccionaste Región, selecciona una ubicación de la lista Región.
      • Si seleccionaste Multirregión, selecciona EE.UU. o Europa en la lista Multirregión.

   3. Haz clic en Crear conjunto de datos.

Crear una conexión

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

Crea una conexión de recurso 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 de BigQuery.

   Ir a BigQuery

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

   

3. En el panel Explorador, haz clic en Agregar datos.

   Se abrirá el diálogo Agregar datos.

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

   También puedes ingresar Vertex AI en el campo Buscar fuentes de datos.

5. En la sección Fuentes de datos destacadas, haz 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 de Vertex AI, funciones remotas, BigLake y Spanner (Cloud Resource).

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

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

   • Si seleccionaste Región, selecciona una ubicación de la lista Región.
   • Si seleccionaste Multirregión, selecciona EE.UU. o Europa en la lista Multirregión.

10. Haz 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 siguiente.

Otorga acceso a la cuenta de servicio

Otorga a la cuenta de servicio de la conexión el rol de visualizador de objetos de almacenamiento:

Console

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

   Ir a IAM y administración

2. Haga clic en Agregar.

   Se abre el cuadro de diálogo Agregar principales.

3. En el campo Principales nuevas (New principals), ingresa el ID de la cuenta de servicio que copiaste antes.

4. En el campo Elige un rol, elige Cloud Storage y, luego,Visualizador 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

Reemplaza lo siguiente:

• PROJECT_NUMBER: Es el número del proyecto en el que se otorgará el rol.
• MEMBER: Es el ID de la cuenta de servicio que copiaste antes.

Crea una tabla de objetos

Para crear una tabla de objetos, sigue estos pasos:

SQL

Usa la sentencia CREATE EXTERNAL TABLE.

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

   Ir a BigQuery

2. En el editor de consultas, escribe la siguiente oració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');

   Reemplaza lo siguiente:

   • PROJECT_ID: el ID de tu proyecto
   • DATASET_ID: el ID del conjunto de datos que contendrá 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: el ID de la conexión de recursos de la nube que se usará con esta tabla de objetos. La conexión determina qué cuenta de servicio se usa para leer datos de Cloud Storage.

     Cuando ves los detalles de conexión en la consola de Google Cloud , el ID de conexión es el valor en la última sección del ID de conexión completamente calificado 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: la ruta al bucket de Cloud Storage que contiene los objetos representados por la tabla de objetos, en el formato ['gs://bucket_name/[folder_name/]*'].

     Puedes usar un carácter comodín de asterisco (*) en cada ruta de acceso para limitar los objetos incluidos en la tabla de objetos. Por ejemplo, si el bucket contiene varios tipos de datos no estructurados, puedes crear la tabla de objetos solo sobre objetos PDF si especificas ['gs://bucket_name/*.pdf']. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

     Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso, por ejemplo ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].

     Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.

   • STALENESS_INTERVAL: especifica si las operaciones que se usan en la tabla de objetos usan los metadatos almacenados en caché, y qué tan actuales deben ser los metadatos almacenados en caché para que la operación los use. Si quieres obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

     Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

     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 inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.

   • CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual. Si quieres obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

     Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

     Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

     Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

Ejemplos

En el siguiente ejemplo, se crea una tabla de objetos con un intervalo de inactividad 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 sobre los objetos en tres buckets 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 solo sobre los objetos PDF en un bucket 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

Reemplaza lo siguiente:

• PROJECT_ID: el ID de tu proyecto
• DATASET_ID: el ID del conjunto de datos que contendrá 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: el ID de la conexión de recursos de la nube que se usará con esta tabla externa. La conexión determina qué cuenta de servicio se usa para leer datos de Cloud Storage.

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

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

  Puedes usar un carácter comodín de asterisco (*) en cada ruta de acceso para limitar los objetos incluidos en la tabla de objetos. Por ejemplo, si el bucket contiene varios tipos de datos no estructurados, puedes crear la tabla de objetos solo sobre objetos PDF si especificas gs://bucket_name/*.pdf. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

  Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso, por ejemplo gs://mybucket1/*,gs://mybucket2/folder5/*.

  Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.

• STALENESS_INTERVAL: especifica si las operaciones que se usan en la tabla de objetos usan los metadatos almacenados en caché, y qué tan actuales deben ser los metadatos almacenados en caché para que la operación los use. Si quieres obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

  Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

  Para habilitar el almacenamiento en caché de metadatos, especifica un valor de intervalo entre 30 minutos y 7 días, mediante Y-M D H:M:S formato que se describe en el tipo de datos INTERVAL. Por ejemplo, especifica 0-0 0 4:0:0 para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.

• CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual. Si quieres obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

  Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

  Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

  Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

Ejemplos

En el siguiente ejemplo, se crea una tabla de objetos con un intervalo de inactividad 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 sobre los objetos en tres buckets 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 solo sobre los objetos PDF en un bucket 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 configurado como SIMPLE en el recurso Table que pasas.

En el siguiente ejemplo, se muestra cómo llamar a este método con 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 con la actualización manual.

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

Los campos clave para especificar de 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 BigQuery para Terraform.

# 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 tu configuración de Terraform en un proyecto de Google Cloud , completa los pasos de las siguientes secciones.

Prepara Cloud Shell

1. Inicia Cloud Shell

2. Establece el proyecto Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

   Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

Prepara 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 dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf.

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

2. Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

   Copia el código de muestra en el main.tf recién creado.

   De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.

3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
4. Guarda los cambios.
5. Inicializa Terraform. Solo debes hacerlo una vez por directorio.

   terraform init

   De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:

   terraform init -upgrade

Aplica los cambios

1. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:

   terraform plan

   Corrige la configuración según sea necesario.

2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:

   terraform apply

   Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

3. Abre tu proyecto Google Cloud para ver los resultados. En la consola de Google Cloud , navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

Nota: Por lo general, las muestras de Terraform suponen que las APIs necesarias están habilitadas en tu proyecto de Google Cloud .

Consulta tablas de objetos

Puedes consultar una tabla de objetos como cualquier otra de BigQuery, por ejemplo:

SELECT *
FROM mydataset.myobjecttable;

Si consultas una tabla de objetos, se muestran los metadatos de los objetos subyacentes. Para obtener más información, consulta Esquema de la tabla de objetos.

¿Qué sigue?

• Aprende a ejecutar inferencias en tablas de objetos de imagen.
• Aprende a analizar tablas de objetos mediante funciones remotas.