Visão geral das visualizações parametrizadas

Neste documento, descrevemos as visualizações parametrizadas no Spanner. As visualizações parametrizadas permitem filtrar dados dinamicamente com base em parâmetros de sessão transmitidos com consultas, especialmente para aplicativos e sistemas agênticos que usam modelos de linguagem grandes (LLMs).

As visualizações parametrizadas ampliam os recursos das visualizações de banco de dados ao injetar parâmetros de contexto diretamente em uma definição de visualização. As visualizações parametrizadas ajudam você a:

  • Transmitir parâmetros de contexto de tempo de consulta, como identidade de usuário ou locatário, para uma definição de visualização.
  • Restrinja os resultados da consulta apenas às linhas que correspondem aos parâmetros fornecidos.
  • Impedir que os usuários ignorem os filtros de dados no nível do aplicativo em consultas SQL geradas ou ad hoc.

Para mais informações, consulte Criar uma visualização parametrizada.

Como funcionam as visualizações parametrizadas

As visualizações parametrizadas usam parâmetros para transmitir com segurança o contexto no nível do aplicativo, como um ID do usuário, para o banco de dados. Quando o aplicativo executa uma consulta, ele envia o contexto com a instrução de consulta. O Spanner acessa esse contexto durante a execução, mas nem a consulta nem o usuário do aplicativo podem ler ou modificar o contexto.

A função SECURE_CONTEXT() fornece a interface SQL para acessar esses parâmetros seguros em uma definição de visualização. As visualizações parametrizadas exigem o modelo de segurança de visualização de direitos do definidor, em que a visualização usa SECURE_CONTEXT() para acessar valores e filtrar resultados.

Por exemplo, para filtrar dados com base no ID do usuário que faz a consulta, inclua o seguinte na cláusula WHERE da visualização:

CREATE VIEW MyUserData
SQL SECURITY DEFINER AS
(SELECT *
FROM AllUserData
WHERE UserID = CAST(SECURE_CONTEXT('user_id'), INT));

Isso permite que o aplicativo veja os dados deles, mas não os de outras pessoas. Também é possível criar uma visualização que permita aos moderadores ver dados menos sensíveis de qualquer usuário:

CREATE VIEW SafeUserData
SQL SECURITY DEFINER AS
(SELECT UserID, AccountCreationTime, PublicProfileText
FROM AllUserData
WHERE SECURE_CONTEXT('role') = 'Moderator');

Embora seja possível usar SECURE_CONTEXT() em qualquer lugar em uma definição de consulta de visualização, a prática recomendada para desempenho é usá-lo na cláusula WHERE para filtrar as colunas de chave principais de uma tabela ou índice. Isso garante que o Spanner envie de maneira eficiente a lógica de filtro para a camada de armazenamento.

Por padrão, a consulta direta da função SECURE_CONTEXT() em uma consulta ad hoc falha, a menos que o papel do banco de dados tenha o papel spanner_secure_context_reader. Isso impede que usuários sem privilégios inspecionem diretamente os valores de parâmetro.

Um padrão recomendado é combinar visualizações parametrizadas com visualizações de direitos do definidor e controle de acesso refinado (FGAC, na sigla em inglês). Para garantir que os usuários só possam consultar dados pela visualização:

  1. Ative o FGAC e crie um papel de banco de dados para seu aplicativo.
  2. GRANT o privilégio SELECT na visualização para o papel.
  3. Verifique se o papel do sistema public não tem privilégios concedidos nas tabelas base ou visualizações.

Exemplo:

-- Create a role for the application user
CREATE ROLE pv_user;

-- Grant SELECT permission on the view to the role
GRANT SELECT ON VIEW MyUserData TO ROLE pv_user;

Depois de criar a visualização parametrizada, o processo para uma solicitação típica é o seguinte:

  1. O aplicativo define o contexto seguro em uma solicitação de consulta. O contexto contém informações que identificam o usuário do aplicativo, como um ID ou uma função de usuário.
  2. O aplicativo executa uma consulta em uma visualização de direitos do definidor.
  3. A visualização usa a função SECURE_CONTEXT() em uma cláusula WHERE para filtrar linhas com base nos valores fornecidos no contexto seguro.
  4. O Spanner retorna apenas as linhas que correspondem ao filtro, filtrando os resultados da consulta para os dados associados ao contexto da sessão do usuário.

