chromadb 3.3.2 → 3.4.0

package/src/collection.ts

@@ -45,7 +45,7 @@ import {
   processUpdateCollectionConfig,
   UpdateCollectionConfiguration,
 } from "./collection-configuration";
-import { SearchLike, SearchResult, toSearch } from "./execution/expression";
+import { SearchLike, SearchResult, toSearch } from "./execution";
 import { isPlainObject } from "./execution/expression/common";
 import { Schema, EMBEDDING_KEY, DOCUMENT_KEY } from "./schema";
 import type { SparseVectorIndexConfig } from "./schema";
@@ -167,6 +167,11 @@ export interface Collection {
    * @returns Promise resolving to the new Collection instance
    */
   fork({ name }: { name: string }): Promise<Collection>;
+  /**
+   * Gets the number of forks for this collection.
+   * @returns Promise resolving to the number of forks
+   */
+  forkCount(): Promise<number>;
   /**
    * Updates existing records in the collection.
    * @param args - Record data to update
@@ -216,6 +221,7 @@ export interface Collection {
   /**
    * Performs hybrid search on the collection using expression builders.
    * @param searches - Single search payload or array of payloads
+   * @param options
    * @returns Promise resolving to column-major search results
    */
   search(
@@ -366,7 +372,9 @@ export class CollectionImpl implements Collection {
 
     if (!embeddingFunction) {
       throw new ChromaValueError(
-        "Embedding function must be defined for operations requiring embeddings.",
+        `No embedding function found for collection '${this._name}'. ` +
+          "You can either provide embeddings directly, or ensure the appropriate " +
+          "embedding function package (e.g. @chroma-core/default-embed) is installed.",
       );
     }
 
@@ -459,10 +467,8 @@ export class CollectionImpl implements Collection {
           // Get document at this position
           if (index < documentsList.length) {
             const doc = documentsList[index];
-            if (typeof doc === "string") {
-              inputs.push(doc);
-              positions.push(index);
-            }
+            inputs.push(doc);
+            positions.push(index);
           }
         });
 
@@ -1027,6 +1033,15 @@ export class CollectionImpl implements Collection {
     });
   }
 
