# Chroma -- Core Pattern Examples

> Client setup, collection management, and fundamental operations (add, query, get, update, upsert, delete). Reference from [SKILL.md](../SKILL.md).

**Related examples:**

- [metadata-filtering.md](metadata-filtering.md) -- Filter operators and compound filters
- [embedding-functions.md](embedding-functions.md) -- Default, OpenAI, custom embedding functions

---

## Client Initialization (HTTP)

```typescript
import { ChromaClient } from "chromadb";

function createChromaClient(): ChromaClient {
  const chromaUrl = process.env.CHROMA_URL;
  if (!chromaUrl) {
    throw new Error("CHROMA_URL environment variable is required");
  }
  return new ChromaClient({ path: chromaUrl });
}

export { createChromaClient };
```

**Why good:** Server URL from environment variable (never hardcoded), validation before construction, named export

By default, `ChromaClient()` connects to `http://localhost:8000`. Explicit URL is preferred to avoid deployment-specific bugs.

---

## Cloud Client Initialization

```typescript
import { CloudClient } from "chromadb";

function createCloudClient(): CloudClient {
  const apiKey = process.env.CHROMA_API_KEY;
  if (!apiKey) {
    throw new Error("CHROMA_API_KEY environment variable is required");
  }
  return new CloudClient({
    apiKey,
    tenant: process.env.CHROMA_TENANT ?? "default_tenant",
    database: process.env.CHROMA_DATABASE ?? "default_database",
  });
}

export { createCloudClient };
```

**Why good:** API key from environment, explicit tenant and database, named export

---

## Client with Token Authentication

```typescript
import { ChromaClient } from "chromadb";

function createAuthenticatedClient(): ChromaClient {
  const chromaUrl = process.env.CHROMA_URL;
  const chromaToken = process.env.CHROMA_TOKEN;
  if (!chromaUrl || !chromaToken) {
    throw new Error(
      "CHROMA_URL and CHROMA_TOKEN environment variables required",
    );
  }

  return new ChromaClient({
    path: chromaUrl,
    auth: {
      provider: "token",
      credentials: chromaToken,
      tokenHeaderType: "X_CHROMA_TOKEN",
    },
  });
}

export { createAuthenticatedClient };
```

**Why good:** Token from environment, explicit auth provider and header type

---

## Create a Collection with Cosine Distance

```typescript
import { ChromaClient } from "chromadb";

const COLLECTION_NAME = "documents";

async function createCosineCollection(client: ChromaClient) {
  const collection = await client.createCollection({
    name: COLLECTION_NAME,
    configuration: {
      hnsw: { space: "cosine" },
    },
  });
  return collection;
}

export { createCosineCollection };
```

**Why good:** Named constant for collection name, `cosine` metric via `configuration` parameter (not deprecated metadata approach)

```typescript
// Bad Example -- deprecated HNSW config approach
const collection = await client.createCollection({
  name: "docs",
  metadata: { "hnsw:space": "cosine" }, // DEPRECATED in v3
});
```

**Why bad:** `metadata` prefix for HNSW settings is deprecated; use `configuration: { hnsw: { space } }` instead

---

## Get or Create Collection (Idempotent)

```typescript
import { ChromaClient } from "chromadb";

const COLLECTION_NAME = "articles";

async function getArticlesCollection(client: ChromaClient) {
  const collection = await client.getOrCreateCollection({
    name: COLLECTION_NAME,
    configuration: {
      hnsw: { space: "cosine" },
    },
  });
  return collection;
}

export { getArticlesCollection };
```

**Why good:** Idempotent -- safe to call repeatedly, creates on first call, returns existing on subsequent calls

**Gotcha:** If the collection already exists, `getOrCreateCollection` ignores the `configuration` parameter. It does NOT update the existing collection's configuration.

---

## Add Documents with Automatic Embedding

```typescript
import type { ChromaClient } from "chromadb";

interface ArticleMetadata {
  title: string;
  category: string;
  year: number;
}

const COLLECTION_NAME = "articles";

async function addArticles(
  client: ChromaClient,
  articles: Array<{ id: string; text: string; metadata: ArticleMetadata }>,
): Promise<void> {
  const collection = await client.getOrCreateCollection({
    name: COLLECTION_NAME,
  });

  await collection.add({
    ids: articles.map((a) => a.id),
    documents: articles.map((a) => a.text),
    metadatas: articles.map((a) => a.metadata),
  });
}

export { addArticles };
export type { ArticleMetadata };
```

