@mastra/qdrant 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/index.js

@@ -250,18 +250,54 @@ var QdrantVector = class extends MastraVector {
     super({ id });
     this.client = new QdrantClient(qdrantParams);
   }
-  async upsert({ indexName, vectors, metadata, ids }) {
+  /**
+   * Validates that a named vector exists in the collection.
+   * @param indexName - The name of the collection to check.
+   * @param vectorName - The name of the vector space to validate.
+   * @throws Error if the vector name doesn't exist in the collection.
+   */
+  async validateVectorName(indexName, vectorName) {
+    const { config } = await this.client.getCollection(indexName);
+    const vectorsConfig = config.params.vectors;
+    const isNamedVectors = vectorsConfig && typeof vectorsConfig === "object" && !("size" in vectorsConfig);
+    if (!isNamedVectors || !(vectorName in vectorsConfig)) {
+      throw new Error(`Vector name "${vectorName}" does not exist in collection "${indexName}"`);
+    }
+  }
+  /**
+   * Upserts vectors into the index.
+   * @param indexName - The name of the index to upsert into.
+   * @param vectors - Array of embedding vectors.
+   * @param metadata - Optional metadata for each vector.
+   * @param ids - Optional vector IDs (auto-generated if not provided).
+   * @param vectorName - Optional name of the vector space when using named vectors.
+   */
+  async upsert({ indexName, vectors, metadata, ids, vectorName }) {
     const pointIds = ids || vectors.map(() => crypto.randomUUID());
+    if (vectorName) {
+      try {
+        await this.validateVectorName(indexName, vectorName);
+      } catch (validationError) {
+        throw new MastraError(
+          {
+            id: createVectorErrorId("QDRANT", "UPSERT", "INVALID_VECTOR_NAME"),
+            domain: ErrorDomain.STORAGE,
+            category: ErrorCategory.USER,
+            details: { indexName, vectorName }
+          },
+          validationError
+        );
+      }
+    }
     const records = vectors.map((vector, i) => ({
       id: pointIds[i],
-      vector,
+      vector: vectorName ? { [vectorName]: vector } : vector,
       payload: metadata?.[i] || {}
     }));
     try {
       for (let i = 0; i < records.length; i += BATCH_SIZE) {
         const batch = records.slice(i, i + BATCH_SIZE);
         await this.client.upsert(indexName, {
-          // @ts-expect-error
           points: batch,
           wait: true
         });
@@ -273,19 +309,60 @@ var QdrantVector = class extends MastraVector {
           id: createVectorErrorId("QDRANT", "UPSERT", "FAILED"),
           domain: ErrorDomain.STORAGE,
           category: ErrorCategory.THIRD_PARTY,
-          details: { indexName, vectorCount: vectors.length }
+          details: { indexName, vectorCount: vectors.length, ...vectorName && { vectorName } }
         },
         error
       );
     }
   }
-  async createIndex({ indexName, dimension, metric = "cosine" }) {
+  /**
+   * Creates a new index (collection) in Qdrant.
+   * Supports both single vector and named vector configurations.
+   *
+   * @param indexName - The name of the collection to create.
+   * @param dimension - Vector dimension (required for single vector mode).
+   * @param metric - Distance metric (default: 'cosine').
+   * @param namedVectors - Optional named vector configurations for multi-vector collections.
+   *
+   * @example
+   * ```ts
+   * // Single vector collection
+   * await qdrant.createIndex({ indexName: 'docs', dimension: 768, metric: 'cosine' });
+   *
+   * // Named vectors collection
+   * await qdrant.createIndex({
+   *   indexName: 'multi-modal',
+   *   dimension: 768, // Used as fallback, can be omitted with namedVectors
+   *   namedVectors: {
+   *     text: { size: 768, distance: 'cosine' },
+   *     image: { size: 512, distance: 'euclidean' },
+   *   },
+   * });
+   * ```
+   */
+  async createIndex({ indexName, dimension, metric = "cosine", namedVectors }) {
     try {
-      if (!Number.isInteger(dimension) || dimension <= 0) {
-        throw new Error("Dimension must be a positive integer");
-      }
-      if (!DISTANCE_MAPPING[metric]) {
-        throw new Error(`Invalid metric: "${metric}". Must be one of: cosine, euclidean, dotproduct`);
+      if (namedVectors) {
+        if (Object.keys(namedVectors).length === 0) {
+          throw new Error("namedVectors must contain at least one named vector configuration");
+        }
+        for (const [name, config] of Object.entries(namedVectors)) {
+          if (!Number.isInteger(config.size) || config.size <= 0) {
+            throw new Error(`Named vector "${name}": size must be a positive integer`);
+          }
+          if (!DISTANCE_MAPPING[config.distance]) {
+            throw new Error(
+              `Named vector "${name}": invalid distance "${config.distance}". Must be one of: cosine, euclidean, dotproduct`
+            );
+          }
+        }
+      } else {
+        if (!Number.isInteger(dimension) || dimension <= 0) {
+          throw new Error("Dimension must be a positive integer");
+        }
+        if (!DISTANCE_MAPPING[metric]) {
+          throw new Error(`Invalid metric: "${metric}". Must be one of: cosine, euclidean, dotproduct`);
+        }
       }
     } catch (validationError) {
       throw new MastraError(
@@ -293,22 +370,49 @@ var QdrantVector = class extends MastraVector {
           id: createVectorErrorId("QDRANT", "CREATE_INDEX", "INVALID_ARGS"),
           domain: ErrorDomain.STORAGE,
           category: ErrorCategory.USER,
-          details: { indexName, dimension, metric }
+          details: {
+            indexName,
+            dimension,
+            metric,
+            ...namedVectors && { namedVectorNames: Object.keys(namedVectors).join(", ") }
+          }
         },
         validationError
       );
     }
     try {
-      await this.client.createCollection(indexName, {
-        vectors: {
-          size: dimension,
-          distance: DISTANCE_MAPPING[metric]
-        }
-      });
+      if (namedVectors) {
+        const namedVectorsConfig = Object.entries(namedVectors).reduce(
+          (acc, [name, config]) => {
+            acc[name] = {
+              size: config.size,
+              distance: DISTANCE_MAPPING[config.distance]
+            };
+            return acc;
+          },
+          {}
+        );
+        await this.client.createCollection(indexName, {
+          vectors: namedVectorsConfig
+        });
+      } else {
+        await this.client.createCollection(indexName, {
+          vectors: {
+            size: dimension,
+            distance: DISTANCE_MAPPING[metric]
+          }
+        });
+      }
     } catch (error) {
       const message = error?.message || error?.toString();
       if (error?.status === 409 || typeof message === "string" && message.toLowerCase().includes("exists")) {
-        await this.validateExistingIndex(indexName, dimension, metric);
+        if (!namedVectors) {
+          await this.validateExistingIndex(indexName, dimension, metric);
+        } else {
+          this.logger.info(
+            `Collection "${indexName}" already exists. Skipping validation for named vectors configuration.`
+          );
+        }
         return;
       }
       throw new MastraError(
@@ -326,12 +430,23 @@ var QdrantVector = class extends MastraVector {
     const translator = new QdrantFilterTranslator();
     return translator.translate(filter);
   }
+  /**
+   * Queries the index for similar vectors.
+   *
+   * @param indexName - The name of the index to query.
+   * @param queryVector - The query vector to find similar vectors for.
+   * @param topK - Number of results to return (default: 10).
+   * @param filter - Optional metadata filter.
+   * @param includeVector - Whether to include vectors in results (default: false).
+   * @param using - Name of the vector space to query when using named vectors.
+   */
   async query({
     indexName,
     queryVector,
     topK = 10,
     filter,
-    includeVector = false
+    includeVector = false,
+    using
   }) {
     const translatedFilter = this.transformFilter(filter) ?? {};
     try {
@@ -340,15 +455,20 @@ var QdrantVector = class extends MastraVector {
         limit: topK,
         filter: translatedFilter,
         with_payload: true,
-        with_vector: includeVector
+        with_vector: includeVector,
+        ...using ? { using } : {}
       })).points;
       return results.map((match) => {
         let vector = [];
-        if (includeVector) {
+        if (includeVector && match.vector != null) {
           if (Array.isArray(match.vector)) {
             vector = match.vector;
           } else if (typeof match.vector === "object" && match.vector !== null) {
-            vector = Object.values(match.vector).filter((v) => typeof v === "number");
+            const namedVectors = match.vector;
+            const sourceArray = using && Array.isArray(namedVectors[using]) ? namedVectors[using] : Object.values(namedVectors).find((v) => Array.isArray(v));
+            if (sourceArray) {
+              vector = sourceArray.filter((v) => typeof v === "number");
+            }
           }
         }
         return {
@@ -364,7 +484,7 @@ var QdrantVector = class extends MastraVector {
           id: createVectorErrorId("QDRANT", "QUERY", "FAILED"),
           domain: ErrorDomain.STORAGE,
           category: ErrorCategory.THIRD_PARTY,
-          details: { indexName, topK }
+          details: { indexName, topK, ...using && { using } }
         },
         error
       );
@@ -723,6 +843,161 @@ var QdrantVector = class extends MastraVector {
       );
     }
   }
+  /**
+   * Creates a payload index on a Qdrant collection to enable efficient filtering on metadata fields.
+   *
+   * This is required for Qdrant Cloud and any Qdrant instance with `strict_mode_config = true`,
+   * where metadata (payload) fields must be explicitly indexed before they can be used for filtering.
+   *
+   * @param params - The parameters for creating the payload index.
+   * @param params.indexName - The name of the collection (index) to create the payload index on.
+   * @param params.fieldName - The name of the payload field to index.
+   * @param params.fieldSchema - The schema type for the field (e.g., 'keyword', 'integer', 'text').
+   * @param params.wait - Whether to wait for the operation to complete. Defaults to true.
+   * @returns A promise that resolves when the index is created (idempotent if index already exists).
+   * @throws Will throw a MastraError if arguments are invalid or if the operation fails.
+   *
+   * @example
+   * ```ts
+   * // Create a keyword index for filtering by source
+   * await qdrant.createPayloadIndex({
+   *   indexName: 'my-collection',
+   *   fieldName: 'source',
+   *   fieldSchema: 'keyword',
+   * });
+   *
+   * // Create an integer index for numeric filtering
+   * await qdrant.createPayloadIndex({
+   *   indexName: 'my-collection',
+   *   fieldName: 'price',
+   *   fieldSchema: 'integer',
+   * });
+   * ```
+   *
+   * @see https://qdrant.tech/documentation/concepts/indexing/#payload-index
+   */
+  async createPayloadIndex({
+    indexName,
+    fieldName,
+    fieldSchema,
+    wait = true
+  }) {
+    const validSchemas = [
+      "keyword",
+      "integer",
+      "float",
+      "geo",
+      "text",
+      "bool",
+      "datetime",
+      "uuid"
+    ];
+    if (!indexName || typeof indexName !== "string" || indexName.trim() === "") {
+      throw new MastraError({
+        id: createVectorErrorId("QDRANT", "CREATE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: "indexName must be a non-empty string",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        details: { indexName, fieldName, fieldSchema }
+      });
+    }
+    if (!fieldName || typeof fieldName !== "string" || fieldName.trim() === "") {
+      throw new MastraError({
+        id: createVectorErrorId("QDRANT", "CREATE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: "fieldName must be a non-empty string",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        details: { indexName, fieldName, fieldSchema }
+      });
+    }
+    if (!validSchemas.includes(fieldSchema)) {
+      throw new MastraError({
+        id: createVectorErrorId("QDRANT", "CREATE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: `fieldSchema must be one of: ${validSchemas.join(", ")}`,
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        details: { indexName, fieldName, fieldSchema }
+      });
+    }
+    try {
+      await this.client.createPayloadIndex(indexName, {
+        field_name: fieldName,
+        field_schema: fieldSchema,
+        wait
+      });
+    } catch (error) {
+      const message = error?.message || error?.toString() || "";
+      if (error?.status === 409 || message.toLowerCase().includes("exists")) {
+        this.logger.info(`Payload index for field "${fieldName}" already exists on collection "${indexName}"`);
+        return;
+      }
+      throw new MastraError(
+        {
+          id: createVectorErrorId("QDRANT", "CREATE_PAYLOAD_INDEX", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, fieldName, fieldSchema }
+        },
+        error
+      );
+    }
+  }
+  /**
+   * Deletes a payload index from a Qdrant collection.
+   *
+   * @param params - The parameters for deleting the payload index.
+   * @param params.indexName - The name of the collection (index) to delete the payload index from.
+   * @param params.fieldName - The name of the payload field index to delete.
+   * @param params.wait - Whether to wait for the operation to complete. Defaults to true.
+   * @returns A promise that resolves when the index is deleted (idempotent if index doesn't exist).
+   * @throws Will throw a MastraError if the operation fails.
+   *
+   * @example
+   * ```ts
+   * await qdrant.deletePayloadIndex({
+   *   indexName: 'my-collection',
+   *   fieldName: 'source',
+   * });
+   * ```
+   */
+  async deletePayloadIndex({ indexName, fieldName, wait = true }) {
+    if (!indexName || typeof indexName !== "string" || indexName.trim() === "") {
+      throw new MastraError({
+        id: createVectorErrorId("QDRANT", "DELETE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: "indexName must be a non-empty string",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        details: { indexName, fieldName }
+      });
+    }
+    if (!fieldName || typeof fieldName !== "string" || fieldName.trim() === "") {
+      throw new MastraError({
+        id: createVectorErrorId("QDRANT", "DELETE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: "fieldName must be a non-empty string",
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        details: { indexName, fieldName }
+      });
+    }
+    try {
+      await this.client.deletePayloadIndex(indexName, fieldName, { wait });
+    } catch (error) {
+      const message = error?.message || error?.toString() || "";
+      if (error?.status === 404 || message.toLowerCase().includes("not found") || message.toLowerCase().includes("not exist")) {
+        this.logger.info(`Payload index for field "${fieldName}" does not exist on collection "${indexName}"`);
+        return;
+      }
+      throw new MastraError(
+        {
+          id: createVectorErrorId("QDRANT", "DELETE_PAYLOAD_INDEX", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, fieldName }
+        },
+        error
+      );
+    }
+  }
 };
 
 // src/vector/prompt.ts