Move off Chroma Cloud before it goes read-only on November 22

---
name: chroma-cloud-to-bonsai
description: Migrate an application from Chroma Cloud to Bonsai managed OpenSearch. Inventories Chroma collections, creates a k-NN index with disk-based vectors, exports and bulk-loads records with their existing embeddings, validates counts and result overlap, and rewrites Chroma calls in the codebase to OpenSearch. Use when asked to move off Chroma Cloud, migrate Chroma to OpenSearch or Bonsai, or replace chromadb in an app.
---

# Migrate from Chroma Cloud to Bonsai (OpenSearch)

Chroma Cloud goes read-only on November 22, 2026 (no add, update, upsert or delete) and stops serving reads on December 22, 2026. Work in the order below, report after each step, and ask before anything that writes to a production cluster.

## Rules

- Read credentials from environment variables. Never print, log or commit them.
- Never delete or modify data in Chroma. This migration only reads from it.
- Keep the embedding model. Existing vectors are exported as they are; query vectors must come from the same model.
- Test against a Bonsai Sandbox cluster with a sample first, then run the full load on the production plan.
- If a step fails twice, stop and report what happened instead of improvising.

## Inputs

Ask the user for anything missing:

- `CHROMA_API_KEY`, `CHROMA_TENANT`, `CHROMA_DATABASE` for Chroma Cloud.
- `BONSAI_URL`: the full access URL from the Bonsai dashboard (`https://user:pass@host`). New accounts can create a free Sandbox cluster at https://app.bonsai.io/signup?utm_source=bonsai-labs&utm_campaign=%2Flabs%2Fchroma-cloud-migration%2F&utm_content=agent-skill
- Python 3.9+ with `pip install chromadb opensearch-py`.

## 1. Inventory Chroma

Write and run a read-only script that connects with `chromadb.CloudClient(tenant=..., database=..., api_key=...)` and, for every collection, reports:

- name and `collection.count()`
- embedding dimension (length of the first embedding from `collection.get(limit=1, include=["embeddings"])`)
- distance metric, from `collection.configuration` (`hnsw.space`) or the legacy `collection.metadata["hnsw:space"]`; Chroma's default is `l2`
- metadata keys and value types, from a sample of about 1,000 records
- average document and metadata size in bytes, from the same sample

Print a table, then the totals. Tell the user they can check the plan size at https://bonsai.io/labs/chroma-cloud-migration/#calculator. Sandbox clusters hold about 125 MB and 35,000 documents, enough for a sample of a few thousand records at 1536 dimensions.

## 2. Find Chroma in the codebase

Search for `chromadb`, `CloudClient`, `HttpClient`, `get_or_create_collection`, `.add(`, `.upsert(`, `.update(`, `.delete(`, `.query(`, `.get(`, `where=` and `where_document=`. List every call site with its file, line and the operation. Note any LangChain or LlamaIndex Chroma vector store wrappers, which have OpenSearch equivalents (`OpenSearchVectorSearch`, `OpensearchVectorStore`).

## 3. Create the index

Create one index per embedding dimension and keep the Chroma collection name in a `collection` keyword field. Hundreds of small indexes would each use shards, and Bonsai plans limit shard count. On a Sandbox cluster, set `"number_of_shards": 1`.

Map the distance metric to `space_type`: `l2` to `l2`, `cosine` to `cosinesimil`, `ip` to `innerproduct`. If the cluster rejects the space type, show the error to the user before trying anything else.

```json
PUT chroma-1536
{
  "settings": {
    "index": { "knn": true, "knn.derived_source.enabled": true, "number_of_shards": 1 }
  },
  "mappings": {
    "dynamic_templates": [
      {
        "metadata_strings": {
          "path_match": "metadata.*",
          "match_mapping_type": "string",
          "mapping": { "type": "keyword" }
        }
      }
    ],
    "properties": {
      "embedding": {
        "type": "knn_vector",
        "dimension": 1536,
        "mode": "on_disk",
        "compression_level": "32x",
        "method": {
          "name": "hnsw",
          "engine": "faiss",
          "space_type": "innerproduct",
          "parameters": { "ef_construction": 256, "m": 16 }
        }
      },
      "document": { "type": "text" },
      "metadata": { "type": "object" },
      "collection": { "type": "keyword" }
    }
  }
}
```

