chromadb 3.1.8 → 3.2.1

package/dist/chromadb.d.ts

@@ -86,6 +86,12 @@ type HnswIndexConfig = {
     sync_threshold?: number | null;
 };
 type Include = 'distances' | 'documents' | 'embeddings' | 'metadatas' | 'uris';
+type IndexStatusResponse = {
+    num_indexed_ops: number;
+    num_unindexed_ops: number;
+    op_indexing_progress: number;
+    total_ops: number;
+};
 type IntInvertedIndexConfig$1 = {
     [key: string]: never;
 };
@@ -191,6 +197,10 @@ type Schema$1 = {
     keys: {
         [key: string]: ValueTypes$1;
     };
+    /**
+     * ID of the attached function that created this output collection (if applicable)
+     */
+    source_attached_function_id?: string | null;
 };
 type SearchPayload = {
     filter?: {
@@ -199,6 +209,12 @@ type SearchPayload = {
             [key: string]: unknown;
         };
     };
+    group_by?: {
+        aggregate?: {
+            [key: string]: unknown;
+        };
+        keys?: Array<string>;
+    };
     limit?: {
         limit?: number;
         offset?: number;
@@ -356,6 +372,19 @@ type VectorIndexType$1 = {
  * User identity information including tenant and database access.
  */
 type UserIdentity = GetUserIdentityResponse;
+/**
+ * Read level controls whether queries read from the write-ahead log (WAL).
+ *
+ * - INDEX_AND_WAL: Read from both the compacted index and the WAL.
+ *   All committed writes will be visible. This is the default.
+ * - INDEX_ONLY: Read only from the compacted index, skipping the WAL.
+ *   Recent writes that haven't been compacted may not be visible, but queries are faster.
+ */
+declare const ReadLevel: {
+    readonly INDEX_AND_WAL: "index_and_wal";
+    readonly INDEX_ONLY: "index_only";
+};
+type ReadLevel = (typeof ReadLevel)[keyof typeof ReadLevel];
 
 /**
  * Metadata that can be associated with a collection.
@@ -557,6 +586,10 @@ declare class QueryResult<TMeta extends Metadata = Metadata> {
      */
     rows(): QueryRowResult<TMeta>[][];
 }
+/**
+ * Re-export IndexStatusResponse type for external use
+ */
+type IndexingStatus = IndexStatusResponse;
 
 /**
  * Supported vector space types.
@@ -843,27 +876,76 @@ declare const Log: (input: RankInput) => RankExpression;
 declare const Max: (...inputs: RankInput[]) => RankExpression;
 declare const Min: (...inputs: RankInput[]) => RankExpression;
 
+interface MinKJSON {
+    keys: string[];
+    k: number;
+}
+interface MaxKJSON {
+    keys: string[];
+    k: number;
+}
+type AggregateJSON = {
+    $min_k: MinKJSON;
+} | {
+    $max_k: MaxKJSON;
+};
+type AggregateInput = Aggregate | AggregateJSON;
+declare abstract class Aggregate {
+    abstract toJSON(): AggregateJSON;
+    static from(input: AggregateInput): Aggregate;
+    static minK(keys: (Key | string)[], k: number): MinK;
+    static maxK(keys: (Key | string)[], k: number): MaxK;
+}
+declare class MinK extends Aggregate {
+    readonly keys: Key[];
+    readonly k: number;
+    constructor(keys: Key[], k: number);
+    toJSON(): AggregateJSON;
+}
+declare class MaxK extends Aggregate {
+    readonly keys: Key[];
+    readonly k: number;
+    constructor(keys: Key[], k: number);
+    toJSON(): AggregateJSON;
+}
+interface GroupByJSON {
+    keys: string[];
+    aggregate: AggregateJSON;
+}
+type GroupByInput = GroupBy | GroupByJSON;
+declare class GroupBy {
+    readonly keys: Key[];
+    readonly aggregate: Aggregate;
+    constructor(keys: Key[], aggregate: Aggregate);
+    static from(input: GroupByInput | undefined): GroupBy | undefined;
+    toJSON(): GroupByJSON;
+}
+
 interface SearchInit {
     where?: WhereInput;
     rank?: RankInput;
+    groupBy?: GroupByInput;
     limit?: LimitInput;
     select?: SelectInput;
 }
 declare class Search {
     private _where?;
     private _rank?;
+    private _groupBy?;
     private _limit;
     private _select;
     constructor(init?: SearchInit);
     private clone;
     where(where?: WhereInput): Search;
     rank(rank?: RankInput): Search;
+    groupBy(groupBy?: GroupByInput): Search;
     limit(limit?: LimitInput, offset?: number): Search;
     select(keys?: SelectInput): Search;
     select(...keys: SelectKeyInput[]): Search;
     selectAll(): Search;
     get whereClause(): WhereExpression | undefined;
     get rankExpression(): RankExpression | undefined;
+    get groupByConfig(): GroupBy | undefined;
     get limitConfig(): Limit;
     get selectConfig(): Select;
     toPayload(): SearchPayload;
@@ -891,6 +973,116 @@ declare class SearchResult {
 
 declare const DOCUMENT_KEY = "#document";
 declare const EMBEDDING_KEY = "#embedding";
+/**
+ * Supported cloud providers for customer-managed encryption keys.
+ * Currently only Google Cloud Platform (GCP) is supported.
+ */
+declare enum CmekProvider {
+    GCP = "gcp"
+}
+/**
+ * Customer-managed encryption key (CMEK) for collection data encryption.
+ *
+ * CMEK allows you to use your own encryption keys managed by cloud providers'
+ * key management services (KMS) instead of default provider-managed keys. This
+ * gives you greater control over key lifecycle, access policies, and audit logging.
+ *
+ * @example
+ * ```typescript
+ * // Create a CMEK for GCP
+ * const cmek = Cmek.gcp(
+ *   "projects/my-project/locations/us-central1/keyRings/my-ring/cryptoKeys/my-key"
+ * );
+ *
+ * // Validate the resource name format
+ * if (cmek.validatePattern()) {
+ *   console.log("Valid CMEK format");
+ * }
+ *
+ * // Use in collection schema
+ * const schema = new Schema();
+ * schema.setCmek(cmek);
+ * ```
+ *
+ * @note Pattern validation only checks format correctness. It does not verify
+ * that the key exists or is accessible. Key permissions and access control
+ * must be configured separately in your cloud provider's console.
+ */
+declare class Cmek {
+    private static readonly GCP_PATTERN;
+    readonly provider: CmekProvider;
+    readonly resource: string;
+    private constructor();
+    /**
+     * Create a CMEK instance for Google Cloud Platform.
+     *
+     * @param resource - GCP Cloud KMS resource name in the format:
+     *   projects/{project-id}/locations/{location}/keyRings/{key-ring}/cryptoKeys/{key-name}
+     *
+     * @returns A new CMEK instance configured for GCP
+     *
+     * @example
+     * ```typescript
+     * const cmek = Cmek.gcp(
+     *   "projects/my-project/locations/us-central1/keyRings/my-ring/cryptoKeys/my-key"
+     * );
+     * ```
+     */
+    static gcp(resource: string): Cmek;
+    /**
+     * Validate the CMEK resource name format.
+     *
+     * Validates that the resource name matches the expected pattern for the
+     * provider. This is a format check only and does not verify that the key
+     * exists or that you have access to it.
+     *
+     * For GCP, the expected format is:
+     *   projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}
+     *
+     * @returns true if the resource name format is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const cmek = Cmek.gcp("projects/p/locations/l/keyRings/r/cryptoKeys/k");
+     * cmek.validatePattern(); // Returns true
+     *
+     * const badCmek = Cmek.gcp("invalid-format");
+     * badCmek.validatePattern(); // Returns false
+     * ```
+     */
+    validatePattern(): boolean;
+    /**
+     * Serialize CMEK to object format for API transport.
+     *
+     * Returns an object with the provider variant as the key and resource as the value.
+     *
+     * @returns Object containing the provider variant and resource identifier
+     *
+     * @example
+     * ```typescript
+     * const cmek = Cmek.gcp("projects/p/locations/l/keyRings/r/cryptoKeys/k");
+     * cmek.toJSON();
+     * // Returns: { gcp: 'projects/p/locations/l/keyRings/r/cryptoKeys/k' }
+     * ```
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Deserialize CMEK from object format.
+     *
+     * Expects the provider variant as the key and resource as the value.
+     *
+     * @param data - Object containing provider variant and resource
+     * @returns Deserialized CMEK instance
+     * @throws Error if the provider is unsupported or data is malformed
+     *
+     * @example
+     * ```typescript
+     * const data = { gcp: 'projects/p/locations/l/keyRings/r/cryptoKeys/k' };
+     * const cmek = Cmek.fromJSON(data);
+     * ```
+     */
+    static fromJSON(data: Record<string, unknown>): Cmek;
+}
 declare class FtsIndexConfig {
     readonly type = "FtsIndexConfig";
 }
@@ -1004,10 +1196,42 @@ declare class ValueTypes {
 }
 type IndexConfig = FtsIndexConfig | VectorIndexConfig | SparseVectorIndexConfig | StringInvertedIndexConfig | IntInvertedIndexConfig | FloatInvertedIndexConfig | BoolInvertedIndexConfig;
 type JsonDict = Record<string, any>;
+/**
+ * Collection schema for configuring indexes and encryption.
+ *
+ * The schema controls how data is indexed and can optionally specify
+ * customer-managed encryption keys (CMEK) for data at rest.
+ *
+ * @example
+ * ```typescript
+ * const schema = new Schema();
+ * // Optionally add CMEK
+ * schema.setCmek(Cmek.gcp("projects/p/locations/l/keyRings/r/cryptoKeys/k"));
+ * ```
+ */
 declare class Schema {
     defaults: ValueTypes;
     keys: Record<string, ValueTypes>;
+    cmek: Cmek | null;
     constructor();
+    /**
+     * Set the customer-managed encryption key for this collection.
+     *
+     * CMEK allows you to use your own encryption keys managed by cloud providers'
+     * key management services instead of default provider-managed keys.
+     *
+     * @param cmek - CMEK instance or null to remove encryption
+     * @returns this for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = new Schema();
+     * schema.setCmek(Cmek.gcp(
+     *   "projects/my-project/locations/us-central1/keyRings/my-ring/cryptoKeys/my-key"
+     * ));
+     * ```
+     */
+    setCmek(cmek: Cmek | null): this;
     createIndex(config?: IndexConfig, key?: string): this;
     deleteIndex(config?: IndexConfig, key?: string): this;
     serializeToJSON(): Schema$1;
@@ -1442,6 +1666,11 @@ interface Collection {
      * @returns Promise resolving to column-major search results
      */
     search(searches: SearchLike | SearchLike[]): Promise<SearchResult>;
+    /**
+     * Gets the indexing status of the collection.
+     * @returns Promise resolving to indexing status information
+     */
+    getIndexingStatus(): Promise<IndexingStatus>;
 }
 
 declare function withChroma(userNextConfig?: any): any;
@@ -1661,4 +1890,4 @@ declare class ChromaRateLimitError extends Error {
 }
 declare function createErrorByType(type: string, message: string): InvalidCollectionError | InvalidArgumentError | undefined;
 
-export { Abs, AdminClient, type AdminClientArgs, AdminCloudClient, type AnyEmbeddingFunction, type BaseRecordSet, BoolInvertedIndexConfig, BoolInvertedIndexType, BoolValueType, ChromaClient, type ChromaClientArgs, ChromaClientError, ChromaConnectionError, ChromaError, ChromaForbiddenError, ChromaNotFoundError, ChromaQuotaExceededError, ChromaRateLimitError, ChromaServerError, ChromaUnauthorizedError, ChromaUniqueError, ChromaValueError, CloudClient, type Collection, type CollectionConfiguration, type CollectionMetadata, type CreateCollectionConfiguration, DOCUMENT_KEY, Div, EMBEDDING_KEY, type EmbeddingFunction, type EmbeddingFunctionClass, type EmbeddingFunctionSpace, Exp, FloatInvertedIndexConfig, FloatInvertedIndexType, FloatListValueType, FloatValueType, FtsIndexConfig, FtsIndexType, GetResult, type HNSWConfiguration, IncludeEnum, type IndexConfig, IntInvertedIndexConfig, IntInvertedIndexType, IntValueType, InvalidArgumentError, InvalidCollectionError, K, Key, type KeyFactory, Knn, type KnnOptions, Limit, type LimitInput, type LimitOptions, type ListDatabasesArgs, Log, Max, type Metadata, Min, Mul, type PreparedInsertRecordSet, type PreparedRecordSet, type QueryRecordSet, QueryResult, type QueryRowResult, RankExpression, type RankInput, type RankLiteral, 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, type CollectionMetadata, type CreateCollectionConfiguration, DOCUMENT_KEY, 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, 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 };