chromadb 3.3.3 → 3.4.1

package/dist/cjs/chromadb.d.cts

@@ -1,3 +1,5 @@
+import { createClient } from '@hey-api/client-fetch';
+
 type BoolInvertedIndexConfig$1 = {
     [key: string]: never;
 };
@@ -1515,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
@@ -1672,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
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromadb",
-  "version": "3.3.3",
+  "version": "3.4.1",
   "description": "A JavaScript interface for chroma",
   "keywords": [
     "chroma",
@@ -60,11 +60,11 @@
     "@chroma-core/default-embed": "^0.1.9"
   },
   "optionalDependencies": {
-    "chromadb-js-bindings-darwin-arm64": "^1.3.1",
-    "chromadb-js-bindings-darwin-x64": "^1.3.1",
-    "chromadb-js-bindings-linux-arm64-gnu": "^1.3.1",
-    "chromadb-js-bindings-linux-x64-gnu": "^1.3.1",
-    "chromadb-js-bindings-win32-x64-msvc": "^1.3.1"
+    "chromadb-js-bindings-darwin-arm64": "^1.3.2",
+    "chromadb-js-bindings-darwin-x64": "^1.3.2",
+    "chromadb-js-bindings-linux-arm64-gnu": "^1.3.2",
+    "chromadb-js-bindings-linux-x64-gnu": "^1.3.2",
+    "chromadb-js-bindings-win32-x64-msvc": "^1.3.2"
   },
   "engines": {
     "node": ">=20"

package/src/api/sdk.gen.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 import type { Options as ClientOptions, TDataShape, Client } from '@hey-api/client-fetch';
-import type { GetUserIdentityData, GetUserIdentityResponse2, GetUserIdentityError, GetCollectionByCrnData, GetCollectionByCrnResponse, GetCollectionByCrnError, HealthcheckData, HealthcheckResponse, HealthcheckError, HeartbeatData, HeartbeatResponse2, HeartbeatError, PreFlightChecksData, PreFlightChecksResponse, PreFlightChecksError, ResetData, ResetResponse, ResetError, CreateTenantData, CreateTenantResponse2, CreateTenantError, GetTenantData, GetTenantResponse2, GetTenantError, UpdateTenantData, UpdateTenantResponse2, UpdateTenantError, ListDatabasesData, ListDatabasesResponse, ListDatabasesError, CreateDatabaseData, CreateDatabaseResponse2, CreateDatabaseError, DeleteDatabaseData, DeleteDatabaseResponse2, DeleteDatabaseError, GetDatabaseData, GetDatabaseResponse, GetDatabaseError, ListCollectionsData, ListCollectionsResponse, ListCollectionsError, CreateCollectionData, CreateCollectionResponse, CreateCollectionError, DeleteCollectionData, DeleteCollectionResponse2, DeleteCollectionError, GetCollectionData, GetCollectionResponse, GetCollectionError, UpdateCollectionData, UpdateCollectionResponse2, UpdateCollectionError, CollectionAddData, CollectionAddResponse, DetachFunctionData, DetachFunctionResponse2, DetachFunctionError, CollectionCountData, CollectionCountResponse, CollectionCountError, CollectionDeleteData, CollectionDeleteResponse, CollectionDeleteError, ForkCollectionData, ForkCollectionResponse, ForkCollectionError, AttachFunctionData, AttachFunctionResponse2, AttachFunctionError, GetAttachedFunctionData, GetAttachedFunctionResponse2, GetAttachedFunctionError, CollectionGetData, CollectionGetResponse, CollectionGetError, IndexingStatusData, IndexingStatusResponse, IndexingStatusError, CollectionQueryData, CollectionQueryResponse, CollectionQueryError, CollectionSearchData, CollectionSearchResponse, CollectionSearchError, CollectionUpdateData, CollectionUpdateResponse, CollectionUpsertData, CollectionUpsertResponse, CollectionUpsertError, CountCollectionsData, CountCollectionsResponse, CountCollectionsError, VersionData, VersionResponse } from './types.gen';
+import type { GetUserIdentityData, GetUserIdentityResponse2, GetUserIdentityError, GetCollectionByCrnData, GetCollectionByCrnResponse, GetCollectionByCrnError, HealthcheckData, HealthcheckResponse, HealthcheckError, HeartbeatData, HeartbeatResponse2, HeartbeatError, PreFlightChecksData, PreFlightChecksResponse, PreFlightChecksError, ResetData, ResetResponse, ResetError, CreateTenantData, CreateTenantResponse2, CreateTenantError, GetTenantData, GetTenantResponse2, GetTenantError, UpdateTenantData, UpdateTenantResponse2, UpdateTenantError, ListDatabasesData, ListDatabasesResponse, ListDatabasesError, CreateDatabaseData, CreateDatabaseResponse2, CreateDatabaseError, DeleteDatabaseData, DeleteDatabaseResponse2, DeleteDatabaseError, GetDatabaseData, GetDatabaseResponse, GetDatabaseError, ListCollectionsData, ListCollectionsResponse, ListCollectionsError, CreateCollectionData, CreateCollectionResponse, CreateCollectionError, DeleteCollectionData, DeleteCollectionResponse2, DeleteCollectionError, GetCollectionData, GetCollectionResponse, GetCollectionError, UpdateCollectionData, UpdateCollectionResponse2, UpdateCollectionError, CollectionAddData, CollectionAddResponse, DetachFunctionData, DetachFunctionResponse2, DetachFunctionError, CollectionCountData, CollectionCountResponse, CollectionCountError, CollectionDeleteData, CollectionDeleteResponse, CollectionDeleteError, ForkCollectionData, ForkCollectionResponse, ForkCollectionError, ForkCountData, ForkCountResponse2, ForkCountError, AttachFunctionData, AttachFunctionResponse2, AttachFunctionError, GetAttachedFunctionData, GetAttachedFunctionResponse2, GetAttachedFunctionError, CollectionGetData, CollectionGetResponse, CollectionGetError, IndexingStatusData, IndexingStatusResponse, IndexingStatusError, CollectionQueryData, CollectionQueryResponse, CollectionQueryError, CollectionSearchData, CollectionSearchResponse, CollectionSearchError, CollectionUpdateData, CollectionUpdateResponse, CollectionUpsertData, CollectionUpsertResponse, CollectionUpsertError, CountCollectionsData, CountCollectionsResponse, CountCollectionsError, VersionData, VersionResponse } from './types.gen';
 import { client as _heyApiClient } from './client.gen';
 
 export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean> = ClientOptions<TData, ThrowOnError> & {
@@ -170,6 +170,23 @@ export class CollectionService {
         });
     }
     