**Why good:** Typed metadata interface, documents auto-embedded by collection's embedding function, columnar format (parallel arrays)

```typescript
// Bad Example -- invalid metadata and missing content
await collection.add({
  ids: ["doc-1"],
  metadatas: [
    {
      title: "Guide",
      author: { name: "Alice", org: "Acme" }, // INVALID: nested object
    },
  ],
  // Missing documents AND embeddings -- at least one required
});
```

**Why bad:** Nested metadata objects are rejected, either `documents` or `embeddings` must be provided

---

## Add Documents with Pre-Computed Embeddings

```typescript
import type { ChromaClient } from "chromadb";

const COLLECTION_NAME = "articles";

async function addWithEmbeddings(
  client: ChromaClient,
  records: Array<{
    id: string;
    embedding: number[];
    text: string;
    metadata: Record<string, string | number>;
  }>,
): Promise<void> {
  const collection = await client.getOrCreateCollection({
    name: COLLECTION_NAME,
    configuration: { hnsw: { space: "cosine" } },
  });

  await collection.add({
    ids: records.map((r) => r.id),
    embeddings: records.map((r) => r.embedding),
    documents: records.map((r) => r.text),
    metadatas: records.map((r) => r.metadata),
  });
}

export { addWithEmbeddings };
```

**Why good:** Pre-computed embeddings bypass the collection's embedding function, documents stored for retrieval, metadata for filtering

**Note:** When both `embeddings` and `documents` are provided, Chroma stores the documents but uses the provided embeddings (does not re-embed).

---

## Query by Text Similarity

```typescript
import type { ChromaClient } from "chromadb";

const N_RESULTS = 10;
const COLLECTION_NAME = "articles";

interface SearchResult {
  id: string;
  document: string | null;
  distance: number | null;
  metadata: Record<string, string | number | boolean> | null;
}

async function searchArticles(
  client: ChromaClient,
  queryText: string,
): Promise<SearchResult[]> {
  const collection = await client.getCollection({ name: COLLECTION_NAME });

  const results = await collection.query({
    queryTexts: [queryText],
    nResults: N_RESULTS,
    include: ["documents", "metadatas", "distances"],
  });

  // Results are nested arrays -- [0] for the first query
  return results.ids[0].map((id, i) => ({
    id,
    document: results.documents?.[0]?.[i] ?? null,
    distance: results.distances?.[0]?.[i] ?? null,
    metadata: results.metadatas?.[0]?.[i] ?? null,
  }));
}

export { searchArticles };
```

**Why good:** Named constant for nResults, explicit include, correct nested array access `[0]`, handles nullable fields, typed return value

```typescript
// Bad Example -- incorrect result access
const results = await collection.query({
  queryTexts: ["query"],
  nResults: 5,
});

// BUG: results.ids is string[][], not string[]
console.log(results.ids[0]); // This is correct
console.log(results.ids.length); // This is the number of QUERIES, not results!
```

**Why bad:** Treating `results.ids` as a flat array leads to bugs; must use `results.ids[0]` for single-query results

---

## Query with Multiple Queries (Batched)

```typescript
const N_RESULTS = 5;

async function batchQuery(
  collection: Awaited<ReturnType<ChromaClient["getCollection"]>>,
  queries: string[],
) {
  const results = await collection.query({
    queryTexts: queries, // Multiple queries in one call
    nResults: N_RESULTS,
  });

  // Each query gets its own result set
  return queries.map((query, queryIndex) => ({
    query,
    results: results.ids[queryIndex].map((id, i) => ({
      id,
      distance: results.distances?.[queryIndex]?.[i] ?? null,
    })),
  }));
}

export { batchQuery };
```

**Why good:** Multiple queries in single API call, correct nested array indexing per query, efficient batching

---

## Query with Pre-Computed Embeddings

```typescript
const N_RESULTS = 10;

const results = await collection.query({
  queryEmbeddings: [queryVector], // Pre-computed embedding
  nResults: N_RESULTS,
  include: ["documents", "metadatas", "distances"],
});
```

**Why good:** Bypasses collection's embedding function, useful when you manage your own embedding pipeline

**Note:** Do not pass both `queryTexts` and `queryEmbeddings` -- use one or the other.

---

## Get Documents by ID

