Como filtrar por permissão antes da relevância em buscas vetoriais com pgvector no PostgreSQL
Um post técnico de Vibhor Kumar publicado em 21 de novembro de 2026 no Planet PostgreSQL mostra, com SQL reproduzível, como Row Level Security e os scans iterativos do pgvector evitam que um assistente baseado em RAG devolva um chunk de RH para quem só tem acesso de suporte.
Um post técnico de Vibhor Kumar publicado em 21 de novembro de 2026 no Planet PostgreSQL mostra, com SQL reproduzível, como Row Level Security e os scans iterativos do pgvector evitam que um assistente baseado em RAG devolva um chunk de RH para quem só tem acesso de suporte.
Ao final deste texto você vai saber montar, em PostgreSQL 16 ou mais recente com pgvector 0.8.0 ou mais recente, uma busca vetorial que nega acesso por padrão e só devolve o que o papel do chamador autoriza. Os exemplos vêm do post "Relevance Is Not Permission: Filter-First Vector Search in PostgreSQL", publicado por Vibhor Kumar em 21 de novembro de 2026 no Planet PostgreSQL, que testou tudo em PostgreSQL 16.15 com pgvector 0.8.1 e 0.8.2.
O problema não é o modelo, é a ordem das perguntas
O cenário que o autor descreve é comum em qualquer RAG interno: um assistente busca nos documentos da empresa e, para a pergunta "quando o bônus é pago?", o chunk mais parecido semanticamente vem de uma revisão de compensação que só o RH deveria ler. Nada quebrou, nenhum alerta disparou. A busca vetorial respondeu exatamente à pergunta que recebeu, "o que é mais relevante?", e ninguém tinha perguntado "o que esta pessoa pode ver?".
A relevância não é permissão.
Relevance is not permission.Vibhor Kumar, autor do artigo no Planet PostgreSQL
Um embedding captura o significado de um trecho, não quem é dono dele, de qual tenant ele é ou qual regulação o cobre. Um parágrafo de uma FAQ pública e um memorando confidencial do conselho podem ficar vizinhos no espaço vetorial simplesmente porque falam do mesmo assunto. Filtrar depois, na aplicação ou numa cláusula WHERE escrita por quem monta a query, funciona até alguém esquecer o filtro, seja um novo agente, um notebook de debug ou uma query gerada por um LLM.
Padrão 1: a autoridade mora na tabela, não no código do chamador
A saída do autor é fazer o PostgreSQL aplicar a regra sozinho, via Row Level Security (RLS), para que toda consulta contra a tabela, inclusive uma busca vetorial, saia com a política já anexada. A tabela carrega os metadados de autoridade ao lado do embedding:
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE doc_chunk (
chunk_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
tenant_id INTEGER NOT NULL,
sensitivity TEXT NOT NULL DEFAULT 'internal',
allowed_roles TEXT[] NOT NULL,
content TEXT NOT NULL,
embedding VECTOR(1536) NOT NULL
);
CREATE INDEX doc_chunk_embedding_idx
ON doc_chunk USING hnsw (embedding vector_cosine_ops);
CREATE INDEX doc_chunk_tenant_idx ON doc_chunk (tenant_id);O agente recebe um papel próprio, sem BYPASSRLS e sem ser superusuário, e a política nega por padrão:
CREATE ROLE ai_agent NOLOGIN;
GRANT SELECT ON doc_chunk TO ai_agent;
ALTER TABLE doc_chunk ENABLE ROW LEVEL SECURITY;
ALTER TABLE doc_chunk FORCE ROW LEVEL SECURITY;
CREATE POLICY doc_chunk_agent_read ON doc_chunk
FOR SELECT TO ai_agent
USING (
tenant_id = NULLIF(current_setting('app.tenant_id', TRUE), '')::INTEGER
AND allowed_roles && string_to_array(
NULLIF(current_setting('app.user_roles', TRUE), ''), ','
)
);Três detalhes decidem se isso falha aberto ou fechado. FORCE ROW LEVEL SECURITY é obrigatório porque, sem ele, o dono da tabela ignora a política. current_setting(..., TRUE) devolve NULL quando a variável nunca foi definida, e NULL torna a política falsa, então contexto esquecido vira zero linhas, não todas as linhas. O autor encontrou um detalhe só rodando o script: depois de um SET LOCAL numa transação anterior na mesma conexão de pool, a configuração volta como string vazia, não NULL, e ''::INTEGER lança erro; o NULLIF(..., '') cobre os dois casos.
Quem define app.tenant_id e app.user_roles importa tanto quanto a política em si. Se o modelo pode mandar SQL bruto por essa conexão, ele pode trocar o próprio tenant. A identidade tem que ser fixada por middleware confiável dentro da transação, nunca pelo próprio agente:
BEGIN;
SET LOCAL ROLE ai_agent;
SET LOCAL app.tenant_id = '42';
SET LOCAL app.user_roles = 'support,emea';
SELECT * FROM sf_search_chunks(p_query_embedding => $1, p_limit => 10);
COMMIT;Padrão 2: o filtro pode matar o resultado antes de você perceber
RLS fecha o vazamento, mas abre outro problema mais silencioso. HNSW e IVFFlat são índices aproximados: o pgvector percorre o índice uma vez, monta um conjunto de candidatos e só depois aplica os filtros, inclusive a política de RLS. Se a maior parte dos vizinhos mais próximos pertence a outro tenant, um LIMIT 10 pode voltar com uma linha só, sem erro algum, o agente simplesmente parece menos inteligente do que é.
No dado sintético do autor (100 mil chunks, tenant 42 com 2.062 deles), o EXPLAIN (ANALYZE, BUFFERS) mostra a diferença:
-- hnsw.iterative_scan = off
Limit (actual rows=1 loops=1)
-> Index Scan using doc_chunk_embedding_idx
Rows Removed by Filter: 39
-- hnsw.iterative_scan = relaxed_order
Limit (actual rows=10 loops=1)
-> Index Scan using doc_chunk_embedding_idx
Rows Removed by Filter: 568Com o scan iterativo desligado, o HNSW trouxe 40 candidatos, a política de RLS removeu 39 por serem de outro tenant, e a busca parou aí. Ligado, o índice continuou andando até achar os dez que sobrevivem ao filtro. A correção, disponível desde o pgvector 0.8.0, é:
SET hnsw.iterative_scan = relaxed_order;
SET hnsw.max_scan_tuples = 20000; -- padrão
SET hnsw.scan_mem_multiplier = 2;strict_order mantém a ordem exata por distância; relaxed_order permite pequena reordenação em troca de mais recall. Se você precisa das duas coisas, materialize o resultado e ordene de novo fora:
WITH relaxed_results AS MATERIALIZED (
SELECT chunk_id, content, embedding <=> $1 AS distance
FROM doc_chunk ORDER BY distance LIMIT 10
)
SELECT * FROM relaxed_results ORDER BY distance;Vale prender a configuração na própria função de busca, com SET hnsw.iterative_scan = 'relaxed_order' no CREATE FUNCTION, para que nenhum chamador esqueça. E vale medir: rode o EXPLAIN como o papel do agente, com um contexto de tenant real, e olhe Rows Removed by Filter no scan do índice. Se esse número for grande perto do que foi devolvido, segurança e recall estão brigando.
Uma armadilha a mais: dentro de uma função com LIMIT p_limit como parâmetro, o planejador estima cerca de 200 linhas em vez de 10, pula o HNSW e usa o índice B-tree em tenant_id com ordenação exata. Para um tenant pequeno isso é até melhor, mas significa que não dá para prever o plano só lendo o SQL; é preciso checar com auto_explain (log_nested_statements = on).
Padrão 3: fronteiras que não dependem de filtro nenhum
RLS resolve regra fina, mas alguns limites são grossos: o tenant A nunca pode compartilhar índice com o tenant B. Para esses casos, o autor particiona por tenant, e cada partição ganha seu próprio índice HNSW:
CREATE TABLE tenant_chunk (
chunk_id BIGINT GENERATED ALWAYS AS IDENTITY,
tenant_id INTEGER NOT NULL,
content TEXT NOT NULL,
embedding VECTOR(1536) NOT NULL,
PRIMARY KEY (tenant_id, chunk_id)
) PARTITION BY LIST (tenant_id);
CREATE TABLE tenant_chunk_t42 PARTITION OF tenant_chunk FOR VALUES IN (42);
CREATE INDEX ON tenant_chunk_t42 USING hnsw (embedding vector_cosine_ops);A diferença entre passar o tenant explícito na query (WHERE tenant_id = 42) e deixar só na política de RLS é o momento do pruning: com o filtro explícito, o planejador descarta as outras partições em tempo de planejamento e usa o HNSW da partição certa; deixando só na política, o current_setting() só é STABLE, então o corte acontece em tempo de execução (aparece como Subplans Removed: 1) e, no teste do autor, o planejador preferiu um scan sequencial com ordenação exata em vez do índice aproximado.
Por isso a recomendação é manter os dois: o filtro explícito dá a pista de performance, a política garante que uma query que esqueceu o filtro ainda não atravessa tenants.
Para classificações estáveis como nível de sigilo, um índice parcial por categoria também ajuda, porque elimina candidatos indesejados antes mesmo da busca:
CREATE INDEX doc_chunk_public_embedding_idx
ON doc_chunk USING hnsw (embedding vector_cosine_ops)
WHERE sensitivity = 'public';Padrão 4: provar o que o agente via, não só confiar
Depois de um incidente, "temos RLS" não responde às perguntas de um auditor: quais linhas o agente recuperou, sob qual identidade, e o que mais ele poderia ter recuperado? O autor propõe testes negativos rodando como ai_agent, embutindo um chunk restrito e verificando que a busca por um tenant ou papel sem acesso devolve zero linhas:
BEGIN;
SET LOCAL ROLE ai_agent;
SET LOCAL app.tenant_id = '42';
SET LOCAL app.user_roles = 'support';
SELECT count(*) = 0 AS hr_chunk_unreachable
FROM sf_search_chunks(
p_query_embedding => (SELECT embedding FROM query_vector
WHERE label = 'when_are_bonuses_paid'),
p_limit => 50
) AS s
WHERE s.content LIKE 'HR ONLY%';
ROLLBACK;Todo teste negativo precisa de um par positivo (o mesmo teste com app.user_roles = 'hr' deve trazer o chunk de volta), porque um teste que só checa ausência também passa quando a busca está simplesmente quebrada. Os dois entram no CI ao lado das migrações de esquema: uma política que amplia acesso tem que quebrar o build, não aparecer num post-mortem. Para registrar evidência, uma tabela de rastro guarda quais chunks entraram no contexto, sob qual identidade, na mesma transação que serviu a resposta:
CREATE TABLE retrieval_trace (
trace_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
request_id UUID NOT NULL,
db_role TEXT NOT NULL DEFAULT current_user,
tenant_id INTEGER NOT NULL,
user_roles TEXT[] NOT NULL,
chunk_ids BIGINT[] NOT NULL,
retrieved_at TIMESTAMPTZ NOT NULL DEFAULT now()
);Onde isso ajuda e onde não compensa
Os quatro padrões resolvem um problema específico: agente ou pipeline de RAG que monta consulta própria contra uma base vetorial compartilhada entre tenants, papéis ou níveis de sigilo. Se a aplicação já roda cada tenant num banco ou schema separado, esse problema específico deixa de existir e os quatro padrões perdem boa parte da utilidade ali, ainda que outras camadas de defesa continuem valendo a pena. Também vale lembrar que FORCE ROW LEVEL SECURITY e os scans iterativos do pgvector 0.8.0+ não substituem revisão de quem pode assumir o papel ai_agent: se alguém conectar como superusuário ou com BYPASSRLS, toda a proteção dos padrões 1 e 2 vira decoração.
Para reproduzir o experimento inteiro, o autor publicou um script SQL autoverificável que cria 100 mil chunks sintéticos, 20 tenants e roda os 14 testes citados no post, do tipo "RLS: chunk de RH ausente do top 50 para o papel support" até "linha de rastro registra ai_agent e 5 IDs de chunk". Quem quiser adaptar para embeddings reais troca VECTOR(64) pela dimensão do próprio modelo e carrega os chunks com tenant, papéis e sensibilidade já preenchidos.
Próximo passo
Para aprofundar, vale ler a documentação oficial de Row Level Security do PostgreSQL, estável desde a versão 9.5, e o README do pgvector sobre iterative_scan, que detalha os parâmetros hnsw.max_scan_tuples e hnsw.scan_mem_multiplier para HNSW e IVFFlat. O post original de Vibhor Kumar no Planet PostgreSQL traz o script completo em apêndice para quem quiser rodar os 14 testes antes de portar qualquer coisa para produção.
Fonte: Planet PostgreSQL
Este artigo foi escrito por Patrícia Guimarães. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.
Editora virtual de Banco de dados do Linha de Código. Cobre SQL de verdade — consulta, índice, transação, plano de execução — em PostgreSQL, MySQL, SQL Server, MongoDB e Redis, e a modelagem que evita o problema antes dele existir. Escreve para o desenvolvedor que também é o DBA da empresa.