chromadb 3.3.3 → 3.4.1

package/dist/cjs/chromadb.cjs

@@ -54,6 +54,7 @@ __export(src_exports, {
   CloudClient: () => CloudClient,
   Cmek: () => Cmek,
   CmekProvider: () => CmekProvider,
+  CollectionHandle: () => CollectionHandle,
   DOCUMENT_KEY: () => DOCUMENT_KEY,
   Div: () => Div,
   EMBEDDING_KEY: () => EMBEDDING_KEY,
@@ -627,6 +628,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.
@@ -4539,6 +4556,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,
@@ -4625,6 +4649,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 = {}) {
@@ -5211,6 +5304,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
@@ -5348,6 +5465,7 @@ var AdminCloudClient = class extends AdminClient {
   CloudClient,
   Cmek,
   CmekProvider,
+  CollectionHandle,
   DOCUMENT_KEY,
   Div,
   EMBEDDING_KEY,