```typescript
async function getDocuments(
  collection: Awaited<ReturnType<ChromaClient["getCollection"]>>,
  ids: string[],
) {
  const results = await collection.get({
    ids,
    include: ["documents", "metadatas"],
  });

  // get() returns flat arrays (not nested like query())
  return results.ids.map((id, i) => ({
    id,
    document: results.documents?.[i] ?? null,
    metadata: results.metadatas?.[i] ?? null,
  }));
}

export { getDocuments };
```

**Why good:** `get()` returns flat arrays (unlike `query()`), explicit include, handles nullable fields

**Gotcha:** `get()` silently omits IDs that don't exist. If you request 5 IDs and 2 don't exist, you get 3 results with no error.

---

## Get with Pagination

```typescript
const PAGE_SIZE = 50;

async function getAllDocuments(
  collection: Awaited<ReturnType<ChromaClient["getCollection"]>>,
): Promise<Array<{ id: string; document: string | null }>> {
  const allResults: Array<{ id: string; document: string | null }> = [];
  let offset = 0;

  while (true) {
    const page = await collection.get({
      limit: PAGE_SIZE,
      offset,
      include: ["documents"],
    });

    if (page.ids.length === 0) {
      break;
    }

    allResults.push(
      ...page.ids.map((id, i) => ({
        id,
        document: page.documents?.[i] ?? null,
      })),
    );

    offset += page.ids.length;
  }

  return allResults;
}

export { getAllDocuments };
```

**Why good:** Paginated retrieval for large collections, named constant for page size, terminates when no more results

---

## Update Existing Records

```typescript
async function updateDocumentMetadata(
  collection: Awaited<ReturnType<ChromaClient["getCollection"]>>,
  id: string,
  newCategory: string,
): Promise<void> {
  await collection.update({
    ids: [id],
    metadatas: [{ category: newCategory }],
  });
}

export { updateDocumentMetadata };
```

**Why good:** Updates specific fields without re-embedding (if only metadata changes)

**Gotcha:** `update()` silently ignores non-existent IDs. If the ID doesn't exist, nothing happens and no error is thrown. Use `upsert()` for create-or-update semantics.

**Note:** If `documents` are provided in `update()`, Chroma re-embeds them using the collection's embedding function.

---

## Upsert (Create or Update)

```typescript
async function upsertDocuments(
  collection: Awaited<ReturnType<ChromaClient["getCollection"]>>,
  docs: Array<{
    id: string;
    text: string;
    metadata: Record<string, string | number | boolean>;
  }>,
): Promise<void> {
  await collection.upsert({
    ids: docs.map((d) => d.id),
    documents: docs.map((d) => d.text),
    metadatas: docs.map((d) => d.metadata),
  });
}

export { upsertDocuments };
```

**Why good:** Idempotent -- creates new records or updates existing ones, safer than `add()` for pipelines that may run multiple times

---

## Delete Records

```typescript
// Delete by IDs
async function deleteByIds(
  collection: Awaited<ReturnType<ChromaClient["getCollection"]>>,
  ids: string[],
): Promise<void> {
  await collection.delete({ ids });
}

// Delete by metadata filter
async function deleteByCategory(
  collection: Awaited<ReturnType<ChromaClient["getCollection"]>>,
  category: string,
): Promise<void> {
  await collection.delete({
    where: { category: { $eq: category } },
  });
}

export { deleteByIds, deleteByCategory };
```

**Why good:** Two deletion patterns (by ID, by filter), named exports

**Gotcha:** `delete()` with no arguments is a no-op -- it does not delete everything. Pass `ids` or `where` to target specific records.

---

## Delete Collection

```typescript
async function removeCollection(
  client: ChromaClient,
  collectionName: string,
): Promise<void> {
  await client.deleteCollection({ name: collectionName });
}

export { removeCollection };
```

**Why good:** Clean deletion of entire collection including all vectors, metadata, and configuration

**Note:** This is irreversible. To recreate with different HNSW settings, delete and recreate the collection.

---

## Collection Health Check

```typescript
import { ChromaClient } from "chromadb";

async function healthCheck(client: ChromaClient): Promise<{
  serverAlive: boolean;
  version: string | null;
  collectionCount: number;
}> {
  try {
    await client.heartbeat();
    const version = await client.version();
    const count = await client.countCollections();

    return { serverAlive: true, version, collectionCount: count };
  } catch {
    return { serverAlive: false, version: null, collectionCount: 0 };
  }
}

export { healthCheck };
```