`mode: on_disk` with `compression_level: 32x` builds the HNSW graph over 1-bit quantized vectors in memory and rescores top candidates with the full-precision vectors on disk. It needs OpenSearch 2.19 or later; check with `GET /`. If a metadata key holds different types across records, map it explicitly before loading.

## 4. Export and bulk load

Write a script that pages through each collection and streams records into the index with `opensearchpy.helpers.bulk`:

- `collection.get(include=["embeddings", "documents", "metadatas"], limit=500, offset=offset)`, until a page returns no ids
- document `_id` = the Chroma id; `_source` = `embedding`, `document`, `metadata` (use `{}` for `None`), `collection`
- write each vector component as `float(f"{x:.9g}")`. Chroma returns float32, and 9 significant digits round-trip a float32 exactly, so bulk requests stay much smaller than Python's default 17 digits
- a `--limit` flag for sample runs, and a checkpoint file with the last offset per collection so a failed run can resume
- `raise_on_error=False`; print the first few errors and the totals at the end

Run it with `--limit 2000` against the Sandbox cluster first, then run steps 5 and 6 against that sample before the full load.

## 5. Validate

- Compare `collection.count()` with `GET <index>/_count` filtered by `collection` for every collection.
- Take 200 recent or representative queries. If the app logs no queries, use the documents of 200 random records as queries. Run each against Chroma (`n_results=10`) and OpenSearch (`k=10`) with the same filters, and report the average overlap of the top 10 ids.
- If the overlap is low, check the space type first. Report the numbers to the user instead of changing compression or engine settings on your own.

## 6. Rewrite the application code

Replace each call site from step 2. Keep a thin wrapper module so the rest of the code does not import the OpenSearch client directly.

| Chroma                                                | OpenSearch                                               |
| ----------------------------------------------------- | -------------------------------------------------------- |
| `collection.add` / `upsert`                           | `_bulk` `index` actions with `_id` = Chroma id           |
| `collection.update`                                   | `_bulk` `update` actions with a partial `doc`            |
| `collection.delete(ids=...)`                          | `_bulk` `delete` actions                                 |
| `collection.delete(where=...)`                        | `_delete_by_query` with the translated filter            |
| `collection.get(ids=...)`                             | `_mget`                                                  |
| `collection.query(query_embeddings=[v], n_results=k)` | `knn` query on `embedding` with `"k": k` and `"size": k` |
| `collection.count()`                                  | `_count` with a `term` on `collection`                   |

Every query and count must include `{ "term": { "collection": "<name>" } }` in its filter.

Filter translation, applied inside the `knn` query's `filter` (a `bool` query):

| Chroma `where` / `where_document` | OpenSearch                                                               |
| --------------------------------- | ------------------------------------------------------------------------ |
| `{"k": v}` or `{"k": {"$eq": v}}` | `term` on `metadata.k`                                                   |
| `$ne`                             | `bool.must_not` with `term`                                              |
| `$gt`, `$gte`, `$lt`, `$lte`      | `range`                                                                  |
| `$in`, `$nin`                     | `terms`, or `must_not` with `terms`                                      |
| `$and`, `$or`                     | `bool.filter`, `bool.should` with `minimum_should_match: 1`              |
| `$contains`, `$not_contains`      | `match_phrase` on `document`, or `must_not` with it                      |
| `$regex`, `$not_regex`            | `regexp` on `document`; warn the user that this is slow on large indexes |

Chroma returns distances (lower is closer) and OpenSearch returns scores (higher is closer). Find any code that sorts or thresholds on distance and adjust it. Ask before changing a threshold value.

## 7. Cut over

1. Before November 22, write to both Chroma and Bonsai, or pause writes, so the two stay in step.
2. Run the full load on the production plan, then step 5 again on the full data.
3. Switch reads to Bonsai behind a config flag, and keep the Chroma read path until December 22 in case you need to compare.
4. Summarize for the user what changed, the validation numbers, and anything left to do.

Help from a Bonsai search engineer: https://bonsai.io/labs/chroma-cloud-migration/#contact