+  public async forkCount(): Promise<number> {
+    const { data } = await CollectionService.forkCount({
+      client: this.apiClient,
+      path: await this.path(),
+    });
+
+    return data.count;
+  }
+
   public async update({
     ids,
     embeddings,
@@ -1140,3 +1155,144 @@ export class CollectionImpl implements Collection {
     return data;
   }
 }
+
+/**
+ * Arguments for creating a CollectionHandle instance.
+ */
+export interface CollectionHandleArgs {
+  /** ChromaDB client instance */
+  chromaClient: ChromaClient;
+  /** HTTP API client */
+  apiClient: ReturnType<typeof createClient>;
+  /** Collection ID */
+  id: string;
+  /** Tenant name */
+  tenant: string;
+  /** Database name */
+  database: string;
+}
+
+const HANDLE_EMBEDDING_ERROR =
+  "This operation requires an embedding function, which is not available on " +
+  "a collection obtained via client.collection(id). Provide pre-computed " +
+  "embeddings directly, or use client.getCollection() to get a full " +
+  "collection with embedding support.";
+
+const HANDLE_NOT_SUPPORTED_ERROR =
+  "is not supported on a collection obtained via client.collection(id). " +
+  "Use client.getCollection() to get a full collection instance.";
+
+/**
+ * A lightweight collection handle that holds only the collection ID and
+ * client context. Supports operations that don't require an embedding
+ * function or schema. Obtained via {@link ChromaClient.collection}.
+ */
+export class CollectionHandle extends CollectionImpl {
+  constructor({ chromaClient, apiClient, id, tenant, database }: CollectionHandleArgs) {
+    super({
+      chromaClient,
+      apiClient,
+      id,
+      tenant,
+      database,
+      name: "",
+      configuration: {},
+    });
+  }
+
+  public override async add(args: {
+    ids: string[];
+    embeddings?: number[][];
+    metadatas?: Metadata[];
+    documents?: string[];
+    uris?: string[];
+  }): Promise<void> {
+    if (!args.embeddings) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.add(args);
+  }
+
+  public override async update(args: {
+    ids: string[];
+    embeddings?: number[][];
+    metadatas?: Metadata[];
+    documents?: string[];
+    uris?: string[];
+  }): Promise<void> {
+    if (!args.embeddings && args.documents) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.update(args);
+  }
+
+  public override async upsert(args: {
+    ids: string[];
+    embeddings?: number[][];
+    metadatas?: Metadata[];
+    documents?: string[];
+    uris?: string[];
+  }): Promise<void> {
+    if (!args.embeddings) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.upsert(args);
+  }
+
+  public override async query<TMeta extends Metadata = Metadata>(args: {
+    queryEmbeddings?: number[][];
+    queryTexts?: string[];
+    queryURIs?: string[];
+    ids?: string[];
+    nResults?: number;
+    where?: Where;
+    whereDocument?: WhereDocument;
+    include?: Include[];
+  }): Promise<QueryResult<TMeta>> {
+    if (!args.queryEmbeddings) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.query(args);
+  }
+
+  public override async search(
+    searches: SearchLike | SearchLike[],
+    options?: { readLevel?: ReadLevel },
+  ): Promise<SearchResult> {
+    const items = Array.isArray(searches) ? searches : [searches];
+    for (const search of items) {
+      const payload = toSearch(search).toPayload();
+      if (this.hasStringKnnQuery(payload.rank)) {
+        throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+      }
+    }
+    return super.search(searches, options);
+  }
+
+  public override async modify(_args: {
+    name?: string;
+    metadata?: CollectionMetadata;
+    configuration?: UpdateCollectionConfiguration;
+  }): Promise<void> {
+    throw new ChromaValueError(`modify() ${HANDLE_NOT_SUPPORTED_ERROR}`);
+  }
+
+  public override async fork(_args: { name: string }): Promise<Collection> {
+    throw new ChromaValueError(`fork() ${HANDLE_NOT_SUPPORTED_ERROR}`);
+  }
+
+  private hasStringKnnQuery(obj: unknown): boolean {
+    if (!obj || typeof obj !== "object") return false;
+    if (Array.isArray(obj)) {
+      return obj.some((item) => this.hasStringKnnQuery(item));
+    }
+    const record = obj as Record<string, unknown>;
+    if ("$knn" in record && isPlainObject(record.$knn)) {
+      const knn = record.$knn as Record<string, unknown>;
+      if (typeof knn.query === "string") return true;
+    }
+    return Object.values(record).some((value) =>
+      this.hasStringKnnQuery(value),
+    );
+  }
+}

package/src/embedding-function.ts

@@ -1,6 +1,5 @@
 import { EmbeddingFunctionConfiguration, SparseVector } from "./api";
 import { ChromaValueError } from "./errors";
-import { DefaultEmbeddingFunction } from "@chroma-core/default-embed";
 import { ChromaClient } from "./chroma-client";
 
 /**
@@ -140,7 +139,8 @@ const pythonEmbeddingFunctions: Record<string, string> = {
   default: "default-embed",
   together_ai: "together-ai",
   sentence_transformer: "sentence-transformer",
-  google_genai: "google-gemini",
+  google_gemini: "google-gemini",
+  google_genai: "google-gemini", // Backward compatibility alias
 };
 
 const unsupportedEmbeddingFunctions: Set<string> = new Set([
@@ -225,41 +225,16 @@ export const registerSparseEmbeddingFunction = (
  * @returns EmbeddingFunction instance or undefined if it cannot be constructed
  */
 export const getEmbeddingFunction = async (args: {
-  collectionName: string;
   client: ChromaClient;
   efConfig?: EmbeddingFunctionConfiguration;
 }) => {
-  const { collectionName, client, efConfig } = args;
+  const { client, efConfig } = args;
 
-  if (!efConfig) {
-    console.warn(
-      `No embedding function configuration found for collection ${collectionName}. 'add' and 'query' will fail unless you provide them embeddings directly.`,
-    );
-    return undefined;
-  }
-
-  if (efConfig.type === "legacy") {
-    console.warn(
-      `No embedding function configuration found for collection ${collectionName}. 'add' and 'query' will fail unless you provide them embeddings directly.`,
-    );
-    return undefined;
-  }
-
-  if (efConfig.type === "unknown") {
-    console.warn(
-      `Unknown embedding function configuration for collection ${collectionName}. 'add' and 'query' will fail unless you provide them embeddings directly.`,
-    );
-    return undefined;
-  }
-
-  if (efConfig.type !== "known") {
+  if (efConfig?.type !== "known") {
     return undefined;
   }
 
   if (unsupportedEmbeddingFunctions.has(efConfig.name)) {
-    console.warn(
-      `Embedding function ${efConfig.name} is not supported in the JS/TS SDK. 'add' and 'query' will fail unless you provide them embeddings directly.`,
-    );
     return undefined;
   }
 
@@ -276,33 +251,23 @@ export const getEmbeddingFunction = async (args: {
       await import(fullPackageName);
       embeddingFunction = knownEmbeddingFunctions.get(packageName);
     } catch (error) {
-      // Dynamic loading failed, proceed with warning
+      // Dynamic loading failed
     }
 
     if (!embeddingFunction) {
-      console.warn(
-        `Collection ${collectionName} was created with the ${packageName} embedding function. However, the @chroma-core/${packageName} package is not installed. 'add' and 'query' will fail unless you provide them embeddings directly, or install the @chroma-core/${packageName} package.`,
-      );
       return undefined;
     }
   }
 
-  let constructorConfig: Record<string, any> =
-    efConfig.type === "known" ? (efConfig.config as Record<string, any>) : {};
+  const constructorConfig: Record<string, any> =
+    (efConfig.config as Record<string, any>) ?? {};
 
   try {
     if (embeddingFunction.buildFromConfig) {
       return embeddingFunction.buildFromConfig(constructorConfig, client);
     }
-
-    console.warn(
-      `Embedding function ${packageName} does not define a 'buildFromConfig' function. 'add' and 'query' will fail unless you provide them embeddings directly.`,
-    );
     return undefined;
   } catch (e) {
-    console.warn(
-      `Embedding function ${packageName} failed to build with config: ${constructorConfig}. 'add' and 'query' will fail unless you provide them embeddings directly. Error: ${e}`,
-    );
     return undefined;
   }
 };
@@ -312,26 +277,14 @@ export const getEmbeddingFunction = async (args: {
  * @returns SparseEmbeddingFunction instance or undefined if it cannot be constructed
  */
 export const getSparseEmbeddingFunction = async (
-  collectionName: string,
   client: ChromaClient,
   efConfig?: EmbeddingFunctionConfiguration,
 ) => {
-  if (!efConfig) {
-    return undefined;
-  }
-
-  if (efConfig.type === "legacy") {
-    return undefined;
-  }
-
-  if (efConfig.type !== "known") {
+  if (efConfig?.type !== "known") {
     return undefined;
   }
 
   if (unsupportedSparseEmbeddingFunctions.has(efConfig.name)) {
-    console.warn(
-      "Embedding function ${efConfig.name} is not supported in the JS/TS SDK. 'add' and 'query' will fail unless you provide them embeddings directly.",
-    );
     return undefined;
   }
 
@@ -345,33 +298,23 @@ export const getSparseEmbeddingFunction = async (
       await import(fullPackageName);
       sparseEmbeddingFunction = knownSparseEmbeddingFunctions.get(packageName);
     } catch (error) {
-      // Dynamic loading failed, proceed with warning
+      // Dynamic loading failed
     }
 
     if (!sparseEmbeddingFunction) {
-      console.warn(
-        `Collection ${collectionName} was created with the ${packageName} sparse embedding function. However, the @chroma-core/${packageName} package is not installed.`,
-      );
       return undefined;
     }
   }
 
-  let constructorConfig: Record<string, any> =
-    efConfig.type === "known" ? (efConfig.config as Record<string, any>) : {};
+  const constructorConfig: Record<string, any> =
+    (efConfig.config as Record<string, any>) ?? {};
 
   try {
     if (sparseEmbeddingFunction.buildFromConfig) {
       return sparseEmbeddingFunction.buildFromConfig(constructorConfig, client);
     }
-
-    console.warn(
-      `Sparse embedding function ${packageName} does not define a 'buildFromConfig' function.`,
-    );
     return undefined;
   } catch (e) {
-    console.warn(
-      `Sparse embedding function ${packageName} failed to build with config: ${constructorConfig}. Error: ${e}`,
-    );
     return undefined;
   }
 };

package/src/index.ts

@@ -6,7 +6,7 @@
 // Apply Deno compatibility patch
 import "./deno";
 
-export { Collection } from "./collection";
+export { Collection, CollectionHandle } from "./collection";
 export { withChroma } from "./next";
 export * from "./types";
 export * from "./admin-client";

package/src/schema.ts

@@ -1285,7 +1285,6 @@ export class Schema {
     });
 
     config.embeddingFunction = await getEmbeddingFunction({
-      collectionName: "schema deserialization",
       client,
       efConfig: json.embedding_function as EmbeddingFunctionConfiguration,
     });
@@ -1307,7 +1306,6 @@ export class Schema {
 
     const embeddingFunction =
       (await getSparseEmbeddingFunction(
-        "schema deserialization",
         client,
         json.embedding_function as EmbeddingFunctionConfiguration,
       )) ??