chromadb 3.2.2 → 3.3.0

package/src/chroma-client.ts

@@ -7,7 +7,12 @@ import {
   deserializeMetadata,
   serializeMetadata,
 } from "./utils";
-import { DefaultService as Api, ChecklistResponse } from "./api";
+import {
+  AuthenticationService,
+  CollectionService,
+  SystemService,
+  ChecklistResponse,
+} from "./api";
 import { CollectionMetadata, UserIdentity } from "./types";
 import { Collection, CollectionImpl } from "./collection";
 import { EmbeddingFunction, getEmbeddingFunction } from "./embedding-function";
@@ -207,7 +212,7 @@ export class ChromaClient {
    * @returns Promise resolving to user identity data
    */
   public async getUserIdentity(): Promise<UserIdentity> {
-    const { data } = await Api.getUserIdentity({
+    const { data } = await AuthenticationService.getUserIdentity({
       client: this.apiClient,
     });
     return data;
@@ -218,7 +223,7 @@ export class ChromaClient {
    * @returns Promise resolving to the server's nanosecond heartbeat timestamp
    */
   public async heartbeat(): Promise<number> {
-    const { data } = await Api.heartbeat({
+    const { data } = await SystemService.heartbeat({
       client: this.apiClient,
     });
     return data["nanosecond heartbeat"];
@@ -239,7 +244,7 @@ export class ChromaClient {
   ): Promise<Collection[]> {
     const { limit = 100, offset = 0 } = args || {};
 
-    const { data } = await Api.listCollections({
+    const { data } = await CollectionService.listCollections({
       client: this.apiClient,
       path: await this._path(),
       query: { limit, offset },
@@ -282,7 +287,7 @@ export class ChromaClient {
    * @returns Promise resolving to the collection count
    */
   public async countCollections(): Promise<number> {
-    const { data } = await Api.countCollections({
+    const { data } = await CollectionService.countCollections({
       client: this.apiClient,
       path: await this._path(),
     });
@@ -320,7 +325,7 @@ export class ChromaClient {
       schema,
     });
 
-    const { data } = await Api.createCollection({
+    const { data } = await CollectionService.createCollection({
       client: this.apiClient,
       path: await this._path(),
       body: {
@@ -376,7 +381,7 @@ export class ChromaClient {
     name: string;
     embeddingFunction?: EmbeddingFunction;
   }): Promise<Collection> {
-    const { data } = await Api.getCollection({
+    const { data } = await CollectionService.getCollection({
       client: this.apiClient,
       path: { ...(await this._path()), collection_id: name },
     });
@@ -413,7 +418,7 @@ export class ChromaClient {
    * @throws Error if the collection does not exist
    */
   public async getCollectionByCrn(crn: string): Promise<Collection> {
-    const { data } = await Api.getCollectionByCrn({
+    const { data } = await CollectionService.getCollectionByCrn({
       client: this.apiClient,
       path: { crn },
     });
@@ -497,7 +502,7 @@ export class ChromaClient {
       schema,
     });
 
-    const { data } = await Api.createCollection({
+    const { data } = await CollectionService.createCollection({
       client: this.apiClient,
       path: await this._path(),
       body: {
@@ -544,7 +549,7 @@ export class ChromaClient {
    * @param options.name - The name of the collection to delete
    */
   public async deleteCollection({ name }: { name: string }): Promise<void> {
-    await Api.deleteCollection({
+    await CollectionService.deleteCollection({
       client: this.apiClient,
       path: { ...(await this._path()), collection_id: name },
     });
@@ -556,7 +561,7 @@ export class ChromaClient {
    * @warning This operation is irreversible and will delete all data
    */
   public async reset(): Promise<void> {
-    await Api.reset({
+    await SystemService.reset({
       client: this.apiClient,
     });
   }
@@ -566,7 +571,7 @@ export class ChromaClient {
    * @returns Promise resolving to the server version string
    */
   public async version(): Promise<string> {
-    const { data } = await Api.version({
+    const { data } = await SystemService.version({
       client: this.apiClient,
     });
     return data;
@@ -578,7 +583,7 @@ export class ChromaClient {
    */
   public async getPreflightChecks(): Promise<ChecklistResponse> {
     if (!this.preflightChecks) {
-      const { data } = await Api.preFlightChecks({
+      const { data } = await SystemService.preFlightChecks({
         client: this.apiClient,
       });
       this.preflightChecks = data;

package/src/collection.ts

@@ -19,7 +19,7 @@ import {
   WhereDocument,
 } from "./types";
 import { Include, SparseVector, SearchPayload } from "./api";
-import { DefaultService as Api } from "./api";
+import { CollectionService, RecordService } from "./api";
 import {
   validateRecordSetLengthConsistency,
   validateIDs,
@@ -747,7 +747,7 @@ export class CollectionImpl implements Collection {
   }
 
   public async count(): Promise<number> {
-    const { data } = await Api.collectionCount({
+    const { data } = await RecordService.collectionCount({
       client: this.apiClient,
       path: await this.path(),
     });
@@ -778,7 +778,7 @@ export class CollectionImpl implements Collection {
 
     const preparedRecordSet = await this.prepareRecords({ recordSet });
 
-    await Api.collectionAdd({
+    await RecordService.collectionAdd({
       client: this.apiClient,
       path: await this.path(),
       body: {
@@ -812,7 +812,7 @@ export class CollectionImpl implements Collection {
 
     this.validateGet(include, ids, where, whereDocument);
 
-    const { data } = await Api.collectionGet({
+    const { data } = await RecordService.collectionGet({
       client: this.apiClient,
       path: await this.path(),
       body: {
@@ -875,7 +875,7 @@ export class CollectionImpl implements Collection {
       nResults,
     );
 
-    const { data } = await Api.collectionQuery({
+    const { data } = await RecordService.collectionQuery({
       client: this.apiClient,
       path: await this.path(),
       body: {
@@ -923,7 +923,7 @@ export class CollectionImpl implements Collection {
       }),
     );
 
-    const { data } = await Api.collectionSearch({
+    const { data } = await RecordService.collectionSearch({
       client: this.apiClient,
       path: await this.path(),
       body: {
@@ -953,12 +953,12 @@ export class CollectionImpl implements Collection {
 
     const { updateConfiguration, updateEmbeddingFunction } = configuration
       ? await processUpdateCollectionConfig({
-          collectionName: this.name,
-          currentConfiguration: this.configuration,
-          newConfiguration: configuration,
-          currentEmbeddingFunction: this.embeddingFunction,
-          client: this.chromaClient,
-        })
+        collectionName: this.name,
+        currentConfiguration: this.configuration,
+        newConfiguration: configuration,
+        currentEmbeddingFunction: this.embeddingFunction,
+        client: this.chromaClient,
+      })
       : {};
 
     if (updateEmbeddingFunction) {
@@ -973,7 +973,7 @@ export class CollectionImpl implements Collection {
       };
     }
 
-    await Api.updateCollection({
+    await CollectionService.updateCollection({
       client: this.apiClient,
       path: await this.path(),
       body: {
@@ -985,7 +985,7 @@ export class CollectionImpl implements Collection {
   }
 
   public async fork({ name }: { name: string }): Promise<Collection> {
-    const { data } = await Api.forkCollection({
+    const { data } = await CollectionService.forkCollection({
       client: this.apiClient,
       path: await this.path(),
       body: { new_name: name },
@@ -1030,7 +1030,7 @@ export class CollectionImpl implements Collection {
       update: true,
     });
 
-    await Api.collectionUpdate({
+    await RecordService.collectionUpdate({
       client: this.apiClient,
       path: await this.path(),
       body: {
@@ -1068,7 +1068,7 @@ export class CollectionImpl implements Collection {
       recordSet,
     });
 
-    await Api.collectionUpsert({
+    await RecordService.collectionUpsert({
       client: this.apiClient,
       path: await this.path(),
       body: {
@@ -1092,7 +1092,7 @@ export class CollectionImpl implements Collection {
   }): Promise<void> {
     this.validateDelete(ids, where, whereDocument);
 
-    await Api.collectionDelete({
+    await RecordService.collectionDelete({
       client: this.apiClient,
       path: await this.path(),
       body: {
@@ -1104,7 +1104,7 @@ export class CollectionImpl implements Collection {
   }
 
   public async getIndexingStatus(): Promise<IndexingStatus> {
-    const { data } = await Api.indexingStatus({
+    const { data } = await RecordService.indexingStatus({
       client: this.apiClient,
       path: await this.path(),
     });

package/src/execution/expression/key.ts

@@ -46,16 +46,37 @@ export class Key {
     return createComparisonWhere(this.name, "$nin", array);
   }
 
-  public contains(value: string): WhereExpression {
-    if (typeof value !== "string") {
-      throw new TypeError("$contains requires a string value");
+  /**
+   * Contains filter.
+   *
+   * On `Key.DOCUMENT`: substring search (value must be a string).
+   * On metadata fields: checks if the array field contains the scalar value.
+   *
+   * @example
+   * K.DOCUMENT.contains("machine learning")   // document substring
+   * K("tags").contains("action")               // metadata array contains
+   * K("scores").contains(42)                   // metadata array contains
+   */
+  public contains(value: string | number | boolean): WhereExpression {
+    if (this.name === "#document" && typeof value !== "string") {
+      throw new TypeError("K.DOCUMENT.contains requires a string value");
     }
     return createComparisonWhere(this.name, "$contains", value);
   }
 
-  public notContains(value: string): WhereExpression {
-    if (typeof value !== "string") {
-      throw new TypeError("$not_contains requires a string value");
+  /**
+   * Not-contains filter.
+   *
+   * On `Key.DOCUMENT`: excludes documents containing the substring.
+   * On metadata fields: checks that the array field does not contain the scalar value.
+   *
+   * @example
+   * K.DOCUMENT.notContains("deprecated")   // document substring exclusion
+   * K("tags").notContains("draft")          // metadata array not-contains
+   */
+  public notContains(value: string | number | boolean): WhereExpression {
+    if (this.name === "#document" && typeof value !== "string") {
+      throw new TypeError("K.DOCUMENT.notContains requires a string value");
     }
     return createComparisonWhere(this.name, "$not_contains", value);
   }

package/src/types.ts

@@ -30,22 +30,41 @@ export type ReadLevel = (typeof ReadLevel)[keyof typeof ReadLevel];
  */
 export type { SparseVector };
 
+/**
+ * Scalar metadata values that can be stored in arrays.
+ */
+export type MetadataScalar = boolean | number | string;
+
 /**
  * Metadata that can be associated with a collection.
- * Values must be boolean, number, or string types.
+ * Values can be boolean, number, string, SparseVector, typed arrays, or null.
  */
 export type CollectionMetadata = Record<
   string,
-  boolean | number | string | SparseVector | null
+  | boolean
+  | number
+  | string
+  | SparseVector
+  | boolean[]
+  | number[]
+  | string[]
+  | null
 >;
 
 /**
  * Metadata that can be associated with individual records.
- * Values must be boolean, number, or string types.
+ * Values can be boolean, number, string, SparseVector, typed arrays, or null.
  */
 export type Metadata = Record<
   string,
-  boolean | number | string | SparseVector | null
+  | boolean
+  | number
+  | string
+  | SparseVector
+  | boolean[]
+  | number[]
+  | string[]
+  | null
 >;
 
 /**
@@ -106,6 +125,8 @@ type WhereOperator = "$gt" | "$gte" | "$lt" | "$lte" | "$ne" | "$eq";
 
 type InclusionExclusionOperator = "$in" | "$nin";
 
+type ArrayContainsOperator = "$contains" | "$not_contains";
+
 type OperatorExpression =
   | { $gt: LiteralValue }
   | { $gte: LiteralValue }
@@ -116,7 +137,9 @@ type OperatorExpression =
   | { $and: LiteralValue }
   | { $or: LiteralValue }
   | { $in: LiteralValue[] }
-  | { $nin: LiteralValue[] };
+  | { $nin: LiteralValue[] }
+  | { $contains: LiteralValue }
+  | { $not_contains: LiteralValue };
 
 /**
  * Where clause for filtering records based on metadata.

package/src/utils.ts

@@ -260,19 +260,50 @@ export const validateMetadata = (metadata?: Metadata) => {
     throw new ChromaValueError("Expected metadata to be non-empty");
   }
 
-  if (
-    !Object.values(metadata).every(
-      (v: any) =>
-        v === null ||
-        v === undefined ||
-        typeof v === "string" ||
-        typeof v === "number" ||
-        typeof v === "boolean" ||
-        validateSparseVector(v),
-    )
-  ) {
+  const validateMetadataListValue = (key: string, v: unknown[]): void => {
+    if (v.length === 0) {
+      throw new ChromaValueError(
+        `Expected metadata list value for key '${key}' to be non-empty`,
+      );
+    }
+    const firstType = typeof v[0];
+    for (const item of v) {
+      if (
+        typeof item !== "string" &&
+        typeof item !== "number" &&
+        typeof item !== "boolean"
+      ) {
+        throw new ChromaValueError(
+          `Expected metadata list value for key '${key}' to contain only strings, numbers, or booleans, got ${typeof item}`,
+        );
+      }
+      if (typeof item !== firstType) {
+        throw new ChromaValueError(
+          `Expected metadata list value for key '${key}' to contain only the same type, got mixed types`,
+        );
+      }
+    }
+  };
+
+  for (const [key, v] of Object.entries(metadata)) {
+    if (
+      v === null ||
+      v === undefined ||
+      typeof v === "string" ||
+      typeof v === "number" ||
+      typeof v === "boolean"
+    ) {
+      continue;
+    }
+    if (validateSparseVector(v)) {
+      continue;
+    }
+    if (Array.isArray(v)) {
+      validateMetadataListValue(key, v);
+      continue;
+    }
     throw new ChromaValueError(
-      "Expected metadata to be a string, number, boolean, SparseVector, or nullable",
+      `Expected metadata value for key '${key}' to be a string, number, boolean, SparseVector, typed array (string[], number[], boolean[]), or null`,
     );
   }
 };
@@ -289,6 +320,9 @@ type SerializedMetadataValue =
   | string
   | SerializedSparseVector
   | SparseVector
+  | Array<boolean>
+  | Array<number>
+  | Array<string>
   | null;
 
 export type SerializedMetadata = Record<string, SerializedMetadataValue>;
@@ -315,10 +349,13 @@ export const serializeMetadata = (
   const result: SerializedMetadata = {};
 
   Object.entries(metadata).forEach(([key, value]) => {
+    if (value === null || value === undefined) {
+      return;
+    }
     if (validateSparseVector(value)) {
       result[key] = toSerializedSparseVector(value);
     } else {
-      result[key] = value ?? null;
+      result[key] = value;
     }
   });
 
@@ -555,12 +592,30 @@ export const validateWhere = (where: Where) => {
       }
 
       if (
-        !["$gt", "$gte", "$lt", "$lte", "$ne", "$eq", "$in", "$nin"].includes(
-          operator,
-        )
+        ["$contains", "$not_contains"].includes(operator) &&
+        !["string", "number", "boolean"].includes(typeof operand)
+      ) {
+        throw new ChromaValueError(
+          `Expected operand value to be a string, number, or boolean for ${operator}, but got ${typeof operand}`,
+        );
+      }
+
+      if (
+        ![
+          "$gt",
+          "$gte",
+          "$lt",
+          "$lte",
+          "$ne",
+          "$eq",
+          "$in",
+          "$nin",
+          "$contains",
+          "$not_contains",
+        ].includes(operator)
       ) {
         throw new ChromaValueError(
-          `Expected operator to be one of $gt, $gte, $lt, $lte, $ne, $eq, $in, $nin, but got ${operator}`,
+          `Expected operator to be one of $gt, $gte, $lt, $lte, $ne, $eq, $in, $nin, $contains, $not_contains, but got ${operator}`,
         );
       }