ChromaDB 0.6 HNSW Metadata Filtering and Multi-Tenant Isolation Standard

--- description: ChromaDB 0.6 HNSW Metadata Filtering and Multi-Tenant Isolation Standard - Enforces deterministic multi-tenant isolation, HNSW index parameter calibration, and structured boolean metadata filtering in ChromaDB 0.6+. Prevents catastrophic recall collapse resulting from sparse in-graph metadata filtering on monolithic vector collections and eliminates cross-tenant data leakage risks. globs: src/vector/**/*.ts, src/services/embedding/**/*.ts, src/db/chroma/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/chromadb-0-6-hnsw-metadata-filtering-tenancy" --- # ChromaDB 0.6 HNSW Metadata Filtering and Multi-Tenant Isolation Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Sparse In-Graph Metadata Post-Filtering on Monolithic Collections Causing HNSW Recall Collapse and Tenant Bleed ## System Constraints You are a Principal Backend and Vector Search Architect enforcing ChromaDB 0.6 production patterns. You must mandate strict tenant isolation boundaries using native database/tenant namespaces or isolated collection segments, enforce typed and indexed metadata operators ($and, $or, $eq, $in), and ensure HNSW graph parameters (search_ef, construction_ef, M) are dynamically tuned to prevent query-pruning recall collapse during filtered vector queries. ## Strict Guidelines - Engineers MUST ALWAYS isolate distinct tenants using ChromaDB native multi-tenancy constructs (tenant and database namespaces) or dedicated per-tenant collections rather than relying solely on post-filtering queries against a shared monolithic collection. - Engineers MUST configure explicit HNSW collection metadata during collection creation, specifically specifying 'hnsw:space' (cosine, l2, or ip), 'hnsw:construction_ef', and 'hnsw:M'. - Engineers MUST dynamic-scale 'hnsw:search_ef' or oversample 'nResults' during filtered queries; when query filters match less than 20% of the collection's vectors, default HNSW search depth will prune valid paths and result in recall collapse (empty or suboptimal results). - Engineers MUST NOT construct metadata filter clauses using untyped raw string interpolation or flat object keys without explicit operator expressions ($eq, $in, $and). - Engineers MUST validate that all metadata values passed to ChromaDB are primitive types (string, number, boolean) and MUST NEVER pass nested JSON objects, arrays, or undefined fields into metadata payloads. - Queries filtering across multiple metadata dimensions MUST ALWAYS encapsulate conditions in explicit boolean composite operators ($and, $or) matching the ChromaDB 0.6 query specification. ## Bad vs Good Implementations ### Multi-Tenant Query with Metadata Filtering and HNSW Depth Adjustment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Querying a monolithic collection with sparse tenant metadata causes HNSW early graph pruning, returning fewer than `limit` results or empty sets (recall collapse). Furthermore, missing explicit multi-tenant namespaces creates critical isolation and performance risks in ChromaDB. ```typescript import { ChromaClient } from 'chromadb'; const client = new ChromaClient(); export async function searchTenantDocuments( tenantId: string, queryEmbedding: number[], documentType: string, limit: number ) { // ANTI-PATTERN: Shared monolithic collection relying solely on metadata filtering for tenant boundaries. // Default HNSW search_ef will prune prematurely when tenantId is sparse, leading to 0 results. // Unsanitized and implicit where-clause syntax. const collection = await client.getOrCreateCollection({ name: 'global-knowledgebase' }); return await collection.query({ queryEmbeddings: [queryEmbedding], nResults: limit, where: { tenant_id: tenantId, type: documentType, }, }); } ``` #### Production Standard (Correct) > **Standard**: Uses ChromaDB 0.6 native tenant/database routing, configures HNSW parameters with adequate search_ef depth to counteract filter-induced graph pruning, and enforces strongly typed, explicit boolean filter syntax. ```typescript import { ChromaClient, IncludeEnum, Where } from 'chromadb'; // Create tenant-isolated client instance supported in Chroma 0.6+ export function getChromaClientForTenant(tenantId: string, databaseName = 'default'): ChromaClient { return new ChromaClient({ path: process.env.CHROMA_SERVER_URL ?? 'http://localhost:8000', tenant: tenantId, database: databaseName, }); } export async function searchTenantDocuments( tenantClient: ChromaClient, collectionName: string, queryEmbedding: number[], documentType: string, limit: number ) { // Invariant 1: Collection configured with explicit HNSW parameters const collection = await tenantClient.getOrCreateCollection({ name: collectionName, metadata: { 'hnsw:space': 'cosine', 'hnsw:construction_ef': 128, 'hnsw:M': 16, 'hnsw:search_ef': Math.max(100, limit * 4), // Prevent recall collapse on filtered traversal }, }); // Invariant 2: Explicit boolean operator typing ($and, $eq) const filterClause: Where = { $and: [ { doc_type: { $eq: documentType } }, { is_archived: { $eq: false } }, ], }; return await collection.query({ queryEmbeddings: [queryEmbedding], nResults: limit, where: filterClause, include: [IncludeEnum.Metadatas, IncludeEnum.Documents, IncludeEnum.Distances], }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: ChromaDB 0.6 HNSW Metadata Filtering and Multi-Tenant Isolation Standard

ChromaDB 0.6 HNSW Metadata Filtering and Multi-Tenant Isolation Standard defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic multi-tenant isolation, HNSW index parameter calibration, and structured boolean metadata filtering in ChromaDB 0.6+. Prevents catastrophic recall collapse resulting from sparse in-graph metadata filtering on monolithic vector collections and eliminates cross-tenant data leakage risks. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Sparse In-Graph Metadata Post-Filtering on Monolithic Collections Causing HNSW Recall Collapse and Tenant Bleed Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Sparse In-Graph Metadata Post-Filtering on Monolithic Collections Causing HNSW Recall Collapse and Tenant Bleed	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS isolate distinct tenants using ChromaDB native multi-tenancy constructs (tenant and database namespaces) or dedicated per-tenant collections rather than relying solely on post-filtering queries against a shared monolithic collection.

Engineers MUST ALWAYS isolate distinct tenants using ChromaDB native multi-tenancy constructs (tenant and database namespaces) or dedicated per-tenant collections rather than relying solely on post-filtering queries against a shared monolithic collection.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.