Vector Index Support (#828)

* Removed duplicate options

* Vector index

* Vector index test

* Updating tests image

* Updating changelog

* Reverted tests.yml

* Rework test

* Rework test

* Rework test

* Rework test

* Fixing bug with latest devel (type is sent as "undefined" instead of "")

* Making sure test works

* Modified changelog

Author: apetenchea

CHANGELOG.md

@@ -14,6 +14,12 @@ This driver uses semantic versioning:
 - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_
   changes that require changes in your code to upgrade.
 
+## [10.1.2] - 2025-06-30
+
+### Added
+
+- Added vector index support
+
 ## [10.1.1] - 2025-01-13
 
 ### Changed

src/collections.ts

@@ -1466,7 +1466,7 @@ export interface DocumentCollection<
   import(
     data: Buffer | Blob | string,
     options?: documents.ImportDocumentsOptions & {
-      type?: "documents" | "list" | "auto";
+      type?: "" | "documents" | "list" | "auto";
     }
   ): Promise<documents.ImportDocumentsResult>;
   //#endregion
@@ -1612,33 +1612,6 @@ export interface DocumentCollection<
       indexes.MdiIndexDescription & { isNewlyCreated: boolean }
     >
   >;
-  /**
-   * Creates a prefixed multi-dimensional index on the collection if it does
-   * not already exist.
-   *
-   * @param options - Options for creating the prefixed multi-dimensional index.
-   *
-   * @example
-   * ```js
-   * const db = new Database();
-   * const collection = db.collection("some-points");
-   * // Create a multi-dimensional index for the attributes x, y and z
-   * await collection.ensureIndex({
-   *   type: "mdi-prefixed",
-   *   fields: ["x", "y", "z"],
-   *   prefixFields: ["x"],
-   *   fieldValueTypes: "double"
-   * });
-   * ```
-   * ```
-   */
-  ensureIndex(
-    options: indexes.EnsureMdiPrefixedIndexOptions
-  ): Promise<
-    connection.ArangoApiResponse<
-      indexes.MdiPrefixedIndexDescription & { isNewlyCreated: boolean }
-    >
-  >;
   /**
    * Creates a prefixed multi-dimensional index on the collection if it does not already exist.
    *
@@ -1712,6 +1685,33 @@ export interface DocumentCollection<
       indexes.InvertedIndexDescription & { isNewlyCreated: boolean }
     >
   >;
+  /**
+   * Creates a vector index on the collection if it does not already exist.
+   *
+   * @param options - Options for creating the vector index.
+   *
+   * @example
+   * ```js
+   * const db = new Database();
+   * const collection = db.collection("some-collection");
+   * await collection.ensureIndex({
+   *   type: "vector",
+   *   fields: ["embedding"],
+   *   params: {
+   *     metric: "cosine",
+   *     dimension: 128,
+   *     nLists: 100
+   *   }
+   * });
+   * ```
+   */
+  ensureIndex(
+    options: indexes.EnsureVectorIndexOptions
+  ): Promise<
+    connection.ArangoApiResponse<
+      indexes.VectorIndexDescription & { isNewlyCreated: boolean }
+    >
+  >;
   /**
    * Creates an index on the collection if it does not already exist.
    *
@@ -2296,7 +2296,7 @@ export interface EdgeCollection<
   import(
     data: Buffer | Blob | string,
     options?: documents.ImportDocumentsOptions & {
-      type?: "documents" | "list" | "auto";
+      type?: "" | "documents" | "list" | "auto";
     }
   ): Promise<documents.ImportDocumentsResult>;
   //#endregion
@@ -2875,12 +2875,12 @@ export class Collection<
   import(
     data: Buffer | Blob | string | any[],
     options: documents.ImportDocumentsOptions & {
-      type?: "documents" | "list" | "auto";
+      type?: "" | "documents" | "list" | "auto";
     } = {}
   ): Promise<documents.ImportDocumentsResult> {
     const search = { ...options, collection: this._name };
     if (Array.isArray(data)) {
-      search.type = Array.isArray(data[0]) ? undefined : "documents";
+      search.type = Array.isArray(data[0]) ? "" : "documents";
       const lines = data as any[];
       data = lines.map((line) => JSON.stringify(line)).join("\r\n") + "\r\n";
     }

src/indexes.ts

@@ -62,7 +62,8 @@ export type EnsureIndexOptions =
   | EnsureTtlIndexOptions
   | EnsureMdiIndexOptions
   | EnsureMdiPrefixedIndexOptions
-  | EnsureInvertedIndexOptions;
+  | EnsureInvertedIndexOptions
+  | EnsureVectorIndexOptions;
 
 /**
  * Shared attributes of all index creation options.
@@ -558,6 +559,56 @@ export type InvertedIndexStoredValueOptions = {
    */
   cache?: boolean;
 };
