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

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @mastra/qdrant
 
+## 1.0.0-beta.5
+
+### Minor Changes
+
+- Add full support for Qdrant named vectors, allowing collections with multiple vector spaces. ([#11905](https://github.com/mastra-ai/mastra/pull/11905))
+  - Added `namedVectors` parameter to `createIndex()` for creating multi-vector collections
+  - Added `vectorName` parameter to `upsert()` for inserting into specific vector spaces
+  - Added `using` parameter to `query()` for querying specific vector spaces
+  - Changed `client` from `private` to `protected` to enable subclass extension
+  - Added vector name validation when upserting to named vector collections
+
+### Patch Changes
+
+- Updated dependencies [[`1dbd8c7`](https://github.com/mastra-ai/mastra/commit/1dbd8c729fb6536ec52f00064d76b80253d346e9), [`c59e13c`](https://github.com/mastra-ai/mastra/commit/c59e13c7688284bd96b2baee3e314335003548de), [`f9a2509`](https://github.com/mastra-ai/mastra/commit/f9a25093ea72d210a5e52cfcb3bcc8b5e02dc25c), [`7a010c5`](https://github.com/mastra-ai/mastra/commit/7a010c56b846a313a49ae42fccd3d8de2b9f292d)]:
+  - @mastra/core@1.0.0-beta.24
+
 ## 1.0.0-beta.4
 
 ### Minor Changes

package/README.md

@@ -13,11 +13,11 @@ pnpm add @mastra/qdrant
 ```typescript
 import { QdrantVector } from '@mastra/qdrant';
 
-const vectorStore = new QdrantVector(
-  'http://localhost:6333', // url
-  'optional-api-key',      // optional
-  false                    // https (optional)
-);
+const vectorStore = new QdrantVector({
+  id: 'my-qdrant',
+  url: 'http://localhost:6333',
+  apiKey: 'optional-api-key', // optional
+});
 
 // Create a new collection
 await vectorStore.createIndex({ indexName: 'myCollection', dimension: 1536, metric: 'cosine' });
@@ -31,9 +31,61 @@ const ids = await vectorStore.upsert({ indexName: 'myCollection', vectors, metad
 const results = await vectorStore.query({
   indexName: 'myCollection',
   queryVector: [0.1, 0.2, ...],
-  topK: 10, // topK
+  topK: 10,
   filter: { text: { $eq: 'doc1' } }, // optional filter
-  includeVector: false // includeVector
+  includeVector: false,
+});
+
+// Query with named vectors (for collections with multiple vector fields)
+const namedResults = await vectorStore.query({
+  indexName: 'myCollection',
+  queryVector: [0.1, 0.2, ...],
+  topK: 10,
+  using: 'title_embedding', // specify which named vector to query
+});
+```
+
+## Named Vectors
+
+Qdrant supports [named vectors](https://qdrant.tech/documentation/concepts/vectors/#named-vectors), allowing multiple vector fields per collection. This is useful for multi-modal data (text + images) or different embedding models.
+
+```typescript
+// Create a collection with multiple named vector spaces
+await vectorStore.createIndex({
+  indexName: 'multi_modal',
+  dimension: 768, // fallback
+  namedVectors: {
+    text: { size: 768, distance: 'cosine' },
+    image: { size: 512, distance: 'euclidean' },
+  },
+});
+
+// Upsert into specific vector spaces
+await vectorStore.upsert({
+  indexName: 'multi_modal',
+  vectors: textEmbeddings,
+  metadata: [{ type: 'text' }],
+  vectorName: 'text', // target the text vector space
+});
+
+await vectorStore.upsert({
+  indexName: 'multi_modal',
+  vectors: imageEmbeddings,
+  metadata: [{ type: 'image' }],
+  vectorName: 'image', // target the image vector space
+});
+
+// Query specific vector spaces
+const textResults = await vectorStore.query({
+  indexName: 'multi_modal',
+  queryVector: textQuery,
+  using: 'text',
+});
+
+const imageResults = await vectorStore.query({
+  indexName: 'multi_modal',
+  queryVector: imageQuery,
+  using: 'image',
 });
 ```
 
@@ -41,6 +93,7 @@ const results = await vectorStore.query({
 
 Required:
 
+- `id`: Unique identifier for this vector store instance
 - `url`: URL of your Qdrant instance
 
 Optional:
@@ -51,6 +104,7 @@ Optional:
 ## Features
 
 - Vector similarity search with Cosine, Euclidean, and Dot Product metrics
+- [Named vectors](https://qdrant.tech/documentation/concepts/vectors/#named-vectors) support for collections with multiple vector fields
 - Automatic batching for large upserts (256 vectors per batch)
 - Built-in telemetry support
 - Metadata filtering
@@ -69,12 +123,14 @@ The following distance metrics are supported:
 
 ## Methods
 
-- `createIndex({ indexName, dimension, metric? })`: Create a new collection
-- `upsert({ indexName, vectors, metadata?, ids? })`: Add or update vectors
-- `query({ indexName, queryVector, topK?, filter?, includeVector? })`: Search for similar vectors
+- `createIndex({ indexName, dimension, metric?, namedVectors? })`: Create a new collection (supports named vectors)
+- `upsert({ indexName, vectors, metadata?, ids?, vectorName? })`: Add or update vectors (supports named vectors)
+- `query({ indexName, queryVector, topK?, filter?, includeVector?, using? })`: Search for similar vectors
 - `updateVector({ indexName, id?, filter?, update })`: Update a single vector by ID or metadata filter
 - `deleteVector({ indexName, id })`: Delete a single vector by ID
 - `deleteVectors({ indexName, ids?, filter? })`: Delete multiple vectors by IDs or metadata filter
+- `createPayloadIndex({ indexName, fieldName, fieldSchema, wait? })`: Create a payload index for filtering
+- `deletePayloadIndex({ indexName, fieldName, wait? })`: Delete a payload index
 - `listIndexes()`: List all collections
 - `describeIndex(indexName)`: Get collection statistics
 - `deleteIndex(indexName)`: Delete a collection

package/dist/docs/README.md

@@ -29,4 +29,4 @@ docs/
 ## Version
 
 Package: @mastra/qdrant
-Version: 1.0.0-beta.4
+Version: 1.0.0-beta.5

package/dist/docs/SKILL.md

@@ -5,7 +5,7 @@ description: Documentation for @mastra/qdrant. Includes links to type definition
 
 # @mastra/qdrant Documentation
 
-> **Version**: 1.0.0-beta.4
+> **Version**: 1.0.0-beta.5
 > **Package**: @mastra/qdrant
 
 ## Quick Navigation

package/dist/docs/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.5",
   "package": "@mastra/qdrant",
   "exports": {},
   "modules": {}

package/dist/docs/rag/01-vector-databases.md

@@ -27,7 +27,7 @@ await store.upsert({
 });
 ```
 
-### Using MongoDB Atlas Vector search
+<h3>Using MongoDB Atlas Vector search</h3>
 
 For detailed setup instructions and best practices, see the [official MongoDB Atlas Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/?utm_campaign=devrel&utm_source=third-party-content&utm_medium=cta&utm_content=mastra-docs).
 
@@ -55,7 +55,7 @@ await store.upsert({
 });
 ```
 
-### Using PostgreSQL with pgvector
+<h3>Using PostgreSQL with pgvector</h3>
 
 PostgreSQL with the pgvector extension is a good solution for teams already using PostgreSQL who want to minimize infrastructure complexity.
 For detailed setup instructions and best practices, see the [official pgvector repository](https://github.com/pgvector/pgvector).
@@ -323,7 +323,7 @@ await store.upsert({
 });
 ```
 
-### Using LanceDB
+<h3>Using LanceDB</h3>
 
 LanceDB is an embedded vector database built on the Lance columnar format, suitable for local development or cloud deployment.
 For detailed setup instructions and best practices, see the [official LanceDB documentation](https://lancedb.github.io/lancedb/).

package/dist/docs/vectors/01-reference.md

@@ -18,10 +18,57 @@ It provides a production-ready service with a convenient API to store, search, a
 
 ### createIndex()
 
+#### Creating a Named Vectors Collection
+
+```typescript
+// Create a collection with multiple named vector spaces
+await store.createIndex({
+  indexName: "multi_modal",
+  dimension: 768, // fallback
+  namedVectors: {
+    text: { size: 768, distance: "cosine" },
+    image: { size: 512, distance: "euclidean" },
+  },
+});
+```
+
 ### upsert()
 
+#### Upserting into Named Vector Spaces
+
+```typescript
+// Upsert into the "text" vector space
+await store.upsert({
+  indexName: "multi_modal",
+  vectors: textEmbeddings,
+  metadata: textMetadata,
+  vectorName: "text",
+});
+
+// Upsert into the "image" vector space
+await store.upsert({
+  indexName: "multi_modal",
+  vectors: imageEmbeddings,
+  metadata: imageMetadata,
+  vectorName: "image",
+});
+```
+
 ### query()
 
+#### Named Vectors
+
+Qdrant supports [named vectors](https://qdrant.tech/documentation/concepts/vectors/#named-vectors), allowing multiple vector fields per collection. Use the `using` parameter to specify which named vector to query against:
+
+```typescript
+const results = await store.query({
+  indexName: "my_index",
+  queryVector: embedding,
+  topK: 10,
+  using: "title_embedding", // Query against a specific named vector
+});
+```
+
 ### listIndexes()
 
 Returns an array of index names as strings.

package/dist/index.cjs

@@ -252,18 +252,54 @@ var QdrantVector = class extends vector.MastraVector {
     super({ id });
     this.client = new jsClientRest.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 error.MastraError(
+          {
+            id: storage.createVectorErrorId("QDRANT", "UPSERT", "INVALID_VECTOR_NAME"),
+            domain: error.ErrorDomain.STORAGE,
+            category: error.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
         });
@@ -275,19 +311,60 @@ var QdrantVector = class extends vector.MastraVector {
           id: storage.createVectorErrorId("QDRANT", "UPSERT", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
-          details: { indexName, vectorCount: vectors.length }
+          details: { indexName, vectorCount: vectors.length, ...vectorName && { vectorName } }
         },
         error$1
       );
     }
   }
-  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 error.MastraError(
@@ -295,22 +372,49 @@ var QdrantVector = class extends vector.MastraVector {
           id: storage.createVectorErrorId("QDRANT", "CREATE_INDEX", "INVALID_ARGS"),
           domain: error.ErrorDomain.STORAGE,
           category: error.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$1) {
       const message = error$1?.message || error$1?.toString();
       if (error$1?.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 error.MastraError(
@@ -328,12 +432,23 @@ var QdrantVector = class extends vector.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 {
@@ -342,15 +457,20 @@ var QdrantVector = class extends vector.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 {
@@ -366,7 +486,7 @@ var QdrantVector = class extends vector.MastraVector {
           id: storage.createVectorErrorId("QDRANT", "QUERY", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
-          details: { indexName, topK }
+          details: { indexName, topK, ...using && { using } }
         },
         error$1
       );