Trabaja con valores de ObjectRef

En este documento, se describen los valores de ObjectRef y cómo crearlos y usarlos en BigQuery.

Un valor ObjectRef es un tipo STRUCT con un esquema predefinido que hace referencia a objetos de Cloud Storage para el análisis multimodal. funciones de OBJ, funciones de IA o funciones definidas por el usuario de Python.

Esquema

Un valor de ObjectRef tiene los siguientes campos:

El campo content_type del campo gcs_metadata de la columna details se recupera de Cloud Storage. Puedes establecer el tipo de contenido de un objeto en Cloud Storage. Si lo omites en Cloud Storage, BigQuery inferirá el tipo de contenido a partir del sufijo del URI.

Crea valores ObjectRef

Puedes crear valores de ObjectRef con tablas de objetos, la función OBJ.MAKE_REF, la función OBJ.LIST o los conjuntos de datos de Cloud Storage Insights.

Usa tablas de objetos

Usa una tabla de objetos si no tienes URIs almacenadas en una tabla y deseas conservar una lista de todos los objetos de un prefijo de Cloud Storage. Una tabla de objetos almacena la referencia a un objeto en cada fila y tiene una columna ref que contiene valores ObjectRef. La siguiente consulta usa la declaración CREATE EXTERNAL TABLE para crear una tabla de objetos:

CREATE EXTERNAL TABLE mydataset.images
WITH CONNECTION `us.myconnection`
OPTIONS (uris=["gs://mybucket/images/*"], object_metadata="SIMPLE");

SELECT ref AS image_ref FROM mydataset.images;

Los valores de ObjectRef de una tabla de objetos deben tener un autorizador para el acceso delegado. La conexión del autorizador es la misma que usas para crear la tabla de objetos.

Usa la función OBJ.MAKE_REF

Usa la función OBJ.MAKE_REF si ya tienes URIs almacenados en una tabla y deseas crear valores de ObjectRef a partir de esos URIs. Las siguientes consultas muestran cómo crear valores ObjectRef en la columna image_ref a partir de la columna uri que contiene URIs de Cloud Storage:

-- Specify only the URI
SELECT *, OBJ.MAKE_REF(uri) AS image_ref FROM mydataset.images;
-- Specify the URI and the connection
SELECT *, OBJ.MAKE_REF(uri, "us.myconnection") AS image_ref FROM mydataset.images;

Para modificar los autorizadores de un valor ObjectRef existente, puedes usar la función OBJ.MAKE_REF:

-- Remove the authorizer
SELECT *, OBJ.MAKE_REF(ref, authorizer=>NULL) AS image_ref FROM mydataset.images;
-- Change the authorizer
SELECT *, OBJ.MAKE_REF(ref, authorizer=>"us.myconnection2") AS image_ref FROM mydataset.images;

La función OBJ.MAKE_REF acepta un autorizador anulable para admitir el acceso directo y el acceso delegado.

Usa la función OBJ.LIST

Usa la función OBJ.LIST para el descubrimiento espontáneo. La función OBJ.LIST devuelve una tabla de metadatos y valores de ObjectRef para los archivos almacenados en Cloud Storage. Los datos de Cloud Storage pueden incluir documentos, imágenes y audio.

El uso de OBJ.LIST reemplaza la necesidad de construir manualmente valores de ObjectRef en una tabla persistente. Puedes agregar rápidamente objetos de Cloud Storage a las funciones de IA para crear canalizaciones de ETL espontáneas que se encarguen de convertir datos no estructurados en datos estructurados. Si necesitas una tabla persistente y con actualización automática que haga un seguimiento continuo de los objetos nuevos que llegan a un bucket con el tiempo, debes crear una tabla de objetos estándar de BigQuery.

La siguiente consulta usa el carácter comodín (*) para descubrir tipos de archivos específicos y la función AI.IF para filtrar datos no estructurados. Esta búsqueda solo muestra los archivos PNG que contienen una imagen de un perro.

SELECT
  uri,
  content_type,
  size
FROM
  OBJ.LIST('gs://mybucket/images/*.png')
WHERE
  AI.IF(('Does this image contain a dog?', ref))
ORDER BY
  uri;

Usa conjuntos de datos de Cloud Storage Insights

Si tienes un conjunto de datos de Storage Insights configurado, este ya incluye una columna ref que contiene valores de ObjectRef. Los valores de ObjectRef creados en los conjuntos de datos de Storage Insights no tienen un autorizador. Para consultar estos objetos, debes tener acceso directo a ellos o agregar un autorizador al objeto ObjectRef para usar el acceso delegado.

Autorizador y permisos

Cuando pasas un valor ObjectRef a las funciones de ObjectRef, las funciones basadas en IA o las UDF de Python, esas funciones deben acceder al objeto almacenado en Cloud Storage. Puedes autorizar este acceso según el valor del campo authorizer de dos maneras: acceso directo y acceso delegado.

Acceso directo

Con el acceso directo, el usuario que ejecuta la consulta accede al objeto directamente con sus propias credenciales. El acceso directo se usa cuando el valor de ObjectRef no tiene un autorizador.

El acceso directo tiene las siguientes restricciones:

• El usuario debe tener permiso para acceder a los objetos.
• Un trabajo de consulta que usa las funciones AI.GENERATE, AI.IF, AI.SCORE o AI.CLASSIFY sin una conexión requiere que el usuario tenga permisos adicionales. La consulta solo puede acceder a los buckets y objetos de Cloud Storage del mismo proyecto en el que se ejecuta el trabajo.

