chromadb 3.3.2 → 3.4.0

package/README.md

@@ -1,6 +1,6 @@
 ## chromadb
 
-Chroma is the open-source embedding database. Chroma makes it easy to build LLM apps by making knowledge, facts, and skills pluggable for LLMs.
+Chroma is the open-source data infrastructure for AI. Chroma makes it easy to build LLM apps by making knowledge, facts, and skills pluggable for LLMs.
 
 This package gives you a JS/TS interface to talk to a backend Chroma DB over REST.
 

package/dist/chromadb.d.ts

@@ -1,3 +1,5 @@
+import { createClient } from '@hey-api/client-fetch';
+
 type BoolInvertedIndexConfig$1 = {
     [key: string]: never;
 };
@@ -757,7 +759,6 @@ declare const registerSparseEmbeddingFunction: (name: string, fn: SparseEmbeddin
  * @returns EmbeddingFunction instance or undefined if it cannot be constructed
  */
 declare const getEmbeddingFunction: (args: {
-    collectionName: string;
     client: ChromaClient;
     efConfig?: EmbeddingFunctionConfiguration;
 }) => Promise<EmbeddingFunction | undefined>;
@@ -765,7 +766,7 @@ declare const getEmbeddingFunction: (args: {
  * Retrieves and instantiates a sparse embedding function from configuration.
  * @returns SparseEmbeddingFunction instance or undefined if it cannot be constructed
  */
-declare const getSparseEmbeddingFunction: (collectionName: string, client: ChromaClient, efConfig?: EmbeddingFunctionConfiguration) => Promise<SparseEmbeddingFunction | undefined>;
+declare const getSparseEmbeddingFunction: (client: ChromaClient, efConfig?: EmbeddingFunctionConfiguration) => Promise<SparseEmbeddingFunction | undefined>;
 /**
  * Serializes an embedding function to configuration format.
  * @param embeddingFunction - User provided embedding function
@@ -1516,6 +1517,17 @@ declare class ChromaClient {
         embeddingFunction?: EmbeddingFunction | null;
         schema?: Schema;
     }): Promise<Collection>;
+    /**
+     * Returns a lightweight collection handle for the given collection ID.
+     * The handle supports operations that don't require an embedding function
+     * or schema (e.g., add with pre-computed embeddings, get, delete, count, search).
+     * Operations that require an embedding function will throw a clear error
+     * directing you to use {@link getCollection} instead.
+     * @param id - The collection ID
+     * @returns A Collection handle for the given ID
+     * @throws ChromaValueError if tenant or database are not set on the client
+     */
+    collection(id: string): Collection;
     /**
      * Deletes a collection and all its data.
      * @param options - Deletion options
@@ -1673,6 +1685,11 @@ interface Collection {
     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
@@ -1722,6 +1739,7 @@ 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(searches: SearchLike | SearchLike[], options?: {
@@ -1738,6 +1756,209 @@ interface Collection {
      */
     getIndexingStatus(): Promise<IndexingStatus>;
 }
+/**
+ * Arguments for creating a Collection instance.
+ */
+interface CollectionArgs {
+    /** ChromaDB client instance */
+    chromaClient: ChromaClient;
+    /** HTTP API client */
+    apiClient: ReturnType<typeof createClient>;
+    /** Collection name */
+    name: string;
+    /** Collection ID */
+    id: string;
+    /** Tenant name */
+    tenant: string;
+    /** Database name */
+    database: string;
+    /** Embedding function for the collection */
+    embeddingFunction?: EmbeddingFunction;
+    /** Collection configuration */
+    configuration: CollectionConfiguration;
+    /** Optional collection metadata */
+    metadata?: CollectionMetadata;
+    /** Optional schema returned by the server */
+    schema?: Schema;
+}
+/**
+ * Implementation of CollectionAPI for ID-based collection operations.
+ * Provides core functionality for interacting with collections using their ID.
+ */
+declare class CollectionImpl implements Collection {
+    protected readonly chromaClient: ChromaClient;
+    protected readonly apiClient: ReturnType<typeof createClient>;
+    readonly id: string;
+    readonly tenant: string;
+    readonly database: string;
+    private _name;
+    private _metadata;
+    private _configuration;
+    protected _embeddingFunction: EmbeddingFunction | undefined;
+    protected _schema: Schema | undefined;
+    /**
+     * Creates a new CollectionAPIImpl instance.
+     * @param options - Configuration for the collection API
+     */
+    constructor({ chromaClient, apiClient, id, tenant, database, name, metadata, configuration, embeddingFunction, schema, }: CollectionArgs);
+    get name(): string;
+    private set name(value);
+    get configuration(): CollectionConfiguration;
+    private set configuration(value);
+    get metadata(): CollectionMetadata | undefined;
+    private set metadata(value);
+    get embeddingFunction(): EmbeddingFunction | undefined;
+    protected set embeddingFunction(embeddingFunction: EmbeddingFunction | undefined);
+    get schema(): Schema | undefined;
+    protected set schema(schema: Schema | undefined);
+    protected path(): Promise<{
+        tenant: string;
+        database: string;
+        collection_id: string;
+    }>;
+    private embed;
+    private sparseEmbed;
+    private getSparseEmbeddingTargets;
+    private applySparseEmbeddingsToMetadatas;
+    private embedKnnLiteral;
+    private embedRankLiteral;
+    private embedSearchPayload;
+    private getSchemaEmbeddingFunction;
+    private prepareRecords;
+    private validateGet;
+    private prepareQuery;
+    private validateDelete;
+    count(options?: {
+        readLevel?: ReadLevel;
+    }): Promise<number>;
+    add({ ids, embeddings, metadatas, documents, uris, }: {
+        ids: string[];
+        embeddings?: number[][];
+        metadatas?: Metadata[];
+        documents?: string[];
+        uris?: string[];
+    }): Promise<void>;
+    get<TMeta extends Metadata = Metadata>(args?: Partial<{
+        ids?: string[];
+        where?: Where;
+        limit?: number;
+        offset?: number;
+        whereDocument?: WhereDocument;
+        include?: Include[];
+    }>): Promise<GetResult<TMeta>>;
+    peek({ limit }: {
+        limit?: number;
+    }): Promise<GetResult>;
+    query<TMeta extends Metadata = Metadata>({ queryEmbeddings, queryTexts, queryURIs, ids, nResults, where, whereDocument, include, }: {
+        queryEmbeddings?: number[][];
+        queryTexts?: string[];
+        queryURIs?: string[];
+        ids?: string[];
+        nResults?: number;
+        where?: Where;
+        whereDocument?: WhereDocument;
+        include?: Include[];
+    }): Promise<QueryResult<TMeta>>;
+    search(searches: SearchLike | SearchLike[], options?: {
+        readLevel?: ReadLevel;
+    }): Promise<SearchResult>;
+    modify({ name, metadata, configuration, }: {
+        name?: string;
+        metadata?: CollectionMetadata;
+        configuration?: UpdateCollectionConfiguration;
+    }): Promise<void>;
+    fork({ name }: {
+        name: string;
+    }): Promise<Collection>;
+    forkCount(): Promise<number>;
+    update({ ids, embeddings, metadatas, documents, uris, }: {
+        ids: string[];
+        embeddings?: number[][];
+        metadatas?: Metadata[];
+        documents?: string[];
+        uris?: string[];
+    }): Promise<void>;
+    upsert({ ids, embeddings, metadatas, documents, uris, }: {
+        ids: string[];
+        embeddings?: number[][];
+        metadatas?: Metadata[];
+        documents?: string[];
+        uris?: string[];
+    }): Promise<void>;
+    delete({ ids, where, whereDocument, limit, }: {
+        ids?: string[];
+        where?: Where;
+        whereDocument?: WhereDocument;
+        limit?: number;
+    }): Promise<DeleteResult>;
+    getIndexingStatus(): Promise<IndexingStatus>;
+}
+/**
+ * Arguments for creating a CollectionHandle instance.
+ */
+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;
+}
+/**
+ * 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}.
+ */
+declare class CollectionHandle extends CollectionImpl {
+    constructor({ chromaClient, apiClient, id, tenant, database }: CollectionHandleArgs);
+    add(args: {
+        ids: string[];
+        embeddings?: number[][];
+        metadatas?: Metadata[];
+        documents?: string[];
+        uris?: string[];
+    }): Promise<void>;
+    update(args: {
+        ids: string[];
+        embeddings?: number[][];
+        metadatas?: Metadata[];
+        documents?: string[];
+        uris?: string[];
+    }): Promise<void>;
+    upsert(args: {
+        ids: string[];
+        embeddings?: number[][];
+        metadatas?: Metadata[];
+        documents?: string[];
+        uris?: string[];
+    }): Promise<void>;
+    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>>;
+    search(searches: SearchLike | SearchLike[], options?: {
+        readLevel?: ReadLevel;
+    }): Promise<SearchResult>;
+    modify(_args: {
+        name?: string;
+        metadata?: CollectionMetadata;
+        configuration?: UpdateCollectionConfiguration;
+    }): Promise<void>;
+    fork(_args: {
+        name: string;
+    }): Promise<Collection>;
+    private hasStringKnnQuery;
+}
 
 declare function withChroma(userNextConfig?: any): any;
 
@@ -1956,4 +2177,4 @@ declare class ChromaRateLimitError extends Error {
 }
 declare function createErrorByType(type: string, message: string): InvalidCollectionError | InvalidArgumentError | undefined;
 
-export { Abs, AdminClient, type AdminClientArgs, AdminCloudClient, Aggregate, type AggregateInput, type AggregateJSON, type AnyEmbeddingFunction, type BaseRecordSet, BoolInvertedIndexConfig, BoolInvertedIndexType, BoolValueType, ChromaClient, type ChromaClientArgs, ChromaClientError, ChromaConnectionError, ChromaError, ChromaForbiddenError, ChromaNotFoundError, ChromaQuotaExceededError, ChromaRateLimitError, ChromaServerError, ChromaUnauthorizedError, ChromaUniqueError, ChromaValueError, CloudClient, Cmek, CmekProvider, type Collection, type CollectionConfiguration, type CollectionMetadata, type CreateCollectionConfiguration, DOCUMENT_KEY, type DeleteResult, Div, EMBEDDING_KEY, type EmbeddingFunction, type EmbeddingFunctionClass, type EmbeddingFunctionSpace, Exp, FloatInvertedIndexConfig, FloatInvertedIndexType, FloatListValueType, FloatValueType, FtsIndexConfig, FtsIndexType, GetResult, GroupBy, type GroupByInput, type GroupByJSON, type HNSWConfiguration, IncludeEnum, type IndexConfig, type IndexingStatus, IntInvertedIndexConfig, IntInvertedIndexType, IntValueType, InvalidArgumentError, InvalidCollectionError, K, Key, type KeyFactory, Knn, type KnnOptions, Limit, type LimitInput, type LimitOptions, type ListDatabasesArgs, Log, Max, MaxK, type Metadata, type MetadataScalar, Min, MinK, Mul, type PreparedInsertRecordSet, type PreparedRecordSet, type QueryRecordSet, QueryResult, type QueryRowResult, RankExpression, type RankInput, type RankLiteral, ReadLevel, type RecordSet, Rrf, type RrfOptions, Schema, Search, type SearchInit, type SearchLike, SearchResult, type SearchResultRow, Select, type SelectInput, type SelectKeyInput, type SparseEmbeddingFunction, type SparseEmbeddingFunctionClass, type SparseVector, SparseVectorIndexConfig, type SparseVectorIndexConfigOptions, SparseVectorIndexType, SparseVectorValueType, StringInvertedIndexConfig, StringInvertedIndexType, StringValueType, Sub, Sum, type UpdateCollectionConfiguration, type UpdateHNSWConfiguration, type UpdateSPANNConfiguration, type UserIdentity, Val, ValueTypes, VectorIndexConfig, type VectorIndexConfigOptions, VectorIndexType, type Where, type WhereDocument, WhereExpression, type WhereInput, type WhereJSON, baseRecordSetFields, createErrorByType, getDefaultEFConfig, getEmbeddingFunction, getSparseEmbeddingFunction, knownEmbeddingFunctions, knownSparseEmbeddingFunctions, processCreateCollectionConfig, processUpdateCollectionConfig, recordSetFields, registerEmbeddingFunction, registerSparseEmbeddingFunction, serializeEmbeddingFunction, toSearch, withChroma };
+export { Abs, AdminClient, type AdminClientArgs, AdminCloudClient, Aggregate, type AggregateInput, type AggregateJSON, type AnyEmbeddingFunction, type BaseRecordSet, BoolInvertedIndexConfig, BoolInvertedIndexType, BoolValueType, ChromaClient, type ChromaClientArgs, ChromaClientError, ChromaConnectionError, ChromaError, ChromaForbiddenError, ChromaNotFoundError, ChromaQuotaExceededError, ChromaRateLimitError, ChromaServerError, ChromaUnauthorizedError, ChromaUniqueError, ChromaValueError, CloudClient, Cmek, CmekProvider, type Collection, type CollectionConfiguration, CollectionHandle, type CollectionMetadata, type CreateCollectionConfiguration, DOCUMENT_KEY, type DeleteResult, Div, EMBEDDING_KEY, type EmbeddingFunction, type EmbeddingFunctionClass, type EmbeddingFunctionSpace, Exp, FloatInvertedIndexConfig, FloatInvertedIndexType, FloatListValueType, FloatValueType, FtsIndexConfig, FtsIndexType, GetResult, GroupBy, type GroupByInput, type GroupByJSON, type HNSWConfiguration, IncludeEnum, type IndexConfig, type IndexingStatus, IntInvertedIndexConfig, IntInvertedIndexType, IntValueType, InvalidArgumentError, InvalidCollectionError, K, Key, type KeyFactory, Knn, type KnnOptions, Limit, type LimitInput, type LimitOptions, type ListDatabasesArgs, Log, Max, MaxK, type Metadata, type MetadataScalar, Min, MinK, Mul, type PreparedInsertRecordSet, type PreparedRecordSet, type QueryRecordSet, QueryResult, type QueryRowResult, RankExpression, type RankInput, type RankLiteral, ReadLevel, type RecordSet, Rrf, type RrfOptions, Schema, Search, type SearchInit, type SearchLike, SearchResult, type SearchResultRow, Select, type SelectInput, type SelectKeyInput, type SparseEmbeddingFunction, type SparseEmbeddingFunctionClass, type SparseVector, SparseVectorIndexConfig, type SparseVectorIndexConfigOptions, SparseVectorIndexType, SparseVectorValueType, StringInvertedIndexConfig, StringInvertedIndexType, StringValueType, Sub, Sum, type UpdateCollectionConfiguration, type UpdateHNSWConfiguration, type UpdateSPANNConfiguration, type UserIdentity, Val, ValueTypes, VectorIndexConfig, type VectorIndexConfigOptions, VectorIndexType, type Where, type WhereDocument, WhereExpression, type WhereInput, type WhereJSON, baseRecordSetFields, createErrorByType, getDefaultEFConfig, getEmbeddingFunction, getSparseEmbeddingFunction, knownEmbeddingFunctions, knownSparseEmbeddingFunctions, processCreateCollectionConfig, processUpdateCollectionConfig, recordSetFields, registerEmbeddingFunction, registerSparseEmbeddingFunction, serializeEmbeddingFunction, toSearch, withChroma };

package/dist/chromadb.legacy-esm.js

@@ -508,6 +508,22 @@ var CollectionService = class {
       }
     });
   }
