chromadb 3.3.0 → 3.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromadb",
-  "version": "3.3.0",
+  "version": "3.3.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.0",
-    "chromadb-js-bindings-darwin-x64": "^1.3.0",
-    "chromadb-js-bindings-linux-arm64-gnu": "^1.3.0",
-    "chromadb-js-bindings-linux-x64-gnu": "^1.3.0",
-    "chromadb-js-bindings-win32-x64-msvc": "^1.3.0"
+    "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"
   },
   "engines": {
     "node": ">=20"

package/src/api/types.gen.ts

@@ -436,6 +436,11 @@ export type Key = 'Document' | 'Embedding' | 'Metadata' | 'Score' | {
     MetadataField: string;
 };
 
+/**
+ * Quantization implementation for SPANN vector index.
+ */
+export type Quantization = 'none' | 'four_bit_rabit_q_with_u_search';
+
 export type QueryRequestPayload = RawWhereFields & {
     ids?: Array<string> | null;
     include?: IncludeList;
@@ -559,9 +564,9 @@ export type SpannIndexConfig = {
     num_centers_to_merge_to?: number | null;
     num_samples_kmeans?: number | null;
     /**
-     * Enable quantization for vector search (cloud-only feature)
+     * Quantization implementation for vector search (cloud-only feature)
      */
-    quantize?: boolean;
+    quantize?: Quantization;
     reassign_neighbor_count?: number | null;
     search_nprobe?: number | null;
     search_rng_epsilon?: number | null;

package/src/schema.ts

@@ -251,72 +251,72 @@ export class SparseVectorIndexConfig {
 }
 
 export class FtsIndexType {
-  constructor(public enabled: boolean, public config: FtsIndexConfig) {}
+  constructor(public enabled: boolean, public config: FtsIndexConfig) { }
 }
 
 export class StringInvertedIndexType {
   constructor(
     public enabled: boolean,
     public config: StringInvertedIndexConfig,
-  ) {}
+  ) { }
 }
 
 export class VectorIndexType {
-  constructor(public enabled: boolean, public config: VectorIndexConfig) {}
+  constructor(public enabled: boolean, public config: VectorIndexConfig) { }
 }
 
 export class SparseVectorIndexType {
   constructor(
     public enabled: boolean,
     public config: SparseVectorIndexConfig,
-  ) {}
+  ) { }
 }
 
 export class IntInvertedIndexType {
-  constructor(public enabled: boolean, public config: IntInvertedIndexConfig) {}
+  constructor(public enabled: boolean, public config: IntInvertedIndexConfig) { }
 }
 
 export class FloatInvertedIndexType {
   constructor(
     public enabled: boolean,
     public config: FloatInvertedIndexConfig,
-  ) {}
+  ) { }
 }
 
 export class BoolInvertedIndexType {
   constructor(
     public enabled: boolean,
     public config: BoolInvertedIndexConfig,
-  ) {}
+  ) { }
 }
 
 export class StringValueType {
   constructor(
     public ftsIndex: FtsIndexType | null = null,
     public stringInvertedIndex: StringInvertedIndexType | null = null,
-  ) {}
+  ) { }
 }
 
 export class FloatListValueType {
-  constructor(public vectorIndex: VectorIndexType | null = null) {}
+  constructor(public vectorIndex: VectorIndexType | null = null) { }
 }
 
 export class SparseVectorValueType {
-  constructor(public sparseVectorIndex: SparseVectorIndexType | null = null) {}
+  constructor(public sparseVectorIndex: SparseVectorIndexType | null = null) { }
 }
 
 export class IntValueType {
-  constructor(public intInvertedIndex: IntInvertedIndexType | null = null) {}
+  constructor(public intInvertedIndex: IntInvertedIndexType | null = null) { }
 }
 
 export class FloatValueType {
   constructor(
     public floatInvertedIndex: FloatInvertedIndexType | null = null,
-  ) {}
+  ) { }
 }
 
 export class BoolValueType {
-  constructor(public boolInvertedIndex: BoolInvertedIndexType | null = null) {}
+  constructor(public boolInvertedIndex: BoolInvertedIndexType | null = null) { }
 }
 
 export class ValueTypes {
@@ -351,11 +351,11 @@ const cloneObject = <T>(value: T): T => {
   return Array.isArray(value)
     ? (value.map((item) => cloneObject(item)) as T)
     : (Object.fromEntries(
-        Object.entries(value as Record<string, unknown>).map(([k, v]) => [
-          k,
-          cloneObject(v),
-        ]),
-      ) as T);
+      Object.entries(value as Record<string, unknown>).map(([k, v]) => [
+        k,
+        cloneObject(v),
+      ]),
+    ) as T);
 };
 
 const resolveEmbeddingFunctionName = (
@@ -471,6 +471,7 @@ export class Schema {
   defaults: ValueTypes;
   keys: Record<string, ValueTypes>;
   cmek: Cmek | null;
+  private _rawJSON: Record<string, unknown> | null = null;
 
   constructor() {
     this.defaults = new ValueTypes();
@@ -480,6 +481,18 @@ export class Schema {
     this.initializeKeys();
   }
 
+  /**
+   * Returns the raw JSON schema as received from the server, or null if the
+   * schema was constructed client-side rather than deserialized from a server
+   * response.
+   */
+  get rawJSON(): Record<string, unknown> | null {
+    if (this._rawJSON === null) {
+      return null;
+    }
+    return structuredClone(this._rawJSON);
+  }
+
   /**
    * Set the customer-managed encryption key for this collection.
    *
@@ -512,35 +525,48 @@ export class Schema {
       );
     }
 
-    if (keyProvided && key && (key === EMBEDDING_KEY || key === DOCUMENT_KEY)) {
+    // Disallow using special internal key #embedding
+    if (keyProvided && key && key === EMBEDDING_KEY) {
+      throw new Error(
+        `Cannot create index on special key '${key}'. This key is managed automatically by the system. Invoke createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.`,
+      );
+    }
+
+    // Only allow #document with FtsIndexConfig
+    if (keyProvided && key === DOCUMENT_KEY && !(config instanceof FtsIndexConfig)) {
       throw new Error(
-        `Cannot create index on special key '${key}'. These keys are managed automatically by the system.`,
+        `Cannot create index on special key '${key}' with this config. Only FtsIndexConfig is allowed for #document.`,
       );
     }
 
+    // Disallow any key starting with # (except #document which allows FTS)
+    if (keyProvided && key && key.startsWith("#") && key !== DOCUMENT_KEY) {
+      throw new Error(
+        "key cannot begin with '#'. Keys starting with '#' are reserved for system use.",
+      );
+    }
+
+    // Special handling for vector index
     if (config instanceof VectorIndexConfig) {
       if (!keyProvided) {
         this.setVectorIndexConfig(config);
         return this;
       }
       throw new Error(
-        "Vector index cannot be enabled on specific keys. Use createIndex(config=VectorIndexConfig(...)) without specifying a key to configure the vector index globally.",
+        "Vector index cannot be enabled on specific keys. Use createIndex(new VectorIndexConfig(...)) without specifying a key to configure the vector index globally.",
       );
     }
 
-    if (config instanceof FtsIndexConfig) {
-      if (!keyProvided) {
-        this.setFtsIndexConfig(config);
-        return this;
-      }
+    // FTS index is only allowed on #document key
+    if (config instanceof FtsIndexConfig && (!keyProvided || key !== DOCUMENT_KEY)) {
       throw new Error(
-        "FTS index cannot be enabled on specific keys. Use createIndex(config=FtsIndexConfig(...)) without specifying a key to configure the FTS index globally.",
+        "FTS index can only be enabled on #document key. Use createIndex(new FtsIndexConfig(), '#document')",
       );
     }
 
     if (config instanceof SparseVectorIndexConfig && !keyProvided) {
       throw new Error(
-        "Sparse vector index must be created on a specific key. Please specify a key using: createIndex(config=SparseVectorIndexConfig(...), key='your_key')",
+        "Sparse vector index must be created on a specific key. Please specify a key using: createIndex(new SparseVectorIndexConfig(...), 'your_key')",
       );
     }
 
@@ -571,26 +597,45 @@ export class Schema {
       );
     }
 
-    if (keyProvided && key && (key === EMBEDDING_KEY || key === DOCUMENT_KEY)) {
+    // Disallow using special internal key #embedding
+    if (keyProvided && key && key === EMBEDDING_KEY) {
       throw new Error(
-        `Cannot delete index on special key '${key}'. These keys are managed automatically by the system.`,
+        "Cannot modify #embedding. Currently not supported",
       );
     }
 
-    if (config instanceof VectorIndexConfig) {
-      throw new Error("Deleting vector index is not currently supported.");
+    // Only allow #document with FtsIndexConfig (to disable FTS)
+    if (keyProvided && key === DOCUMENT_KEY && !(config instanceof FtsIndexConfig)) {
+      throw new Error(
+        `Cannot delete index on special key '${key}' with this config. Only FtsIndexConfig is allowed for #document.`,
+      );
     }
 
-    if (config instanceof FtsIndexConfig) {
-      throw new Error("Deleting FTS index is not currently supported.");
+    // Disallow any key starting with # (except #document which allows FTS deletion)
+    if (keyProvided && key && key.startsWith("#") && key !== DOCUMENT_KEY) {
+      throw new Error(
+        "key cannot begin with '#'. Keys starting with '#' are reserved for system use.",
+      );
     }
 
+    // TODO: Consider removing these checks in the future to allow disabling vector and sparse vector indexes
+    // Temporarily disallow deleting vector index (both globally and per-key)
+    if (config instanceof VectorIndexConfig) {
+      throw new Error("Deleting vector index is not currently supported.");
+    }
+
+    // Temporarily disallow deleting sparse vector index (both globally and per-key)
     if (config instanceof SparseVectorIndexConfig) {
       throw new Error(
         "Deleting sparse vector index is not currently supported.",
       );
     }
 
+    // FTS deletion is only allowed on #document key
+    if (config instanceof FtsIndexConfig && (!keyProvided || key !== DOCUMENT_KEY)) {
+      throw new Error("Deleting FTS index is only supported on #document key.");
+    }
+
     // TODO: Consider removing this check in the future to allow disabling all indexes for a key
     // Disallow disabling all index types for a key (config=undefined, key="some_key")
     if (keyProvided && !configProvided && key) {
@@ -639,6 +684,7 @@ export class Schema {
 
     const data = json as JsonDict;
     const instance = Object.create(Schema.prototype) as Schema;
+    instance._rawJSON = structuredClone(data) as Record<string, unknown>;
     instance.defaults = await Schema.deserializeValueTypes(
       (data.defaults ?? {}) as Record<string, any>,
       client,
@@ -700,26 +746,6 @@ export class Schema {
     );
   }
 
-  private setFtsIndexConfig(config: FtsIndexConfig): void {
-    const defaultsString = ensureStringValueType(this.defaults);
-    const currentDefaultsFts =
-      defaultsString.ftsIndex ?? new FtsIndexType(false, new FtsIndexConfig());
-    defaultsString.ftsIndex = new FtsIndexType(
-      currentDefaultsFts.enabled,
-      config,
-    );
-
-    const documentValueTypes = ensureValueTypes(this.keys[DOCUMENT_KEY]);
-    this.keys[DOCUMENT_KEY] = documentValueTypes;
-    const overrideString = ensureStringValueType(documentValueTypes);
-    const currentOverrideFts =
-      overrideString.ftsIndex ?? new FtsIndexType(true, new FtsIndexConfig());
-    overrideString.ftsIndex = new FtsIndexType(
-      currentOverrideFts.enabled,
-      config,
-    );
-  }
-
   private setIndexInDefaults(config: IndexConfig, enabled: boolean): void {
     if (config instanceof FtsIndexConfig) {
       const valueType = ensureStringValueType(this.defaults);
@@ -1075,8 +1101,7 @@ export class Schema {
       !embeddingFunction.supportedSpaces().includes(resolvedSpace)
     ) {
       console.warn(
-        `Space '${resolvedSpace}' is not supported by embedding function '${
-          resolveEmbeddingFunctionName(embeddingFunction) ?? "unknown"
+        `Space '${resolvedSpace}' is not supported by embedding function '${resolveEmbeddingFunctionName(embeddingFunction) ?? "unknown"
         }'. Supported spaces: ${embeddingFunction
           .supportedSpaces()
           .join(", ")}`,