DEV Community

JudsonRhodes1569
JudsonRhodes1569

Posted on

Postgres Metadata Filters: Multi-Tenant Vector Search Without Losing Relevant Answers

TL;DR: In multi-tenant vector search, metadata filters are the hard gate that decides which records may compete in similarity search. Put tenant_id on every chunk, bind it from trusted server-side identity, and apply it inside retrieval rather than trimming results afterward. Add narrower fields such as product, jurisdiction, document state, and effective time only when they improve relevance or enforce a real eligibility rule. Every extra predicate can reduce the candidate set and latency, but a bad one can erase the best answer. Measure both.

Filter strategy Pick this when Retrieval-quality risk Latency shape
Tenant only A help center is small or its language is distinctive Similar but irrelevant product or region pages can rank Broadest permitted candidate set
Tenant plus stable facets Product, locale, or jurisdiction changes which answer is valid Incorrect request context can hide the right chunk Usually less vector work; filtering still has a cost
Tenant plus time/state rules Draft, revoked, or future policy must never answer Bad timestamps or lifecycle data create false negatives Smaller live corpus, with more ingestion discipline
Separate physical index per tenant Isolation requirements justify operational duplication Cross-index aggregation and migrations get harder Predictable local search, more indexes to operate

That is the field guide. The tenant boundary is non-negotiable. The other rows are choices, and they should earn their place through retrieval evaluation and production telemetry.

What do metadata filters do in multi-tenant vector search?

An embedding turns text into a vector whose nearby points tend to represent related content. It does not encode authorization. A passage about reversing a card transfer may sit close to another tenant's passage about reversing a bank transfer, even though the requester must never see the second passage. Similarity asks “what looks related?” Metadata asks “what is eligible?”

This distinction matters because retrieval-augmented generation gives a model external passages to condition its answer on. If an ineligible passage reaches that context, later prompting is too late as an isolation control. The retrieval boundary has already failed. The original RAG paper describes retrieval as combining a generator with external non-parametric memory; in a SaaS help center, that memory needs an application-defined scope.

Picture the query path in words: authenticated user to server-side tenant context to filter builder to vector candidate search to reranker to cited answer. The tenant value moves forward from identity. It never comes backward from a free-form question, and the browser does not get to nominate another tenant.

Filters have three jobs. tenant_id creates the security scope. Lifecycle fields such as document_state = published keep drafts and retired guidance out of answers. Relevance facets such as product = card_issuing narrow an ambiguous question to the help-center area the user is viewing. Mixing those jobs into one undocumented bag of attributes makes incidents hard to read. Name them separately in code and telemetry.

Start there.

Pick tenant-only filtering for a clean baseline

Start with the least restrictive valid query: the tenant boundary plus published content. This is the baseline against which every relevance filter should be tested. It maximizes recall within the allowed corpus, so it exposes whether embeddings and chunking can find the answer without extra hints.

This option fits smaller tenants and queries that already contain discriminating language. It also keeps request handling simple. But fintech vocabulary repeats. “Settlement,” “beneficiary,” and “verification” can occur across products, countries, and user roles. A tenant-only search can return a semantically close page that is operationally wrong.

Do not guess. Keep a labeled query set with the expected document or chunk, then record recall at a fixed candidate count and end-to-end latency. The baseline is useful even if it loses: it tells you exactly what a new facet bought and what it hid.

Pick stable facets when context changes the answer

Add a facet when the application already knows stable context and that context separates valid answers. Product area, locale, audience role, and jurisdiction are common examples. A user browsing an EU merchant-disputes screen should not depend on the embedding to infer both attributes from a two-word query like “appeal window.”

Filters bite hard. If ingestion writes locale: en-GB but the request sends en_GB, the relevant set becomes empty. If a document applies to several products but stores only one scalar product value, a correct passage disappears. These are data-contract bugs, not model failures.

That failure is quiet.

Use controlled values and explicit arrays for multi-valued facets. Version the metadata schema beside the chunker. At ingestion time, reject a chunk that lacks its tenant, source document ID, lifecycle state, or schema version. That small amount of strictness turns silent retrieval loss into a visible pipeline error.

There is also a useful fallback rule: relax relevance facets, never the isolation facet. If tenant + product + locale returns too little evidence, a second search may drop locale or product according to a reviewed policy. It must still carry tenant and publication-state constraints. Fallback should widen relevance, not permission.

Go deep: make the retrieval contract observable

A generic TypeScript boundary keeps identity, eligibility, and ranking inputs visible. This example builds a parameterized Postgres query over chunks whose embeddings are stored in a vector-capable column. The exact distance expression and index configuration depend on the installed extension and chosen metric, so the interface keeps that concern behind vectorDistanceSql.

interface RetrievalContext {
  tenantId: string;
  product?: string;
  jurisdiction?: string;
  asOf: Date;
}

interface SearchInput {
  embedding: readonly number[];
  limit: number;
  context: RetrievalContext;
}

interface QueryPlan {
  sql: string;
  values: readonly unknown[];
  filterNames: readonly string[];
}

