Trabalhar com valores ObjectRef

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

Um valor ObjectRef é um STRUCT tipo com um esquema predefinido que faz referência a objetos do Cloud Storage para análise multimodal. Ele pode ser processado por funções OBJ, funções de IA ou funções definidas pelo usuário em 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 no 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 do Cloud Storage. É possível definir o tipo de conteúdo de um objeto no Cloud Storage. Se você omitir esse campo no Cloud Storage, o BigQuery vai inferir o tipo de conteúdo pelo sufixo do URI.

Criar valores ObjectRef

É possível criar valores ObjectRef usando tabelas de objetos, a função OBJ.MAKE_REF ou conjuntos de dados do Cloud 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 instrução CREATE EXTERNAL TABLE 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 a função OBJ.MAKE_REF se você já tiver URIs armazenados em uma tabela e quiser criar valores ObjectRef com base nesses 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, 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 a acesso direto e acesso delegado.

Usar conjuntos de dados do Cloud Storage Insights

Se você tiver um conjunto de dados do Storage Insights configurado, ele já vai incluir uma coluna ref que contém valores ObjectRef. 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 a eles 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 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 funções AI.GENERATE, AI.IF, AI.SCORE ou AI.CLASSIFY 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.GET_ACCESS_URL(OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg"), 'r')));

Acesso delegado

Com o acesso delegado, o usuário que executa a consulta delega o acesso a objetos a uma conexão a recursos do BigQuery Cloud, especificada no campo authorizer do valor ObjectRef. O acesso delegado pode permitir 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 ler os objetos usando a conta de serviço da conexão. Se o usuário ou a conta de serviço não tiver permissões suficientes, 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. Ela requer 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 do connection2 tem o papel de usuário da Vertex AI.
SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.GET_ACCESS_RUL(OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1"), 'r')),
  connection_id => "us.connection2");

Práticas recomendadas

Considere as práticas recomendadas a seguir ao decidir se vai usar o 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 de ObjectRef para análise com antecedência usando 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 com os analistas a tabela que armazena os valores de ObjectRef. 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 houver, 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 entender. "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 fornecida não existe.
  • Erro do autorizador: a conexão não existe ou o usuário não tem permissão para usá-la no acesso delegado.

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

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

A seguir