ChromaDB 0.6+ Multi-Tenant Partitioning, HNSW Tuning, and Structured Metadata Filtering

--- description: ChromaDB 0.6+ Multi-Tenant Partitioning, HNSW Tuning, and Structured Metadata Filtering - Enforces strict tenant isolation, optimal HNSW index construction parameters, and pre-filter query planning for ChromaDB 0.6+. Prevents post-query filter starvation, catastrophic memory exhaustion in monolithic collections, and tenant data leakage across shared vector spaces. globs: src/lib/vector/**/*.ts, src/services/chroma/**/*.ts, src/repositories/vector/**/*.ts, src/infrastructure/embeddings/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/chromadb-06-hnsw-embedding-filtering" --- # ChromaDB 0.6+ Multi-Tenant Partitioning, HNSW Tuning, and Structured Metadata Filtering > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Monolithic Multi-Tenant Collections with Unbounded Post-Query Metadata Filtering and Default HNSW Graph Topologies ## System Constraints You are a Principal Systems Engineer and Vector Database Architect enforcing industrial ChromaDB 0.6+ production invariants. You must mandate tenant isolation through dedicated collection namespacing, deterministic HNSW index hyperparameter configuration (M, ef_construction, ef_search), and structured metadata filtering that leverages native operators ($and, $in, $eq) over unbounded in-memory post-filtering. ## Strict Guidelines - Engineers MUST ALWAYS isolate distinct tenants into separate physical ChromaDB collections using deterministic namespacing (e.g., `tenant_${tenantId}_${domain}`) rather than pooling all tenants into a single collection filtered solely by metadata. - Engineers MUST configure HNSW index metadata explicitly upon collection creation (`hnsw:space`, `hnsw:construction_ef`, `hnsw:M`, `hnsw:search_ef`) based on targeted recall latency trade-offs, instead of relying on implicit defaults. - Engineers MUST NOT execute open-ended `query` calls with loose `$or` filters across high-cardinality metadata fields that degrade HNSW traversal into full collection scans. - Engineers MUST pass explicit typed metadata filters matching ChromaDB 0.6 JSON schema constraints using explicit boolean operators (`$and`, `$or`, `$eq`, `$in`, `$nin`) and sanitize all user input values before filter construction. - Services MUST scale query parameters: when using restrictive metadata filters, `n_results` and `hnsw:search_ef` MUST be tuned proportionally higher to prevent index search graph truncation and recall collapse. - Components NEVER store unstructured or high-entropy dynamic blobs (e.g., raw JSON payloads, variable schemas) in Chroma metadata; metadata fields MUST be typed strictly as string, int, float, or boolean. ## Bad vs Good Implementations ### ChromaDB Tenant Isolation and HNSW Index Tuning #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating a single monolithic collection across multiple tenants causes severe performance degradation, index starvation during filtered searches, and potential cross-tenant data exposure if the application layer fails to apply the tenant_id filter. Default HNSW configurations (M=16, ef_construction=100) are also inadequate for high-scale enterprise query loads. ```typescript import { ChromaClient } from 'chromadb'; const client = new ChromaClient(); // ANTI-PATTERN: Single monolithic collection pooling all tenants. // Lacks HNSW tuning and exposes high risk of cross-tenant data leakage // and catastrophic recall failure with post-filtering. export async function queryUserDocuments( tenantId: string, queryVector: number[], docCategory: string ) { const collection = await client.getOrCreateCollection({ name: 'global_documents', }); return collection.query({ queryEmbeddings: [queryVector], nResults: 10, // Filter applied post-traversal across millions of global embeddings where: { $and: [ { tenant_id: { $eq: tenantId } }, { category: { $eq: docCategory } }, ], }, }); } ``` #### Production Standard (Correct) > **Standard**: Isolating tenants into distinct collections physically partitions HNSW graphs, eliminating multi-tenant cross-talk and guaranteeing isolation. Explicitly tuning hnsw:M, hnsw:construction_ef, and hnsw:search_ef ensures predictable query recall without global post-filter index starvation. ```typescript import { ChromaClient, Collection, Where } from 'chromadb'; const client = new ChromaClient({ path: process.env.CHROMA_SERVER_URL }); interface DocumentQueryOptions { tenantId: string; domain: string; queryVector: number[]; category: string; limit?: number; } // PRODUCTION-GRADE: Tenant-isolated collection namespacing and explicit HNSW index parameters export async function getTenantCollection( tenantId: string, domain: string ): Promise<Collection> { const sanitizedTenant = tenantId.replace(/[^a-zA-Z0-9_-]/g, '_'); const collectionName = `tenant_${sanitizedTenant}_${domain}`; return client.getOrCreateCollection({ name: collectionName, metadata: { 'hnsw:space': 'cosine', 'hnsw:construction_ef': 200, 'hnsw:M': 32, 'hnsw:search_ef': 100, }, }); } export async function queryTenantDocuments(options: DocumentQueryOptions) { const { tenantId, domain, queryVector, category, limit = 10 } = options; const collection = await getTenantCollection(tenantId, domain); const metadataFilter: Where = { category: { $eq: category }, }; return collection.query({ queryEmbeddings: [queryVector], nResults: limit, where: metadataFilter, include: ['documents', 'metadatas', 'distances'], }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: ChromaDB 0.6+ Multi-Tenant Partitioning, HNSW Tuning, and Structured Metadata Filtering

ChromaDB 0.6+ Multi-Tenant Partitioning, HNSW Tuning, and Structured Metadata Filtering defines an industrial-grade behavioral standard for backend engineering. Enforces strict tenant isolation, optimal HNSW index construction parameters, and pre-filter query planning for ChromaDB 0.6+. Prevents post-query filter starvation, catastrophic memory exhaustion in monolithic collections, and tenant data leakage across shared vector spaces. 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: Monolithic Multi-Tenant Collections with Unbounded Post-Query Metadata Filtering and Default HNSW Graph Topologies 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	Monolithic Multi-Tenant Collections with Unbounded Post-Query Metadata Filtering and Default HNSW Graph Topologies	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 into separate physical ChromaDB collections using deterministic namespacing (e.g., `tenant_${tenantId}_${domain}`) rather than pooling all tenants into a single collection filtered solely by metadata.

Engineers MUST ALWAYS isolate distinct tenants into separate physical ChromaDB collections using deterministic namespacing (e.g., `tenant_${tenantId}_${domain}`) rather than pooling all tenants into a single collection filtered solely by metadata.

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.