Chromadb JS API Cheatsheet

chromadb-cheatsheet.md

Chromadb Javascript API Cheatsheet

💡 NOTE This is a quick cheatsheet of the API. For full API docs, refer to the JS and Python docs in the sidebar.

Run the backend

Run chroma run --path /db_path to run the Chroma backend as a standalone server on your local computer.

Initialize client - JS

import { ChromaClient } from "chromadb";
const client = new ChromaClient();

Methods on Client

Methods related to Collections

COLLECTION NAMING

Collections are similar to AWS s3 buckets in their naming requirements because they are used in URLs in the REST API. Here's the full list.

// list all collections
await client.listCollections();

// make a new collection
const collection = await client.createCollection({ name: "testname" });

// get an existing collection
const collection = await client.getCollection({ name: "testname" });

// delete a collection
await client.deleteCollection({ name: "testname" });

Utility methods

// resets entire database - this *cant* be undone!
await client.reset();

Methods on Collection

// get the number of items in a collection
await collection.count()

// add new items to a collection
// either one at a time
await collection.add({
    ids: "id1",
    embeddings: [1.5, 2.9, 3.4],
    metadatas: {"source": "my_source"},
    documents: "This is a document",
})
// or many, up to 100k+!
await collection.add({
    ids: ["uri9", "uri10"],
    embeddings: [[1.5, 2.9, 3.4], [9.8, 2.3, 2.9]],
    metadatas: [{"style": "style1"}, {"style": "style2"}],
    documents: ["This is a document", 'that is a document']
})
// including just documents
await collection.add({
    ids: ["uri9", "uri10"],
    metadatas: [{"style": "style1"}, {"style": "style2"}],
    documents: ["doc1000101", "doc288822"],
})
// or use upsert, so records will be updated if they already exist
// (instead of throwing an error)
await collection.upsert({
    ids: "id1",
    embeddings: [1.5, 2.9, 3.4],
    metadatas: {"source": "my_source"},
    documents: "This is a document",
})

// get items from a collection
await collection.get()

// convenience, get first 5 items from a collection
await collection.peek()

// do nearest neighbor search to find similar embeddings or documents, supports filtering
await collection.query({
    queryEmbeddings=[[1.1, 2.3, 3.2], [5.1, 4.3, 2.2]],
    nResults=2,
    where={"style": "style2"}
})

// delete items
await collection.delete()