Crear tablas de objetos

En este documento se describe cómo acceder a datos no estructurados en BigQuery creando una tabla de objetos.

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

1. Crea una conexión para leer información de objetos de Cloud Storage.
2. Asigna el rol Lector de objetos de Storage (roles/storage.objectViewer) a la cuenta de servicio asociada a la conexión.
3. 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 (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. Asegúrate de que tu administrador de BigQuery haya creado una conexión y configurado el acceso a Cloud Storage.

Roles obligatorios

Para trabajar con tablas de objetos, los usuarios necesitan los siguientes permisos de gestión de identidades y accesos en función de su rol en la organización. Para obtener más información sobre los roles de usuario, consulta el modelo de seguridad. Para obtener más información sobre cómo conceder permisos, consulta el artículo Ver los roles que se pueden conceder en los recursos.

• Administrador de lago de datos

  Para obtener los permisos que necesitas para conectarte a Cloud Storage, pide a tu administrador que te asigne el rol Administrador de conexiones de BigQuery (roles/bigquery.connectionAdmin) en el proyecto.

  Para obtener los permisos que necesitas para crear y gestionar segmentos de Cloud Storage, pide a tu administrador que te conceda el rol Administrador de Storage (roles/storage.admin) en el proyecto.

  Este rol predefinido contiene los permisos necesarios para conectarse a Cloud Storage y crear y gestionar segmentos de Cloud Storage. Para ver los permisos exactos que se necesitan, despliega la sección Permisos obligatorios:

  Permisos obligatorios

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

• Administrador de almacén de datos

  Para obtener los permisos que necesita para crear tablas de objetos, pida a su administrador que le conceda los siguientes roles en el proyecto:

  • Rol Editor de datos de BigQuery (roles/bigquery.dataEditor).
  • Rol 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 se necesitan, despliega la sección Permisos obligatorios:

  Permisos obligatorios

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

• Analista de datos

  Para obtener los permisos que necesitas para consultar tablas de objetos, pide a tu administrador que te conceda 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)

  Este rol predefinido contiene los permisos necesarios para consultar tablas de objetos. Para ver los permisos exactos que se necesitan, despliega la sección Permisos obligatorios:

  Permisos obligatorios

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

• La capacidad de leer objetos directamente desde Cloud Storage (consulta el rol de gestión de identidades y accesos Lector de objetos de Storage), que permite a los analistas de datos eludir los controles de acceso establecidos por los administradores del almacén de datos.

• La capacidad de vincular tablas a conexiones (como el administrador de conexiones de BigQuery).

  De lo contrario, los analistas de datos pueden crear tablas de objetos nuevas 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 tablas de objetos

Antes de crear una tabla de objetos, debe tener un conjunto de datos que la contenga. Para obtener más información, consulta el artículo Crear conjuntos de datos.

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 en la 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 cuánto tiempo deben haber pasado desde la última actualización de los metadatos almacenados en caché para que la operación los pueda usar. 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 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.

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

     Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En ese caso, puedes llamar al BQ.REFRESH_EXTERNAL_METADATA_CACHEprocedimiento del sistema 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: el ID de la conexión de recursos 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 cuánto tiempo deben haber pasado desde la última actualización de los metadatos almacenados en caché para que la operación los pueda usar. 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.

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

  Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En ese caso, puedes llamar al BQ.REFRESH_EXTERNAL_METADATA_CACHEprocedimiento del sistema 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 proyecto, sigue los pasos que se indican en las siguientes secciones. Google Cloud

Preparar Cloud Shell

1. Abre Cloud Shell.

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

   Solo tiene que ejecutar este comando una vez por proyecto y puede 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

   Haga 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 asegurarte de 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.