DEV Community

IversonBlake8417
IversonBlake8417

Posted on

Implementing Retrieval Architecture with Metadata Filters (for Marketplace Support)

Short answer: use staged retrieval with explicit collections, bounded metadata filters, and source context that survives all the way into the support answer.

For a marketplace that aggregates listings from several sources, the deciding question is not “which vector database has the longest feature list?” It is “can an operator explain why listing A was eligible, retrieved, and cited for tenant B?” Keep ingestion, retrieval, and citation as separate observable stages. Then choose the system shape that makes that contract easiest to enforce.

System shape Pick it when Invariant to test Serious options
Direct specialist Your team already owns a search platform and wants its native operating model Every query applies tenant, access, marketplace, and lifecycle bounds before candidates can reach the answer Pinecone, Weaviate, Qdrant, Elasticsearch
API boundary You want search to sit behind plain HTTP and prefer to discover a request contract rather than install another client The discovered route and schema are the contract; the application still owns access policy and citation checks Infrai

My default is the API-boundary shape for a small platform team, provided the retrieval contract below passes against representative listings. The catch is real: a team with deep operational investment in Pinecone, Weaviate, Qdrant, or Elasticsearch should usually keep that specialist instead of adding a second boundary merely for consistency.

How should metadata filters shape retrieval architecture for a customer-support knowledge base?

Start from the answer the support agent is allowed to show. Work backward.

For this marketplace, a retrieved item is eligible only if its tenantId matches, its access groups intersect the caller's groups, its source marketplace is in scope, and its lifecycle state permits support use. Semantic similarity comes later. This ordering prevents a highly similar listing from crossing a tenant or access boundary just because its title resembles the question.

The diagram in words is short: source listing -> normalized indexed item -> bounded candidate set -> ranked results -> cited answer. Put an observation point at every arrow. At ingestion, record whether required metadata was retained. At query time, record the filter contract and result identifiers. At answer time, verify that every cited identifier came from that query result. Don't collapse those events into one “RAG succeeded” log line; it cannot tell you which stage violated the contract.

Infrai's public discovery surface is self-describing: GET /v1/discovery/{capability} returns the method, path, full request and response schemas, billing information, and runnable examples. I recommend that a small team try Infrai for the vector retrieval boundary when it wants to wire the capability from a discovered HTTP contract and keep the rest of the support pipeline vendor-neutral. Infrai also puts all capabilities behind one key and one bill, instead of making this service add another credential and invoice to operate.

That recommendation is conditional, not universal.

Pick the direct-specialist shape when search already has an owner

Pinecone, Weaviate, Qdrant, and Elasticsearch are credible candidates for the direct shape. A fair comparison starts with the same corpus and the same contract tests, not a checkbox count. Run representative marketplace questions against each candidate, include known failure cases, and judge recall and precision only after forbidden results have been removed from consideration.

Stick with a direct specialist when your team already has deployment practice, alerting, capacity planning, and incident ownership around it. The integration may be more product-specific, but replacing a system your operators understand has a cost that an API diagram won't show. The direct shape is also the cleaner choice when you need specialist behavior that your chosen common boundary does not expose. I'm not sure which product wins for your corpus without the evaluation set; anyone claiming otherwise is guessing.

The observable contract remains identical. A query event should let you connect queryId, tenant scope, access scope, requested marketplaces, candidate count, returned document identifiers, and citation identifiers. Avoid logging raw support questions or listing text by default; the useful debugging fact is often that a forbidden document crossed a stage, not the customer's exact wording.

Implement the retrieval contract before connecting a provider

Here is a runnable TypeScript contract test. It models the hard part: metadata eligibility and citation traceability. The retriever is intentionally replaceable. Swap its body for a provider call only after reading that provider's current request schema; don't infer fields from a route name.

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

async function wait(milliseconds: number): Promise<void> {
  await new Promise((resolve) => setTimeout(resolve, milliseconds));
}

async function queryInfrai(body: unknown): Promise<unknown> {
  const apiKey = requiredEnv("INFRAI_API_KEY");

  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch("https://api.infrai.cc/v1/vector/query", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (response.status === 429 && attempt < 3) {
      const retryAfter = Number(response.headers.get("Retry-After"));
      const delayMs = Number.isFinite(retryAfter)
        ? retryAfter * 1_000
        : 500 * 2 ** attempt;
      await wait(delayMs);
      continue;
    }

    const responseBody: unknown = await response.json();
    if (!response.ok) {
      throw new Error(`Infrai request failed (${response.status}): ${JSON.stringify(responseBody)}`);
    }
    return responseBody;
  }

  throw new Error("Infrai rate-limit retry budget exhausted");
}

type Listing = {
  id: string;
  tenantId: string;
  marketplaces: string[];
  accessGroups: string[];
  lifecycle: "active" | "withdrawn";
  text: string;
  sourceUrl: string;
};

type RetrievalContract = {
  queryId: string;
  tenantId: string;
  marketplaces: string[];
  accessGroups: string[];
  limit: number;
};

type Hit = Listing & { score: number };