function buildSearch(input: SearchInput, vectorDistanceSql: string): QueryPlan {
  const clauses = [
    `tenant_id = $1`,
    `document_state = 'published'`,
    `effective_at <= $2`,
    `(expires_at IS NULL OR expires_at > $2)`,
  ];
  const values: unknown[] = [input.context.tenantId, input.context.asOf];
  const filterNames = ['tenant', 'state', 'effective_time'];

  if (input.context.product) {
    values.push(input.context.product);
    clauses.push(`$${values.length} = ANY(product_codes)`);
    filterNames.push('product');
  }

  if (input.context.jurisdiction) {
    values.push(input.context.jurisdiction);
    clauses.push(`$${values.length} = ANY(jurisdictions)`);
    filterNames.push('jurisdiction');
  }

  values.push(JSON.stringify(input.embedding), input.limit);
  const vectorParameter = `$${values.length - 1}`;
  const limitParameter = `$${values.length}`;

  return {
    sql: `
      SELECT chunk_id, document_id, content,
             ${vectorDistanceSql} AS distance
      FROM help_center_chunks
      WHERE ${clauses.join(' AND ')}
      ORDER BY distance ASC
      LIMIT ${limitParameter}
    `,
    values,
    filterNames,
  };
}
Enter fullscreen mode Exit fullscreen mode

The tenant ID must come from authenticated server context. Parameter binding protects values from becoming SQL syntax; it does not prove that a caller is entitled to a tenant. Keep authorization before this boundary, and consider database row-level security as defense in depth. PostgreSQL documents row security policies as restrictions on which rows a user may return or modify. Application testing still matters because table owners and privileged roles can interact with those policies differently.

Now instrument the contract. Emit a trace span for retrieval with low-cardinality attributes such as schema version, enabled filter names, candidate limit, result-count bucket, and outcome. Record duration around embedding lookup, filtered candidate retrieval, and reranking separately. Do not put raw questions, chunk text, account IDs, or tenant IDs into broadly accessible metric labels. High-cardinality identifiers make metrics expensive and can spread sensitive data. Keep restricted identifiers in a controlled log or trace system only when operational policy permits them.

Three signals do most of the work:

  1. Retrieval latency distributions, split by filter shape and schema version. A percentile shows the slow tail that an average hides.
  2. Empty-result and fallback rates. A sudden rise after an ingestion release points toward metadata drift before it points toward embeddings.
  3. Offline recall at a fixed candidate count, evaluated per product and jurisdiction slice. An aggregate score can conceal one broken segment.

A request log might say that tenant,state,product produced three candidates and required no fallback. It should not repeat the tenant value in a public dashboard. A trace links that retrieval step to the answer and its citations, while a counter shows whether the same shape is failing across the fleet. Crisp layers.

Measure the fallback.

For alerts, page on user-visible symptoms rather than any single empty result. Some questions genuinely have no answer. A sustained change in empty-result rate, paired with healthy ingestion volume and a recent schema-version shift, is more actionable. Likewise, latency can rise because the permitted corpus grew, because a query plan changed, or because reranking expanded. Separate timers prevent the vector store from taking blame for every slow answer.

Chunking and ingestion decide whether filters can work

Filtering begins before the query exists. Each chunk must inherit the authoritative metadata of its source document. If a 30-page policy contains several jurisdictions, document-level copying may be too coarse; split at the section where applicability changes, then attach that section's jurisdiction set. Do not infer legal scope from embedding proximity.

Preserve document_id and a stable chunk identity so replacement is deterministic. An update should not leave old and new policy chunks simultaneously eligible. One practical sequence is to write the new version as inactive, validate its chunk count and required fields, activate it, then retire the prior version. The exact transaction boundary depends on the storage architecture, but readers should never observe a half-published document. Chunk size joins the quality-versus-latency decision here: smaller chunks can isolate the exact clause and allow precise metadata, yet they create more vectors and may lose surrounding qualifications; larger chunks carry context, but retrieve more text and can blur sections with different applicability. Evaluate the full pipeline with real help-center questions, including terse queries and wording copied from the UI. Compare recall at the same candidate limit, then inspect p50 and p95 retrieval latency for each filter shape. No universal token count resolves this.

Keep an ingestion ledger with source version, content checksum, chunker version, metadata schema version, counts accepted and rejected, and activation status. This is operational evidence. When recall drops, it lets the team distinguish changed source text from changed chunking or missing facets.

Limits and a practical decision rule

Metadata filters cannot repair weak source content, a poor chunk boundary, or an embedding that does not represent the query language well. They also cannot replace authorization checks. They constrain the search space; that is powerful, but narrower is not automatically better.

Use a physical index per tenant when the isolation or operational model demands it and the team accepts duplicated index lifecycle work. Use a shared index with a mandatory tenant predicate when shared operations are appropriate and the storage engine can enforce and test that boundary. In either layout, run adversarial tests that create near-identical passages in two tenants and assert that each identity retrieves only its own record.

The decision rule is short: make permission filters unconditional, add relevance filters only when sliced evaluation improves answer selection, and retain them only while production telemetry supports the latency trade-off. Test missing, malformed, and stale metadata explicitly. That is how a filter becomes an observable retrieval contract instead of an optimistic query option.

Sources

Top comments (0)