**Why good:** Uses `heartbeat()` for connectivity check, `version()` for compatibility verification, handles connection failures gracefully

---

## Peek at Collection Contents

```typescript
const PEEK_LIMIT = 5;

async function peekCollection(
  collection: Awaited<ReturnType<ChromaClient["getCollection"]>>,
) {
  const preview = await collection.peek({ limit: PEEK_LIMIT });

  console.log(`Total records: ${await collection.count()}`);
  for (let i = 0; i < preview.ids.length; i++) {
    console.log(preview.ids[i], preview.documents?.[i]?.slice(0, 100));
  }
}

export { peekCollection };
```

**Why good:** Quick debugging tool, `peek()` returns first N items in insertion order, `count()` for total size

**Note:** `peek()` is for debugging, not querying. Results are in insertion order, not relevance order.

---

## Result Iteration with `.rows()`

```typescript
// Get results -- flat iteration
const getResults = await collection.get({
  include: ["documents", "metadatas"],
});

for (const row of getResults.rows()) {
  console.log(row.id, row.document, row.metadata);
}

// Query results -- nested iteration (one batch per query)
const queryResults = await collection.query({
  queryTexts: ["search term"],
  nResults: 5,
});

for (const batch of queryResults.rows()) {
  for (const row of batch) {
    console.log(row.id, row.document, row.metadata, row.distance);
  }
}
```

**Why good:** `.rows()` provides a cleaner iteration API than manual index access, handles the nested/flat difference between query and get results

---

_Full skill documentation: [SKILL.md](../SKILL.md) | Quick reference: [reference.md](../reference.md)_

# Chroma -- Embedding Function Examples

> Default, OpenAI, and custom embedding function configuration. See [core.md](core.md) for basic operations and [reference.md](../reference.md) for the full provider list.

**Related examples:**

- [core.md](core.md) -- Client setup, add, query
- [metadata-filtering.md](metadata-filtering.md) -- Filter operators

---

## Default Embedding Function

The default embedding function uses `all-MiniLM-L6-v2` (Sentence Transformers), running locally. Requires a separate package since v3.

```bash
npm install chromadb @chroma-core/default-embed
```

```typescript
import { ChromaClient } from "chromadb";

const COLLECTION_NAME = "articles";

async function createWithDefaultEmbedding(client: ChromaClient) {
  // No embeddingFunction parameter needed -- uses default automatically
  const collection = await client.createCollection({
    name: COLLECTION_NAME,
    configuration: { hnsw: { space: "cosine" } },
  });

  // Documents are embedded automatically using all-MiniLM-L6-v2
  await collection.add({
    ids: ["doc-1", "doc-2"],
    documents: [
      "Introduction to machine learning",
      "Advanced neural network architectures",
    ],
  });

  return collection;
}

export { createWithDefaultEmbedding };
```

**Why good:** Simplest setup -- just pass documents, embedding happens automatically. No API keys needed, runs locally.

**Note:** `@chroma-core/default-embed` must be installed even though it's not explicitly imported. Chroma resolves it at runtime.

---

## OpenAI Embedding Function

Use OpenAI's `text-embedding-3-small` for higher-quality embeddings.

```bash
npm install @chroma-core/openai
```

```typescript
import { ChromaClient } from "chromadb";
import { OpenAIEmbeddingFunction } from "@chroma-core/openai";

const COLLECTION_NAME = "knowledge-base";

async function createWithOpenAI(client: ChromaClient) {
  const openAiKey = process.env.OPENAI_API_KEY;
  if (!openAiKey) {
    throw new Error("OPENAI_API_KEY environment variable is required");
  }

  const embeddingFunction = new OpenAIEmbeddingFunction({
    modelName: "text-embedding-3-small",
  });

  const collection = await client.createCollection({
    name: COLLECTION_NAME,
    embeddingFunction,
    configuration: { hnsw: { space: "cosine" } },
  });

  return collection;
}

export { createWithOpenAI };
```

**Why good:** API key from environment (reads `OPENAI_API_KEY` automatically), explicit model name, cosine metric matches OpenAI's normalized embeddings

**Note:** When retrieving an existing collection with `getCollection`, you must pass the same `embeddingFunction` so that queries are embedded correctly:

