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:
- Crea una conexión para leer la información del objeto desde Cloud Storage.
- Otorga permiso para leer información de Cloud Storage a la cuenta de servicio asociada con la conexión.
- Crea la tabla de objetos y asóciala con la conexión mediante la declaración
CREATE EXTERNAL TABLE
.
Antes de comenzar
- Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
Enable the BigQuery and BigQuery Connection API APIs.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
Enable the BigQuery and BigQuery Connection API APIs.
- 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
- Rol de Editor de datos de BigQuery (
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.
- Rol de Visualizador de datos de BigQuery (
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
.
En la consola de Google Cloud, ve a la página de BigQuery.
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 proyectoDATASET_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 sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para actualizar la caché.Debes configurar
CACHE_MODE
siSTALENESS_INTERVAL
está configurado en un valor mayor que 0.
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=BUCKET_PATH@REGION.CONNECTION_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 proyectoDATASET_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 formatogs://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 especificasgs://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 ejemplogs://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 datosINTERVAL
. Por ejemplo, especifica0-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 sistemaBQ.REFRESH_EXTERNAL_METADATA_CACHE
para actualizar la caché.Debes configurar
CACHE_MODE
siSTALENESS_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/*.pdf@us.my-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.
Para aplicar tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.
Prepara Cloud Shell
- Inicia Cloud Shell
-
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).
-
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 denominamain.tf
.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
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.
- Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
- Guarda los cambios.
-
Inicialice 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
Aplique los cambios
-
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.
-
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 “Apply complete!”.
- 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.
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.