+  /**
+   * Get fork count
+   * Returns the number of forks for a collection.
+   */
+  static forkCount(options) {
+    return (options.client ?? client).get({
+      security: [
+        {
+          name: "x-chroma-token",
+          type: "apiKey"
+        }
+      ],
+      url: "/api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/fork_count",
+      ...options
+    });
+  }
   /**
    * Get number of collections
    * Returns the total number of collections in a database.
@@ -1516,7 +1532,9 @@ var pythonEmbeddingFunctions = {
   default: "default-embed",
   together_ai: "together-ai",
   sentence_transformer: "sentence-transformer",
+  google_gemini: "google-gemini",
   google_genai: "google-gemini"
+  // Backward compatibility alias
 };
 var unsupportedEmbeddingFunctions = /* @__PURE__ */ new Set([
   "amazon_bedrock",
@@ -1555,32 +1573,11 @@ var registerSparseEmbeddingFunction = (name, fn) => {
   knownSparseEmbeddingFunctions.set(name, fn);
 };
 var getEmbeddingFunction = async (args) => {
-  const { collectionName, client: client2, 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 void 0;
-  }
-  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 void 0;
-  }
-  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 void 0;
-  }
-  if (efConfig.type !== "known") {
+  const { client: client2, efConfig } = args;
+  if (efConfig?.type !== "known") {
     return void 0;
   }
   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 void 0;
   }
   const packageName = pythonEmbeddingFunctions[efConfig.name] || efConfig.name;
@@ -1596,42 +1593,24 @@ var getEmbeddingFunction = async (args) => {
     } catch (error) {
     }
     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 void 0;
     }
   }