```typescript
const collection = await client.getCollection({
  name: COLLECTION_NAME,
  embeddingFunction: new OpenAIEmbeddingFunction({
    modelName: "text-embedding-3-small",
  }),
});
```

---

## Custom Embedding Function

Implement the `EmbeddingFunction` interface for custom models.

```typescript
import type { EmbeddingFunction } from "chromadb";

class CustomEmbeddingFunction implements EmbeddingFunction {
  public readonly name = "custom-embedder";
  private readonly model: string;

  constructor(args: { model: string }) {
    this.model = args.model;
  }

  async generate(texts: string[]): Promise<number[][]> {
    // Replace with your embedding logic
    // Must return one embedding vector per input text
    const embeddings = await Promise.all(
      texts.map(async (text) => {
        // Call your embedding API or model
        return new Array(384).fill(0).map(() => Math.random());
      }),
    );
    return embeddings;
  }

  getConfig(): Record<string, unknown> {
    return { model: this.model };
  }

  validateConfigUpdate(config: Record<string, unknown>): void {
    if ("model" in config) {
      throw new Error("Model cannot be updated after creation");
    }
  }

  static buildFromConfig(
    config: Record<string, unknown>,
  ): CustomEmbeddingFunction {
    return new CustomEmbeddingFunction({ model: config.model as string });
  }
}

export { CustomEmbeddingFunction };
```

**Why good:** Implements required interface methods, immutable model config, `generate()` returns one vector per input

---

## Using Embedding Functions Directly

You can invoke embedding functions independently for debugging or pre-computation.

```typescript
import { DefaultEmbeddingFunction } from "@chroma-core/default-embed";

async function debugEmbeddings(): Promise<void> {
  const embeddingFn = new DefaultEmbeddingFunction();

  // Generate embeddings outside of a collection
  const embeddings = await embeddingFn.generate([
    "test document one",
    "test document two",
  ]);

  console.log("Dimension:", embeddings[0].length);
  console.log("First embedding (first 5 values):", embeddings[0].slice(0, 5));
}

export { debugEmbeddings };
```

**Why good:** Useful for verifying embedding dimensions, debugging embedding quality, or pre-computing embeddings for external use

---

## Collection with Ollama Embeddings

Use locally-hosted models via Ollama.

```bash
npm install @chroma-core/ollama
```

```typescript
import { ChromaClient } from "chromadb";
import { OllamaEmbeddingFunction } from "@chroma-core/ollama";

const COLLECTION_NAME = "local-knowledge";

async function createWithOllama(client: ChromaClient) {
  const embeddingFunction = new OllamaEmbeddingFunction({
    url: process.env.OLLAMA_URL ?? "http://localhost:11434",
    model: "nomic-embed-text",
  });

  const collection = await client.createCollection({
    name: COLLECTION_NAME,
    embeddingFunction,
    configuration: { hnsw: { space: "cosine" } },
  });

  return collection;
}

export { createWithOllama };
```

**Why good:** Fully local embedding pipeline (no API keys), configurable Ollama URL, explicit model name

---

## Embedding Function Gotchas

**Dimension mismatch:** If you change embedding functions on an existing collection (e.g., switch from default 384-dim to OpenAI 1536-dim), queries will fail with dimension mismatch errors. Delete and recreate the collection with the new function.

**Consistency requirement:** Always pass the same embedding function to `getCollection()` / `getOrCreateCollection()` as was used at creation. If you omit it, Chroma uses the default, which may produce different-dimension embeddings.

**Query vs add:** The same embedding function is used for both `add()` (document embedding) and `query()` (query embedding). Do not mix different embedding models between add and query operations on the same collection.

---

_Full skill documentation: [SKILL.md](../SKILL.md) | Quick reference: [reference.md](../reference.md)_

# Chroma -- Metadata Filtering Examples

> Filter operators, compound filters, document content filters, and where/whereDocument patterns. See [core.md](core.md) for basic query patterns and [reference.md](../reference.md) for the operator table.

**Related examples:**

- [core.md](core.md) -- Client setup, basic query with filters
- [embedding-functions.md](embedding-functions.md) -- Embedding function configuration

---

## Comparison Operators