+    /**
+     * Get fork count
+     * Returns the number of forks for a collection.
+     */
+    public static forkCount<ThrowOnError extends boolean = true>(options: Options<ForkCountData, ThrowOnError>) {
+        return (options.client ?? _heyApiClient).get<ForkCountResponse2, ForkCountError, ThrowOnError>({
+            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.

package/src/api/types.gen.ts

@@ -260,6 +260,16 @@ export type ForkCollectionPayload = {
     new_name: string;
 };
 
+/**
+ * Response containing the fork count for a collection.
+ */
+export type ForkCountResponse = {
+    /**
+     * The number of forks for this collection.
+     */
+    count: number;
+};
+
 export type FtsIndexConfig = {
     [key: string]: never;
 };
@@ -1663,6 +1673,52 @@ export type ForkCollectionResponses = {
 
 export type ForkCollectionResponse = ForkCollectionResponses[keyof ForkCollectionResponses];
 
+export type ForkCountData = {
+    body?: never;
+    path: {
+        /**
+         * Tenant UUID
+         */
+        tenant: string;
+        /**
+         * Database name
+         */
+        database: string;
+        /**
+         * Collection UUID
+         */
+        collection_id: string;
+    };
+    query?: never;
+    url: '/api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/fork_count';
+};
+
+export type ForkCountErrors = {
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+    /**
+     * Collection not found
+     */
+    404: ErrorResponse;
+    /**
+     * Server error
+     */
+    500: ErrorResponse;
+};
+
+export type ForkCountError = ForkCountErrors[keyof ForkCountErrors];
+
+export type ForkCountResponses = {
+    /**
+     * Fork count retrieved successfully
+     */
+    200: ForkCountResponse;
+};
+
+export type ForkCountResponse2 = ForkCountResponses[keyof ForkCountResponses];
+
 export type AttachFunctionData = {
     /**
      * Function attachment request

package/src/chroma-client.ts

@@ -14,7 +14,7 @@ import {
   ChecklistResponse,
 } from "./api";
 import { CollectionMetadata, UserIdentity } from "./types";
-import { Collection, CollectionImpl } from "./collection";
+import { Collection, CollectionHandle, CollectionImpl } from "./collection";
 import { EmbeddingFunction, getEmbeddingFunction } from "./embedding-function";
 import { chromaFetch } from "./chroma-fetch";
 import * as process from "node:process";
@@ -538,6 +538,33 @@ export class ChromaClient {
     });
   }
 
+  /**
+   * 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
+   */
+  public collection(id: string): Collection {
+    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

package/src/cli.ts

@@ -53,10 +53,6 @@ const main = async () => {
     return;
   }
 
-  process.on("SIGINT", () => {
-    process.exit(0);
-  });
-
   binding.cli(["chroma", ...args]);
 };
 

package/src/collection.ts

@@ -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
@@ -1028,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,
@@ -1141,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/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";