Por ejemplo, si llamas a la función AI.GENERATE en un valor ObjectRef que no tiene un autorizador, la función leerá el objeto como si fueras tú. Si no tienes permiso para leer el objeto, la función escribe un error "permission denied" en la columna status del resultado.

En el siguiente ejemplo, se muestra una consulta que usa acceso directo:

-- Requires that the end user can read the object "gs://cloud-samples-data/vision/demo-img.jpg" and use the Agent Platform model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")));

Acceso delegado

Con el acceso delegado, el usuario que ejecuta la consulta delega el acceso al objeto en una conexión a recursos de Cloud de BigQuery, que se especifica en el campo authorizer del valor ObjectRef. El acceso delegado puede habilitar el acceso a los datos entre proyectos.

Para usar el acceso delegado, el administrador de datos debe seguir estos pasos para configurar la conexión y los permisos:

• Configuración única. El administrador de datos debe configurar una conexión a recursos de Cloud para administrar el bucket de Cloud Storage:
  1. Crea una conexión a recursos de Cloud de BigQuery o reutiliza una existente en el proyecto.
  2. Busca la cuenta de servicio en los metadatos de la conexión.
  3. Otorga a la cuenta de servicio el permiso storage.objects.get para lecturas o el permiso storage.objects.create para escrituras en el proyecto o en los buckets de Cloud Storage. Puedes otorgar estos permisos con los roles de visualizador de objetos de Storage o usuario de objetos de almacenamiento de Storage.
• Configuración por usuario. El administrador de datos debe otorgar a los usuarios el permiso bigquery.objectRefs.read para lecturas o el permiso bigquery.objectRefs.write para escrituras en la conexión de BigQuery. Puedes otorgar estos permisos con los roles de lector de ObjectRef de BigQuery o administrador de ObjectRef de BigQuery.

Por ejemplo, si un usuario pasa valores de ObjectRef que tienen un autorizador a una función de AI.GENERATE, la función verifica que el usuario tenga el permiso de bigquery.objectRefs.read y, luego, lee los objetos con la cuenta de servicio de la conexión. Si el usuario o la cuenta de servicio no tienen permisos suficientes, la función escribe un error "permission denied" en la columna status del resultado.

En el siguiente ejemplo, se muestra una búsqueda que usa acceso delegado. Para ello, se requiere lo siguiente:

• El usuario tiene el permiso bigquery.objectRefs.read en connection1.
• La cuenta de servicio de connection1 tiene el permiso storage.objects.get en el objeto.
• La cuenta de servicio de connection2 tiene el rol de usuario de Agent Platform.

SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1")),
  connection_id => "us.connection2");

Dentro de un perímetro de los Controles del servicio de VPC, las funciones de IA no pueden procesar valores de ObjectRef que usan acceso delegado. El acceso delegado genera una URL HTTPS firmada para el objeto, y Gemini Enterprise Agent Platform bloquea las recuperaciones de HTTP y HTTPS para los proyectos dentro de un perímetro. La función escribe el siguiente error en la columna status del resultado:

INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC.

Dado que la columna ref de una tabla de objetos siempre usa la conexión de la tabla de objetos como autorizador, pasar ref a una función IA dentro de un perímetro siempre devuelve este error. Para analizar el objeto, pasa un valor OBJ.MAKE_REF(uri) de un solo argumento, que usa el acceso directo y envía el URI de Cloud Storage al modelo sin generar una URL firmada.

Prácticas recomendadas

Ten en cuenta las siguientes prácticas recomendadas cuando decidas si usar acceso directo o delegado:

• Usa el acceso directo para un equipo pequeño que opera en un solo proyecto para el almacenamiento y el análisis de datos. El administrador de datos usa Identity and Access Management para otorgar a los usuarios acceso a los datos de BigQuery y Cloud Storage. Los usuarios pueden crear valores de ObjectRef a pedido sin un autorizador para analizar objetos con sus propias credenciales.
• Usa el acceso delegado para un equipo grande que opera en varios proyectos, especialmente cuando el almacenamiento y el análisis de datos están desacoplados. El administrador de datos puede configurar conexiones y crear valores de ObjectRef para el análisis con anticipación con una conexión como su autorizador. Este enfoque funciona con tablas de objetos o con OBJ.MAKE_REF en una lista de URIs. Luego, el administrador de datos puede compartir la tabla que almacena los valores de ObjectRef con los analistas. Los analistas no necesitan acceder al bucket original para analizar los objetos.

Errores

Las funciones que consumen valores ObjectRef informan errores de dos maneras:

• Falla en la consulta: Es posible que la consulta falle con un mensaje de error y sin resultados.
• Valores de error devueltos: La consulta se realiza correctamente, pero la función puede escribir errores como parte del valor devuelto. Para obtener información sobre el formato del valor de devolución, consulta la página de referencia de la función que estás usando.

Cuando una función devuelve un valor ObjectRef, el campo details de ese valor puede contener un campo errors. Si es así, el valor de ese campo es un array de errores. Cada error tiene el siguiente esquema:

Estos son dos tipos de errores comunes:

• Error de objeto: No existe la versión o el URI del objeto proporcionado.
• Error del autorizador: No existe la conexión o el usuario no tiene permiso para usarla para el acceso delegado.

La siguiente consulta muestra cómo seleccionar valores de ObjectRef que contienen errores de una columna Objectref:

SELECT ref
FROM mydataset.images
WHERE ref.details.errors IS NOT NULL;

¿Qué sigue?

• Especifica columnas ObjectRef en esquemas de tablas.
• Analiza datos multimodales.
• Obtén más información sobre las funciones ObjectRef.