```typescript
const N_RESULTS = 10;

// Exact match (explicit)
const drama = await collection.query({
  queryTexts: ["dramatic story"],
  nResults: N_RESULTS,
  where: { genre: { $eq: "drama" } },
});

// Exact match (shorthand -- equivalent to $eq)
const dramaShorthand = await collection.query({
  queryTexts: ["dramatic story"],
  nResults: N_RESULTS,
  where: { genre: "drama" },
});

// Not equal
const notComedy = await collection.query({
  queryTexts: ["funny story"],
  nResults: N_RESULTS,
  where: { genre: { $ne: "comedy" } },
});

// Numeric range (greater than or equal)
const recent = await collection.query({
  queryTexts: ["recent articles"],
  nResults: N_RESULTS,
  where: { year: { $gte: 2023 } },
});

// Numeric range (less than)
const older = await collection.query({
  queryTexts: ["historical articles"],
  nResults: N_RESULTS,
  where: { year: { $lt: 2020 } },
});
```

**Why good:** Each operator targets specific types, shorthand `{ genre: "drama" }` is equivalent to `{ genre: { $eq: "drama" } }`

---

## Set Membership Operators

```typescript
const N_RESULTS = 10;

// $in -- value in set
const selectedGenres = await collection.query({
  queryTexts: ["search query"],
  nResults: N_RESULTS,
  where: { genre: { $in: ["drama", "action", "thriller"] } },
});

// $nin -- value not in set
const excludedGenres = await collection.query({
  queryTexts: ["search query"],
  nResults: N_RESULTS,
  where: { genre: { $nin: ["horror", "comedy"] } },
});
```

**Why good:** `$in` replaces multiple `$or` / `$eq` clauses, cleaner and more efficient

---

## Array Metadata Operators

For metadata fields that are arrays (e.g., tags, authors). Requires Chroma >= 1.5.0.

```typescript
const N_RESULTS = 10;

// $contains -- array includes specific value
const chenPapers = await collection.query({
  queryTexts: ["machine learning"],
  nResults: N_RESULTS,
  where: { authors: { $contains: "Chen" } },
});

// $not_contains -- array excludes specific value
const withoutDraft = await collection.query({
  queryTexts: ["published papers"],
  nResults: N_RESULTS,
  where: { tags: { $not_contains: "draft" } },
});
```

**Why good:** `$contains` checks if an array metadata field includes a scalar value, works with string/int/float/boolean arrays

**Gotcha:** `$contains` and `$not_contains` only work on array metadata fields, not on scalar values. For scalar equality, use `$eq`.

---

## Compound Filters with $and / $or

```typescript
const N_RESULTS = 10;

// AND: all conditions must match
const filteredResults = await collection.query({
  queryTexts: ["search query"],
  nResults: N_RESULTS,
  where: {
    $and: [
      { genre: { $eq: "drama" } },
      { year: { $gte: 2020 } },
      { rating: { $gt: 7.5 } },
    ],
  },
});

// OR: any condition matches
const broadResults = await collection.query({
  queryTexts: ["search query"],
  nResults: N_RESULTS,
  where: {
    $or: [{ genre: { $eq: "drama" } }, { genre: { $eq: "documentary" } }],
  },
});

// Nested AND + OR
const complexResults = await collection.query({
  queryTexts: ["search query"],
  nResults: N_RESULTS,
  where: {
    $and: [
      { year: { $gte: 2020 } },
      {
        $or: [{ genre: { $eq: "drama" } }, { genre: { $eq: "thriller" } }],
      },
    ],
  },
});
```

**Why good:** Nested logical operators for complex queries, `$or` inside `$and` for flexible filtering

---

## Document Content Filtering (whereDocument)

Filter by document text content using `$contains`, `$not_contains`, `$regex`, and `$not_regex`.

```typescript
const N_RESULTS = 10;

// $contains -- case-sensitive substring match
const containsNeural = await collection.query({
  queryTexts: ["deep learning"],
  nResults: N_RESULTS,
  whereDocument: { $contains: "neural network" },
});

// $not_contains -- exclude documents with substring
const excludeDeprecated = await collection.query({
  queryTexts: ["current practices"],
  nResults: N_RESULTS,
  whereDocument: { $not_contains: "deprecated" },
});

// $regex -- pattern matching
const regexMatch = await collection.query({
  queryTexts: ["technical papers"],
  nResults: N_RESULTS,
  whereDocument: { $regex: "deep\\s+learning" },
});

// $not_regex -- exclude by pattern
const excludePattern = await collection.query({
  queryTexts: ["final papers"],
  nResults: N_RESULTS,
  whereDocument: { $not_regex: "draft.*v[0-9]" },
});
```