-  let constructorConfig = efConfig.type === "known" ? efConfig.config : {};
+  const constructorConfig = efConfig.config ?? {};
   try {
     if (embeddingFunction.buildFromConfig) {
       return embeddingFunction.buildFromConfig(constructorConfig, client2);
     }
-    console.warn(
-      `Embedding function ${packageName} does not define a 'buildFromConfig' function. 'add' and 'query' will fail unless you provide them embeddings directly.`
-    );
     return void 0;
   } 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 void 0;
   }
 };
-var getSparseEmbeddingFunction = async (collectionName, client2, efConfig) => {
-  if (!efConfig) {
-    return void 0;
-  }
-  if (efConfig.type === "legacy") {
-    return void 0;
-  }
-  if (efConfig.type !== "known") {
+var getSparseEmbeddingFunction = async (client2, efConfig) => {
+  if (efConfig?.type !== "known") {
     return void 0;
   }
   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 void 0;
   }
   const packageName = pythonSparseEmbeddingFunctions[efConfig.name] || efConfig.name;
@@ -1644,25 +1623,16 @@ var getSparseEmbeddingFunction = async (collectionName, client2, efConfig) => {
     } catch (error) {
     }
     if (!sparseEmbeddingFunction) {
-      console.warn(
-        `Collection ${collectionName} was created with the ${packageName} sparse embedding function. However, the @chroma-core/${packageName} package is not installed.`
-      );
       return void 0;
     }
   }
-  let constructorConfig = efConfig.type === "known" ? efConfig.config : {};
+  const constructorConfig = efConfig.config ?? {};
   try {
     if (sparseEmbeddingFunction.buildFromConfig) {
       return sparseEmbeddingFunction.buildFromConfig(constructorConfig, client2);
     }
-    console.warn(
-      `Sparse embedding function ${packageName} does not define a 'buildFromConfig' function.`
-    );
     return void 0;
   } catch (e) {
-    console.warn(
-      `Sparse embedding function ${packageName} failed to build with config: ${constructorConfig}. Error: ${e}`
-    );
     return void 0;
   }
 };