+
+/**
+ * Options for creating a vector index.
+ */
+export type EnsureVectorIndexOptions = EnsureIndexOptionsType<
+  "vector",
+  [string],
+  {
+    /**
+     * The number of threads to use for indexing. Default is 2.
+     */
+    parallelism?: number;
+
+    /**
+     * Vector index parameters, following Faiss configuration.
+     */
+    params: {
+      /**
+       * Whether to use cosine or l2 (Euclidean) distance.
+       */
+      metric: "cosine" | "l2";
+
+      /**
+       * Vector dimension. Must match the length of vectors in documents.
+       */
+      dimension: number;
+
+      /**
+       * Number of Voronoi cells (centroids) for IVF. Affects accuracy and index build time.
+       */
+      nLists: number;
+
+      /**
+       * How many neighboring centroids to probe by default. Higher = slower, better recall.
+       */
+      defaultNProbe?: number;
+
+      /**
+       * Training iterations for index build. Default is 25.
+       */
+      trainingIterations?: number;
+
+      /**
+       * Advanced Faiss index factory string.
+       * If not specified, defaults to IVF<nLists>,Flat.
+       */
+      factory?: string;
+    };
+  }
+>;
 //#endregion
 
 //#region IndexDescription
@@ -572,7 +623,8 @@ export type IndexDescription =
   | MdiIndexDescription
   | MdiPrefixedIndexDescription
   | InvertedIndexDescription
-  | SystemIndexDescription;
+  | SystemIndexDescription
+  | VectorIndexDescription;
 
 /**
  * An object representing a system index.
@@ -862,6 +914,26 @@ export type HiddenIndexDescription = (
    */
   progress?: number;
 };
+
+/**
+ * An object representing a vector index.
+ */
+export type VectorIndexDescription = IndexDescriptionType<
+  "vector",
+  [string],
+  {
+    parallelism: number;
+    inBackground: boolean;
+    params: {
+      metric: "cosine" | "l2";
+      dimension: number;
+      nLists: number;
+      defaultNProbe?: number;
+      trainingIterations?: number;
+      factory?: string;
+    };
+  }
+>;
 //#endregion
 
 //#region Index selectors

src/test/11-managing-indexes.ts

@@ -29,6 +29,34 @@ describe("Managing indexes", function () {
       system.close();
     }
   });
+  describe("collection.ensureIndex#vector", () => {
+    it.skip("should create a vector index", async () => {
+      // Available in ArangoDB 3.12.4+.
+      // Only enabled with the --experimental-vector-index startup option.
+      const data = Array.from({ length: 128 }, (_, cnt) => ({
+        _key: `vec${cnt}`,
+        embedding: Array(128).fill(cnt),
+      }));
+      await collection.import(data);
+      const info = await collection.ensureIndex({
+        type: "vector",
+        fields: ["embedding"],
+        params: {
+          metric: "cosine",
+          dimension: 128,
+          nLists: 2,
+        },
+      });
+      expect(info).to.have.property("id");
+      expect(info).to.have.property("type", "vector");
+      expect(info).to.have.property("fields");
+      expect(info.fields).to.eql(["embedding"]);
+      expect(info).to.have.property("isNewlyCreated", true);
+      expect(info).to.have.nested.property("params.metric", "cosine");
+      expect(info).to.have.nested.property("params.dimension", 128);
+      expect(info).to.have.nested.property("params.nLists", 2);
+    });
+  });
   describe("collection.ensureIndex#persistent", () => {
     it("should create a persistent index", async () => {
       const info = await collection.ensureIndex({