**Why good:** `$contains` for simple substring search, `$regex` for pattern matching, `$not_*` variants for exclusion

**Gotcha:** `$contains` is case-sensitive -- "Neural" will not match "neural". Use `$regex` with case-insensitive patterns if needed.

---

## Compound Document Filters

```typescript
const N_RESULTS = 10;

// AND -- both substrings must appear in document
const bothTerms = await collection.query({
  queryTexts: ["AI research"],
  nResults: N_RESULTS,
  whereDocument: {
    $and: [{ $contains: "transformer" }, { $contains: "attention" }],
  },
});

// OR -- either substring matches
const eitherTerm = await collection.query({
  queryTexts: ["AI research"],
  nResults: N_RESULTS,
  whereDocument: {
    $or: [{ $contains: "transformer" }, { $contains: "recurrent" }],
  },
});
```

**Why good:** Compound document filters for multi-term matching

---

## Combined Metadata + Document Filters

Use `where` and `whereDocument` together for maximum filtering precision.

```typescript
const N_RESULTS = 10;

const results = await collection.query({
  queryTexts: ["machine learning tutorial"],
  nResults: N_RESULTS,
  where: {
    $and: [{ category: { $eq: "tutorial" } }, { year: { $gte: 2023 } }],
  },
  whereDocument: { $contains: "neural network" },
  include: ["documents", "metadatas", "distances"],
});

// Access results (nested arrays for query)
for (let i = 0; i < results.ids[0].length; i++) {
  console.log(
    results.ids[0][i],
    results.distances?.[0]?.[i],
    results.metadatas?.[0]?.[i],
  );
}
```

**Why good:** Combined metadata + document filters for precise retrieval, correct nested array access

---

## Filtering with get() (No Vector Query)

Use `get()` with filters to retrieve documents without similarity search.

```typescript
const PAGE_SIZE = 50;

// Get by metadata filter
const tutorials = await collection.get({
  where: { category: { $eq: "tutorial" } },
  limit: PAGE_SIZE,
  include: ["documents", "metadatas"],
});

// Get by document content filter
const withCode = await collection.get({
  whereDocument: { $contains: "function" },
  limit: PAGE_SIZE,
  include: ["documents"],
});

// Combined metadata + document filter
const recentTutorialsWithCode = await collection.get({
  where: {
    $and: [{ category: { $eq: "tutorial" } }, { year: { $gte: 2023 } }],
  },
  whereDocument: { $contains: "function" },
  limit: PAGE_SIZE,
  include: ["documents", "metadatas"],
});
```

**Why good:** `get()` does not require a query vector, useful for data management and non-similarity-based retrieval

---

## Delete by Metadata Filter

```typescript
// Delete all records matching a filter
await collection.delete({
  where: {
    $and: [{ status: { $eq: "archived" } }, { year: { $lt: 2020 } }],
  },
});
```

**Why good:** Bulk deletion without knowing record IDs, compound filter for precise targeting

---

## Common Filter Mistakes

```typescript
// Bad: $gt on string value (only works on numbers)
where: {
  title: {
    $gt: "A";
  }
}
// Fix: use $eq, $ne, $in, or $nin for strings

// Bad: Nested object in metadata
metadatas: [{ author: { name: "Alice", org: "Acme" } }];
// Fix: flatten to top-level keys
metadatas: [{ authorName: "Alice", authorOrg: "Acme" }];

// Bad: Mixed types in array metadata
metadatas: [{ tags: ["draft", 2024, true] }]; // INVALID: mixed types
// Fix: arrays must be homogeneous
metadatas: [{ tags: ["draft", "2024"] }]; // All strings

// Bad: $contains on scalar metadata field
where: {
  category: {
    $contains: "tut";
  }
} // INVALID: $contains is for arrays
// Fix: use $eq for scalar fields, $contains for array fields
where: {
  category: {
    $eq: "tutorial";
  }
}

// Bad: Case-sensitive surprise with whereDocument
whereDocument: {
  $contains: "Neural";
} // Won't match "neural"
// Fix: use $regex for case-insensitive matching
whereDocument: {
  $regex: "(?i)neural";
}
```

**Why bad:** Each mistake causes either a rejection or silently empty results; type-restricted operators and case sensitivity are common sources of "no results" bugs

---

_Full skill documentation: [SKILL.md](../SKILL.md) | Quick reference: [reference.md](../reference.md)_