Trabalhar com valores ObjectRef

Este documento descreve os valores ObjectRef e como criá-los e usá-los no BigQuery.

Um valor ObjectRef é um tipo STRUCT com um esquema predefinido que faz referência a objetos do Cloud Storage para análise multimodal. Ele pode ser processado por OBJ funções, funções de IA, ou funções definidas pelo usuário do Python.

Esquema

Um valor ObjectRef tem os seguintes campos:

Nome Tipo Modo Descrição Exemplo
uri STRING REQUIRED O URI do objeto do Cloud Storage. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE A geração de objetos. "1560286006357632"
authorizer STRING NULLABLE Um ID de conexão do BigQuery para acesso delegado ou NULL para acesso direto. O ID pode ter os seguintes formatos:
"region.connection"
ou
"project.region.connection"		 "myproject.us.myconnection"
details JSON NULLABLE Os metadados do objeto ou erros do processamento dele. Ele pode incluir os campos content_type, md5_hash, size e updated para o objeto. {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

O campo content_type no campo gcs_metadata da coluna details é buscado no Cloud Storage. É possível definir o tipo de conteúdo de um objeto no Cloud Storage. Se você o omitir no Cloud Storage, o BigQuery vai inferir o tipo de conteúdo do sufixo do URI.

Criar valores ObjectRef

É possível criar valores ObjectRef usando tabelas de objetos, a OBJ.MAKE_REF função, ou conjuntos de dados do Storage Insights.

Usar tabelas de objetos

Use uma tabela de objetos se você não tiver URIs armazenados em uma tabela e quiser listar todos os objetos de um prefixo do Cloud Storage. Uma tabela de objetos armazena a referência a um objeto em cada linha e tem uma coluna ref que contém valores ObjectRef. A consulta a seguir usa a CREATE EXTERNAL TABLE instrução para criar uma tabela 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;

Os valores ObjectRef de uma tabela de objetos precisam ter um autorizador para acesso delegado. A conexão do autorizador é a mesma que você usa para criar a tabela de objetos.

Usar a função OBJ.MAKE_REF

Use the OBJ.MAKE_REF função se você já tiver URIs armazenados em uma tabela e quiser criar ObjectRef valores desses URIs. As consultas a seguir mostram como criar valores ObjectRef na coluna image_ref da coluna uri que contém URIs do 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 os autorizadores de um valor ObjectRef atual, use a função 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;

A função OBJ.MAKE_REF aceita um autorizador anulável para oferecer suporte ao acesso direto e delegado.

Usar conjuntos de dados do Storage Insights

Se você tiver um conjunto de dados do Storage Insights configurado, ele já vai incluir uma ref coluna que contém ObjectRef valores. Todos os valores ObjectRef criados em conjuntos de dados do Storage Insights não têm um autorizador. Para consultar esses objetos, você precisa ter acesso direto ao objeto ou adicionar um autorizador ao ObjectRef para usar o acesso delegado.

Autorizador e permissões

Quando você transmite um valor ObjectRef para funções ObjectRef, funções de IA ou UDFs do Python, essas funções precisam acessar o objeto armazenado no Cloud Storage. É possível autorizar esse acesso com base no valor do campo authorizer de duas maneiras: acesso direto e acesso delegado.

Acesso direto

Com o acesso direto, o usuário que executa a consulta acessa o objeto diretamente usando as próprias credenciais. O acesso direto é usado quando o valor ObjectRef não tem um autorizador.

O acesso direto tem as seguintes restrições:

  • O usuário precisa ter permissão para acessar os objetos.
  • Um job de consulta que usa as AI.GENERATE, AI.IF, AI.SCOREou AI.CLASSIFY funções sem uma conexão exige que o usuário tenha permissões adicionais. A consulta só pode acessar buckets e objetos do Cloud Storage do mesmo projeto em que o job é executado.

Por exemplo, se você chamar a função AI.GENERATE em um valor ObjectRef que não tem um autorizador, a função vai ler o objeto como você. Se você não tiver permissão para ler o objeto, a função vai gravar um erro "permission denied" na coluna status do resultado.

O exemplo a seguir mostra uma consulta que usa acesso direto:

-- Requires that the end user can read the object "gs://cloud-samples-data/vision/demo-img.jpg" and use the Vertex AI model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")),
  endpoint => 'gemini-2.5-pro');

