ChromaDB 0.6 HNSW Filter Optimization and Tenant Isolation Standard

Enforces strict tenant isolation, optimal HNSW index utilization, and structured metadata filtering semantics for ChromaDB 0.6.x. Eliminates unindexed full-collection post-filtering scans and tenant crosstalk vulnerabilities by enforcing dedicated collection sharding or prefixed deterministic namespaces combined with valid boolean metadata filter trees. Guarantees that query operations pass strict typing validations and avoid runtime unhandled exceptions during approximate nearest neighbor graph traversals.

--- description: ChromaDB 0.6 HNSW Filter Optimization and Tenant Isolation Standard - Enforces strict tenant isolation, optimal HNSW index utilization, and structured metadata filtering semantics for ChromaDB 0.6.x. Eliminates unindexed full-collection post-filtering scans and tenant crosstalk vulnerabilities by enforcing dedicated collection sharding or prefixed deterministic namespaces combined with valid boolean metadata filter trees. Guarantees that query operations pass strict typing validations and avoid runtime unhandled exceptions during approximate nearest neighbor graph traversals. globs: src/lib/vector/**/*.ts, src/services/embedding/**/*.ts, src/repositories/vector/**/*.ts, src/services/retrieval/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/chromadb-0-6-hnsw-filtering-multitenancy" --- # ChromaDB 0.6 HNSW Filter Optimization and Tenant Isolation Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Global Single-Collection Querying with Post-Hoc Dynamic Metadata Filtering Across Tenants ## System Constraints You are a Principal Backend and Data Infrastructure Architect enforcing strict architectural invariants for ChromaDB 0.6.x deployments. Your mandate is to prevent multitenancy data leaks, eradicate full-collection sequential scans caused by unindexed filtering, and optimize HNSW graph traversal through rigid schema validation and collection-level tenant partitioning. ## Strict Guidelines - Engineers MUST ALWAYS isolate tenant workloads using dedicated collection names formatted as `tenant_${tenantId}_${domain}` or using ChromaDB 0.6 tenant/database contexts rather than relying purely on top-level runtime `$eq` metadata filtering on a monolithic collection. - Engineers MUST NOT construct untyped string-based or deeply nested unstructured metadata filters; all filters MUST conform strictly to ChromaDB 0.6 query operator specs (`$and`, `$or`, `$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`). - Code MUST explicitly specify `hnsw:space`, `hnsw:construction_ef`, `hnsw:search_ef`, and `hnsw:M` in the collection metadata at creation time to prevent falling back to sub-optimal default graph hyper-parameters. - Queries MUST NOT omit metadata filters if querying across shared multi-document spaces, and engineers MUST validate that any filtered field contains non-null, primitive scalar types (string, number, boolean) supported by ChromaDB indices. - Services MUST implement defensive fallback and pagination when `nResults` exceeds the candidate pool of a filtered HNSW subgraph to prevent zero-result truncation or memory exhaustion. ## Bad vs Good Implementations ### Tenant Isolation and Pre-Filtered HNSW Querying #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Querying a monolithic collection across tenants degrades HNSW graph traversal efficiency because nodes are pruned post-graph-hop, risking zero results when tenant density is low in a neighborhood. Furthermore, passing multi-key literal objects without explicit `$and` operators violates ChromaDB 0.6 filter parsing rules, resulting in runtime exceptions. ```typescript import { ChromaClient } from 'chromadb'; const client = new ChromaClient(); export async function searchDocuments(tenantId: string, queryEmbedding: number[], category: string) { // Flaw 1: Shared monolithic collection across all tenants leads to data bleed risk and degraded HNSW recall const collection = await client.getOrCreateCollection({ name: 'global_embeddings' }); // Flaw 2: Malformed filter structure; missing logical operators ($and) causes runtime engine rejection in ChromaDB 0.6 const results = await collection.query({ queryEmbeddings: [queryEmbedding], nResults: 10, where: { tenantId: tenantId, category: category } as any, }); return results; } ``` #### Production Standard (Correct) > **Standard**: Partitioning collections by tenant eliminates multi-tenant vector leakage and maintains high recall within the HNSW index. Specifying HNSW hyper-parameters ensures deterministic vector space indexing. Constructing a valid `$and` filter strictly adheres to ChromaDB 0.6 metadata filtering specifications. ```typescript import { ChromaClient, Where } from 'chromadb'; const client = new ChromaClient({ path: process.env.CHROMA_SERVER_URL }); interface HNSWCollectionConfig { 'hnsw:space': 'cosine' | 'l2' | 'ip'; 'hnsw:construction_ef': number; 'hnsw:search_ef': number; 'hnsw:M': number; } const DEFAULT_HNSW_METADATA: HNSWCollectionConfig = { 'hnsw:space': 'cosine', 'hnsw:construction_ef': 128, 'hnsw:search_ef': 64, 'hnsw:M': 16, }; export async function searchTenantDocuments( tenantId: string, domain: string, queryEmbedding: number[], category: string, visibility: 'public' | 'internal' ) { // Invariant 1: Hard tenant namespace isolation at collection level prevents crosstalk and optimizes index size const sanitizedTenant = tenantId.replace(/[^a-zA-Z0-9_-]/g, ''); const collectionName = `tenant_${sanitizedTenant}_${domain}`; const collection = await client.getOrCreateCollection({ name: collectionName, metadata: DEFAULT_HNSW_METADATA, }); // Invariant 2: Explicit recursive Where schema using ChromaDB 0.6 boolean operators const whereFilter: Where = { $and: [ { category: { $eq: category } }, { visibility: { $eq: visibility } } ] }; return await collection.query({ queryEmbeddings: [queryEmbedding], nResults: 10, where: whereFilter, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: ChromaDB 0.6 HNSW Filter Optimization and Tenant Isolation Standard

ChromaDB 0.6 HNSW Filter Optimization and Tenant Isolation Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict tenant isolation, optimal HNSW index utilization, and structured metadata filtering semantics for ChromaDB 0.6.x. Eliminates unindexed full-collection post-filtering scans and tenant crosstalk vulnerabilities by enforcing dedicated collection sharding or prefixed deterministic namespaces combined with valid boolean metadata filter trees. Guarantees that query operations pass strict typing validations and avoid runtime unhandled exceptions during approximate nearest neighbor graph traversals. 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: Global Single-Collection Querying with Post-Hoc Dynamic Metadata Filtering Across Tenants 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	Global Single-Collection Querying with Post-Hoc Dynamic Metadata Filtering Across Tenants	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 tenant workloads using dedicated collection names formatted as `tenant_${tenantId}_${domain}` or using ChromaDB 0.6 tenant/database contexts rather than relying purely on top-level runtime `$eq` metadata filtering on a monolithic collection.

Engineers MUST ALWAYS isolate tenant workloads using dedicated collection names formatted as `tenant_${tenantId}_${domain}` or using ChromaDB 0.6 tenant/database contexts rather than relying purely on top-level runtime `$eq` metadata filtering on a 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.