Crea tablas de objetos

En este documento, se describe cómo acceder a datos no estructurados en BigQuery mediante la creación de una tabla de objetos.

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

1. Crea una conexión para leer la información del objeto desde Cloud Storage.
2. Otorga permiso para leer información de Cloud Storage a la cuenta de servicio asociada con la conexión.
3. Crea la tabla de objetos y asóciala con la conexión mediante la declaración CREATE EXTERNAL TABLE.

Antes de comenzar

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

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the BigQuery and BigQuery Connection API APIs.

   Enable the APIs

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

   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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the BigQuery and BigQuery Connection API APIs.

   Enable the APIs

8. Asegúrate de que tu administrador de BigQuery cree una conexión y configure el acceso a Cloud Storage.

Roles obligatorios

Para trabajar con tablas de objetos, los usuarios necesitan los siguientes permisos de IAM según su rol en tu organización. Para obtener más información sobre los roles de los usuarios, consulta Modelo de seguridad. Para obtener más información sobre cómo otorgar permisos, consulta Visualiza los roles que se pueden otorgar en los recursos.

• Administrador de data lake

  A fin de obtener los permisos que necesitas para conectarte a Cloud Storage, pídele a tu administrador que te otorgue el rol de administrador de conexión de BigQuery (roles/bigquery.connectionAdmin) en el proyecto.

  A fin de obtener los permisos que necesitas para crear y administrar buckets de Cloud Storage, pídele a tu administrador que te otorgue el rol Administrador de almacenamiento (roles/storage.admin) en el proyecto.

  Este rol predefinido contiene los permisos necesarios para conectarse a Cloud Storage y crear y administrar buckets de Cloud Storage. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

  Permisos necesarios

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

• Administrador del almacén de datos

  A fin de obtener los permisos que necesitas para crear tablas de objetos, pídele a tu administrador que te otorgue los siguientes roles en el proyecto:

  • Rol de Editor de datos de BigQuery (roles/bigquery.dataEditor)
  • Rol de Administrador de conexión de BigQuery (roles/bigquery.connectionAdmin)

  Este rol predefinido contiene los permisos necesarios para crear tablas de objetos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

  Permisos necesarios

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

• Analista de datos

  A fin de obtener los permisos que necesitas para consultar las tablas de objetos, pídele a tu administrador que te otorgue 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)

  Este rol predefinido contiene los permisos necesarios para consultar las tablas de objetos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

  Permisos necesarios

  • 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 analistas de datos no deben tener lo siguiente:

• La capacidad de leer objetos directamente desde Cloud Storage (consulta el rol de IAM Storage Object Viewer), lo que permite a los analistas de datos eludir los controles de acceso que establecen los administradores de almacenes de datos.

• La capacidad de vincular tablas a conexiones (como BigQuery Connection Administrator)

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

Crea tablas de objetos

Antes de crear una tabla de objetos, debes tener un conjunto de datos existente que la contenga. Para obtener más información, consulta Crea conjuntos de datos.

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

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