Acesso delegado

Com acesso delegado, o usuário que executa a consulta delega o acesso ao objeto a uma conexão a recursos do Cloud do BigQuery, que é especificada no campo authorizer do valor ObjectRef. O acesso delegado pode ativar o acesso aos dados entre projetos.

Para usar o acesso delegado, o administrador de dados precisa seguir estas etapas para configurar a conexão e as permissões:

Por exemplo, se um usuário transmitir valores ObjectRef que têm um autorizador para uma função AI.GENERATE, a função vai verificar se o usuário tem a permissão bigquery.objectRefs.read e, em seguida, ler os objetos usando a conta de serviço da conexão. Se o usuário ou a conta de serviço tiver permissões insuficientes, a função vai gravar um erro "permission denied" na coluna status do resultado.

O exemplo a seguir mostra uma consulta que usa acesso delegado. Ele exige o seguinte:

  • O usuário tem a permissão bigquery.objectRefs.read em connection1.
  • A conta de serviço de connection1 tem a permissão storage.objects.get no objeto.
  • A conta de serviço de connection2 tem o papel de Usuário da Agent Platform.
SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1")),
  endpoint => 'gemini-2.5-pro',
  connection_id => "us.connection2");

Práticas recomendadas

Considere as práticas recomendadas a seguir ao decidir se quer usar acesso direto ou delegado:

  • Use o acesso direto para uma equipe pequena que opera em um único projeto para armazenamento e análise de dados. O administrador de dados usa o Identity and Access Management para conceder aos usuários acesso aos dados do BigQuery e do Cloud Storage. Os usuários podem criar valores ObjectRef sob demanda sem um autorizador para analisar objetos usando as próprias credenciais.
  • Use o acesso delegado para uma equipe grande que opera em vários projetos, principalmente quando o armazenamento e a análise de dados estão separados. O administrador de dados pode configurar conexões e criar valores ObjectRef para análise com antecedência com uma conexão como autorizador. Essa abordagem funciona com tabelas de objetos ou usando OBJ.MAKE_REF em uma lista de URIs. Em seguida, o administrador de dados pode compartilhar a tabela que armazena os valores ObjectRef com os analistas. Os analistas não precisam acessar o bucket original para analisar os objetos.

Erros

As funções que consomem valores ObjectRef informam erros de duas maneiras:

  • Falha na consulta: a consulta pode falhar com uma mensagem de erro e nenhum resultado.
  • Valores de erro retornados: a consulta é bem-sucedida, mas a função pode gravar erros como parte do valor de retorno. Para informações sobre o formato do valor de retorno, consulte a página de referência da função que você está usando.

Quando uma função retorna um valor ObjectRef, o campo details desse valor pode conter um campo errors. Se isso acontecer, o valor desse campo será uma matriz de erros. Cada erro tem o seguinte esquema:

Nome Tipo Modo Descrição Exemplo
code INT64 REQUIRED Código de erro HTTP padrão. 400
message STRING REQUIRED Uma mensagem de erro descritiva e fácil de usar. "Connection credential for myproject.us.nonexistent_connection cannot be used. Either the connection does not exist, or the user does not have sufficient permissions (bigquery.objectRefs.read)"
source STRING REQUIRED O nome da função que acionou o erro. "OBJ.MAKE_REF"

Estes são dois tipos comuns de erros:

  • Erro de objeto: o URI ou a versão do objeto fornecido não existe.
  • Erro do autorizador: a conexão não existe ou o usuário não tem permissão para usá-la para acesso delegado.

A consulta a seguir mostra como selecionar ObjectRef valores que contêm erros de uma coluna Objectref:

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

A seguir