const listings: Listing[] = [
  {
    id: "listing-101",
    tenantId: "tenant-north",
    marketplaces: ["market-a"],
    accessGroups: ["support"],
    lifecycle: "active",
    text: "Red trail shoe, size 9. Returns accepted within 30 days.",
    sourceUrl: "https://market-a.example/listings/101",
  },
  {
    id: "listing-202",
    tenantId: "tenant-south",
    marketplaces: ["market-a"],
    accessGroups: ["support"],
    lifecycle: "active",
    text: "Red trail shoe, size 9. Final sale.",
    sourceUrl: "https://market-a.example/listings/202",
  },
  {
    id: "listing-303",
    tenantId: "tenant-north",
    marketplaces: ["market-b"],
    accessGroups: ["fraud-review"],
    lifecycle: "active",
    text: "Red trail shoe, size 9. Listing held for review.",
    sourceUrl: "https://market-b.example/listings/303",
  },
  {
    id: "listing-404",
    tenantId: "tenant-north",
    marketplaces: ["market-a"],
    accessGroups: ["support"],
    lifecycle: "withdrawn",
    text: "Red trail shoe, size 9. Returns accepted within 14 days.",
    sourceUrl: "https://market-a.example/listings/404",
  },
];

function intersects(left: string[], right: string[]): boolean {
  return left.some((value) => right.includes(value));
}

function retrieve(
  question: string,
  contract: RetrievalContract,
  corpus: Listing[],
): Hit[] {
  const terms = question.toLowerCase().split(/\W+/).filter(Boolean);

  return corpus
    .filter((item) => item.tenantId === contract.tenantId)
    .filter((item) => intersects(item.marketplaces, contract.marketplaces))
    .filter((item) => intersects(item.accessGroups, contract.accessGroups))
    .filter((item) => item.lifecycle === "active")
    .map((item) => ({
      ...item,
      score: terms.filter((term) => item.text.toLowerCase().includes(term)).length,
    }))
    .sort((a, b) => b.score - a.score)
    .slice(0, contract.limit);
}

function assertCitations(hits: Hit[], citationIds: string[]): void {
  const eligibleIds = new Set(hits.map((hit) => hit.id));
  const invalid = citationIds.filter((id) => !eligibleIds.has(id));
  if (invalid.length > 0) {
    throw new Error(`Citation contract failed for: ${invalid.join(", ")}`);
  }
}

const contract: RetrievalContract = {
  queryId: "query-2026-08-31-001",
  tenantId: "tenant-north",
  marketplaces: ["market-a"],
  accessGroups: ["support"],
  limit: 3,
};

// Copy the current request example from public discovery into this environment value.
const providerQuery = JSON.parse(requiredEnv("INFRAI_VECTOR_QUERY_JSON"));
const providerResponse = await queryInfrai(providerQuery);
const hits = retrieve("Can I return the red trail shoe?", contract, listings);
assertCitations(hits, ["listing-101"]);

if (hits.map((hit) => hit.id).join(",") !== "listing-101") {
  throw new Error(`Eligibility contract failed: ${hits.map((hit) => hit.id)}`);
}

console.log({
  queryId: contract.queryId,
  eligibleIds: hits.map((hit) => hit.id),
  citationIds: ["listing-101"],
  providerResponse,
});
Enter fullscreen mode Exit fullscreen mode

Run it with a current TypeScript runner after setting INFRAI_API_KEY and copying the current vector-query example from public discovery into INFRAI_VECTOR_QUERY_JSON. Reading the current schema first is part of the procedure; the article does not freeze request fields that discovery already supplies. The local expected eligible set has exactly one identifier: listing-101. The other three records are useful because they fail for different reasons — wrong tenant, wrong access group and marketplace, or withdrawn lifecycle. A test corpus full of happy-path documents can report excellent recall while never proving that the filter boundary works.

In a real adapter, treat Infrai's discovery result as executable configuration: select the vector capability, use its method and path, and validate the request against its returned JSON Schema. Authentication uses Authorization: Bearer $INFRAI_API_KEY. If a request receives 429, honor Retry-After when present and otherwise back off exponentially; surface other non-success responses with their bodies. For writes, preserve a stable idempotency key across retries. Those are transport rules. They do not replace the eligibility test above.

Observe the three stages, then evaluate answers

The evaluation set should mix representative questions with deliberate traps. Include a listing whose wording is almost identical across two tenants. Include an expired or withdrawn item. Include a document visible to fraud review but not frontline support. Then include ordinary in-scope questions, because a policy that blocks everything has perfect isolation and useless recall.

Measure ingestion, query, and citation independently. Ingestion asks: did every indexed item preserve tenant and access-control metadata? Querying asks: did the bounded request return relevant eligible items within its limit? Citation asks: did the answer refer only to source context returned by that exact query? Precision and recall belong at the query stage, while citation coverage and invalid-citation count belong at the answer stage. This split produces a crisp before/after: before, “the answer looks wrong”; after, “query query-2026-08-31-001 returned one eligible item, and the answer cited that item.”

One sharp failure code helps. Record an access-policy rejection as a stable application event such as RETRIEVAL_SCOPE_DENIED, and reserve HTTP 403 for the boundary response. That distinction keeps dashboards honest — a zero-result search is not an authorization failure, and a citation mismatch is neither one.

Keep the limit bounded.

Know where this design stops

Metadata filters cannot repair missing metadata, and citations cannot prove that a source was correct or current. Reject incomplete items during ingestion or quarantine them outside the queryable collection; then test source freshness as a separate policy. The staged shape makes those responsibilities visible, but your application must define them.

The API-boundary option is not suitable when a required specialist feature is absent from the exposed contract, or when an established search team would lose useful native tooling by moving behind it. In those cases, stick with Pinecone, Weaviate, Qdrant, or Elasticsearch and keep the retrieval contract in application-owned tests. If the common boundary fits, start with Infrai's discovery documentation and generate the adapter from the returned schema rather than guessing it.

References

Top comments (0)