@@ -1788,7 +1758,6 @@ var processUpdateCollectionConfig = async ({
     );
   }
   const embeddingFunction = currentEmbeddingFunction || await getEmbeddingFunction({
-    collectionName,
     client: client2,
     efConfig: currentConfiguration.embeddingFunction ?? void 0
   });
@@ -3886,7 +3855,6 @@ var Schema = class _Schema {
       spann: json.spann ? cloneObject(json.spann) : null
     });
     config.embeddingFunction = await getEmbeddingFunction({
-      collectionName: "schema deserialization",
       client: client2,
       efConfig: json.embedding_function
     });
@@ -3901,7 +3869,6 @@ var Schema = class _Schema {
       bm25: typeof json.bm25 === "boolean" ? json.bm25 : null
     });
     const embeddingFunction = await getSparseEmbeddingFunction(
-      "schema deserialization",
       client2,
       json.embedding_function
     ) ?? config.embeddingFunction ?? void 0;
@@ -3987,7 +3954,7 @@ var CollectionImpl = class _CollectionImpl {
     const embeddingFunction = this._embeddingFunction ?? this.getSchemaEmbeddingFunction();
     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.`
       );
     }
     if (isQuery && embeddingFunction.generateForQueries) {
@@ -4048,10 +4015,8 @@ var CollectionImpl = class _CollectionImpl {
           }
           if (index < documentsList.length) {
             const doc = documentsList[index];
-            if (typeof doc === "string") {
-              inputs.push(doc);
-              positions.push(index);
-            }
+            inputs.push(doc);
+            positions.push(index);
           }
         });
         if (inputs.length === 0) {
@@ -4471,6 +4436,13 @@ var CollectionImpl = class _CollectionImpl {
       configuration: data.configuration_json
     });
   }
+  async forkCount() {
+    const { data } = await CollectionService.forkCount({
+      client: this.apiClient,
+      path: await this.path()
+    });
+    return data.count;
+  }
   async update({
     ids,
     embeddings,
@@ -4557,6 +4529,75 @@ var CollectionImpl = class _CollectionImpl {
     return data;
   }
 };
+var 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.";
+var HANDLE_NOT_SUPPORTED_ERROR = "is not supported on a collection obtained via client.collection(id). Use client.getCollection() to get a full collection instance.";
+var CollectionHandle = class extends CollectionImpl {
+  constructor({ chromaClient, apiClient, id, tenant, database }) {
+    super({
+      chromaClient,
+      apiClient,
+      id,
+      tenant,
+      database,
+      name: "",
+      configuration: {}
+    });
+  }
+  async add(args) {
+    if (!args.embeddings) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.add(args);
+  }
+  async update(args) {
+    if (!args.embeddings && args.documents) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.update(args);
+  }
+  async upsert(args) {
+    if (!args.embeddings) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.upsert(args);
+  }
+  async query(args) {
+    if (!args.queryEmbeddings) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.query(args);
+  }
+  async search(searches, options) {
+    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);
+  }
+  async modify(_args) {
+    throw new ChromaValueError(`modify() ${HANDLE_NOT_SUPPORTED_ERROR}`);
+  }
+  async fork(_args) {
+    throw new ChromaValueError(`fork() ${HANDLE_NOT_SUPPORTED_ERROR}`);
+  }
+  hasStringKnnQuery(obj) {
+    if (!obj || typeof obj !== "object") return false;
+    if (Array.isArray(obj)) {
+      return obj.some((item) => this.hasStringKnnQuery(item));
+    }
+    const record = obj;
+    if ("$knn" in record && isPlainObject(record.$knn)) {
+      const knn = record.$knn;
+      if (typeof knn.query === "string") return true;
+    }
+    return Object.values(record).some(
+      (value) => this.hasStringKnnQuery(value)
+    );
+  }
+};
 
 // src/next.ts
 function withChroma(userNextConfig = {}) {
@@ -4918,7 +4959,6 @@ var ChromaClient = class {
         );
         const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(schema);
         const resolvedEmbeddingFunction = await getEmbeddingFunction({
-          collectionName: collection.name,
           client: this,
           efConfig: collection.configuration_json.embedding_function ?? void 0
         }) ?? schemaEmbeddingFunction;
@@ -4988,7 +5028,6 @@ var ChromaClient = class {
     );
     const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(serverSchema);
     const resolvedEmbeddingFunction = embeddingFunction ?? await getEmbeddingFunction({
-      collectionName: data.name,
       client: this,
       efConfig: data.configuration_json.embedding_function ?? void 0
     }) ?? schemaEmbeddingFunction;
@@ -5024,7 +5063,6 @@ var ChromaClient = class {
     const schema = await Schema.deserializeFromJSON(data.schema ?? null, this);
     const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(schema);
     const resolvedEmbeddingFunction = embeddingFunction ?? await getEmbeddingFunction({
-      collectionName: data.name,
       client: this,
       efConfig: data.configuration_json.embedding_function ?? void 0
     }) ?? schemaEmbeddingFunction;
@@ -5055,7 +5093,6 @@ var ChromaClient = class {
     const schema = await Schema.deserializeFromJSON(data.schema ?? null, this);
     const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(schema);
     const resolvedEmbeddingFunction = await getEmbeddingFunction({
-      collectionName: data.name,
       efConfig: data.configuration_json.embedding_function ?? void 0,
       client: this
     }) ?? schemaEmbeddingFunction;
@@ -5131,7 +5168,6 @@ var ChromaClient = class {
     );
     const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(serverSchema);
     const resolvedEmbeddingFunction = embeddingFunction ?? await getEmbeddingFunction({
-      collectionName: name,
       efConfig: data.configuration_json.embedding_function ?? void 0,
       client: this
     }) ?? schemaEmbeddingFunction;
@@ -5148,6 +5184,30 @@ var ChromaClient = class {
       schema: serverSchema
     });
   }
+  /**
+   * Returns a lightweight collection handle for the given collection ID.
+   * The handle supports operations that don't require an embedding function
+   * or schema (e.g., add with pre-computed embeddings, get, delete, count, search).
+   * Operations that require an embedding function will throw a clear error
+   * directing you to use {@link getCollection} instead.
+   * @param id - The collection ID
+   * @returns A Collection handle for the given ID
+   * @throws ChromaValueError if tenant or database are not set on the client
+   */
+  collection(id) {
+    if (!this._tenant || !this._database) {
+      throw new ChromaValueError(
+        "tenant and database must be set on the client before calling collection(). Provide them in the ChromaClient constructor or use getCollection() instead."
+      );
+    }
+    return new CollectionHandle({
+      chromaClient: this,
+      apiClient: this.apiClient,
+      id,
+      tenant: this._tenant,
+      database: this._database
+    });
+  }
   /**
    * Deletes a collection and all its data.
    * @param options - Deletion options
@@ -5284,6 +5344,7 @@ export {
   CloudClient,
   Cmek,
   CmekProvider,
+  CollectionHandle,
   DOCUMENT_KEY,
   Div,
   EMBEDDING_KEY,