Por exemplo, um aplicativo pode transmitir o ID do usuário atual no contexto seguro usando uma das bibliotecas de cliente do Spanner. O exemplo a seguir usa a biblioteca de cliente C++ para definir o parâmetro seguro user_id:

(*request.mutable_secure_context())["user_id"] = "ca6095c4-1a68-44a8-9562-dd9e897326f0";

Em seguida, o aplicativo executa uma consulta SQL padrão na visualização. A visualização usa esse user_id na cláusula WHERE para retornar apenas os registros que pertencem a esse usuário:

--Query executed by the application
SELECT * FROM MyUserData;

Benefícios das visualizações parametrizadas

Os parâmetros ajudam você a atingir as seguintes metas:

  • Isolar dados de locatários em aplicativos multilocatários: use parâmetros para garantir que as consultas retornem dados apenas para um locatário específico.

  • Restringir consultas de IA agêntica: limite as consultas em linguagem natural aos dados de um usuário ou locatário.

  • Filtrar dados com credenciais temporárias: restrinja o acesso aos dados com base em um ID de usuário ou locatário que não existe no Identity and Access Management (IAM).

  • Usar credenciais particulares para filtragem: filtre dados usando valores necessários para a consulta que não devem ser retornados ao usuário final.

Redução de riscos de segurança

As visualizações parametrizadas ajudam a reduzir os riscos de segurança quando os usuários finais executam consultas não confiáveis, como consultas em linguagem natural, no banco de dados. Esses riscos incluem:

  • Comandos maliciosos: os usuários podem tentar manipular o modelo subjacente para acessar todos os dados do aplicativo.
  • Consultas SQL de escopo amplo: os modelos de linguagem grandes (LLMs) podem gerar consultas SQL que expõem dados sensíveis, mesmo em consultas de usuários bem-intencionadas.

Ao usar visualizações parametrizadas, é possível restringir o intervalo de linhas retornadas para usuários individuais do aplicativo, independentemente de como os usuários formulam as consultas.

Práticas recomendadas

Siga estas práticas para implementar visualizações parametrizadas de maneira eficaz.

  • Combine com as visualizações de direitos do definidor e o FGAC: use parâmetros como parte de um modelo de segurança abrangente que inclui visualizações de direitos do definidor e papéis de controle de acesso refinado. Conceda os privilégios do papel SELECT apenas nas visualizações e garanta que o papel e o papel do sistema public não tenham privilégios nas tabelas base subjacentes.

  • Use JSON para contextos complexos: para transmitir um contexto estruturado, como um usuário com vários papéis, serialize os dados como uma string JSON. Transmita a string JSON como um único parâmetro. Use o JSON ou o JSONB integrado do Spanner para extrair valores dentro da visualização.

  • Simplifique o acesso com UDFs SQL: se você acessa com frequência campos em um contexto JSON estruturado, crie funções SQL definidas pelo usuário (UDFs) para encapsular a lógica de extração. O uso de UDFs nas visualizações melhora a legibilidade e a capacidade de manutenção.

  • Proteja-se contra injeção de comandos com o Model Armor: ao gerar consultas usando LLMs com entrada de usuário não confiável, use o Model Armor para identificar e bloquear proativamente tentativas de injeção de comandos e jailbreak.

Limitações

As visualizações parametrizadas têm as seguintes limitações:

  • Tipos de argumento: a função SECURE_CONTEXT() requer um argumento literal de string.
  • Tipos de resultado: a função SECURE_CONTEXT() retorna uma string.
  • Interações de recursos do Spanner: não é possível usar SECURE_CONTEXT() em colunas geradas, expressões de valor de coluna padrão ou dentro de funções definidas pelo usuário (UDFs).
  • Barreiras de segurança: as visualizações parametrizadas no Spanner não incluem uma barreira de segurança. Embora todos os filtros sejam aplicados antes de retornar os resultados da consulta, eles podem não restringir quais dados são acessados durante o processamento interno da consulta.

A seguir