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

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @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
+
+- Added support for creating payload (metadata) indexes in Qdrant ([#11839](https://github.com/mastra-ai/mastra/pull/11839))
+
+  Qdrant Cloud and deployments with `strict_mode_config = true` require explicit payload indexes for metadata filtering. This release adds two new methods to `QdrantVector`:
+
+  **New exports:**
+  - `PayloadSchemaType` - Union type for Qdrant payload schema types ('keyword', 'integer', 'float', 'geo', 'text', 'bool', 'datetime', 'uuid')
+  - `CreatePayloadIndexParams` - Parameters interface for creating payload indexes
+  - `DeletePayloadIndexParams` - Parameters interface for deleting payload indexes
+
+  **New methods:**
+  - `createPayloadIndex()` - Creates a payload index on a collection field for efficient filtering
+  - `deletePayloadIndex()` - Removes a payload index from a collection field
+
+  **Example usage:**
+
+  ```typescript
+  import { QdrantVector } from '@mastra/qdrant';
+
+  const qdrant = new QdrantVector({ url: `http://localhost:6333`, id: 'my-store' });
+
+  // Create a keyword index for filtering by source
+  await qdrant.createPayloadIndex({
+    indexName: 'my-collection',
+    fieldName: 'source',
+    fieldSchema: 'keyword',
+  });
+
+  // Now filtering works in strict mode environments
+  const results = await qdrant.query({
+    indexName: 'my-collection',
+    queryVector: embeddings,
+    filter: { source: 'document-a' },
+  });
+  ```
+
+  Closes #8923
+
+### Patch Changes
+
+- Updated dependencies [[`ebae12a`](https://github.com/mastra-ai/mastra/commit/ebae12a2dd0212e75478981053b148a2c246962d), [`c61a0a5`](https://github.com/mastra-ai/mastra/commit/c61a0a5de4904c88fd8b3718bc26d1be1c2ec6e7), [`69136e7`](https://github.com/mastra-ai/mastra/commit/69136e748e32f57297728a4e0f9a75988462f1a7), [`449aed2`](https://github.com/mastra-ai/mastra/commit/449aed2ba9d507b75bf93d427646ea94f734dfd1), [`eb648a2`](https://github.com/mastra-ai/mastra/commit/eb648a2cc1728f7678768dd70cd77619b448dab9), [`0131105`](https://github.com/mastra-ai/mastra/commit/0131105532e83bdcbb73352fc7d0879eebf140dc), [`9d5059e`](https://github.com/mastra-ai/mastra/commit/9d5059eae810829935fb08e81a9bb7ecd5b144a7), [`ef756c6`](https://github.com/mastra-ai/mastra/commit/ef756c65f82d16531c43f49a27290a416611e526), [`b00ccd3`](https://github.com/mastra-ai/mastra/commit/b00ccd325ebd5d9e37e34dd0a105caae67eb568f), [`3bdfa75`](https://github.com/mastra-ai/mastra/commit/3bdfa7507a91db66f176ba8221aa28dd546e464a), [`e770de9`](https://github.com/mastra-ai/mastra/commit/e770de941a287a49b1964d44db5a5763d19890a6), [`52e2716`](https://github.com/mastra-ai/mastra/commit/52e2716b42df6eff443de72360ae83e86ec23993), [`27b4040`](https://github.com/mastra-ai/mastra/commit/27b4040bfa1a95d92546f420a02a626b1419a1d6), [`610a70b`](https://github.com/mastra-ai/mastra/commit/610a70bdad282079f0c630e0d7bb284578f20151), [`8dc7f55`](https://github.com/mastra-ai/mastra/commit/8dc7f55900395771da851dc7d78d53ae84fe34ec), [`8379099`](https://github.com/mastra-ai/mastra/commit/8379099fc467af6bef54dd7f80c9bd75bf8bbddf), [`8c0ec25`](https://github.com/mastra-ai/mastra/commit/8c0ec25646c8a7df253ed1e5ff4863a0d3f1316c), [`ff4d9a6`](https://github.com/mastra-ai/mastra/commit/ff4d9a6704fc87b31a380a76ed22736fdedbba5a), [`69821ef`](https://github.com/mastra-ai/mastra/commit/69821ef806482e2c44e2197ac0b050c3fe3a5285), [`1ed5716`](https://github.com/mastra-ai/mastra/commit/1ed5716830867b3774c4a1b43cc0d82935f32b96), [`4186bdd`](https://github.com/mastra-ai/mastra/commit/4186bdd00731305726fa06adba0b076a1d50b49f), [`7aaf973`](https://github.com/mastra-ai/mastra/commit/7aaf973f83fbbe9521f1f9e7a4fd99b8de464617)]:
+  - @mastra/core@1.0.0-beta.22
+
 ## 1.0.0-beta.3
 
 ### Patch 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.3
+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.3
+> **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.3",
+  "version": "1.0.0-beta.5",
   "package": "@mastra/qdrant",
   "exports": {},
   "modules": {}

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

@@ -12,6 +12,7 @@ After generating embeddings, you need to store them in a database that supports
 import { MongoDBVector } from "@mastra/mongodb";
 
 const store = new MongoDBVector({
+  id: 'mongodb-vector',
   uri: process.env.MONGODB_URI,
   dbName: process.env.MONGODB_DATABASE,
 });
@@ -26,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).
 
@@ -54,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).
@@ -144,6 +145,7 @@ await store.upsert({
 import { AstraVector } from "@mastra/astra";
 
 const store = new AstraVector({
+  id: 'astra-vector',
   token: process.env.ASTRA_DB_TOKEN,
   endpoint: process.env.ASTRA_DB_ENDPOINT,
   keyspace: process.env.ASTRA_DB_KEYSPACE,
@@ -170,7 +172,7 @@ import { LibSQLVector } from "@mastra/core/vector/libsql";
 
 const store = new LibSQLVector({
   id: 'libsql-vector',
-  connectionUrl: process.env.DATABASE_URL,
+  url: process.env.DATABASE_URL,
   authToken: process.env.DATABASE_AUTH_TOKEN, // Optional: for Turso cloud databases
 });
 
@@ -217,6 +219,7 @@ await store.upsert({
 import { CloudflareVector } from "@mastra/vectorize";
 
 const store = new CloudflareVector({
+  id: 'cloudflare-vector',
   accountId: process.env.CF_ACCOUNT_ID,
   apiToken: process.env.CF_API_TOKEN,
 });
@@ -238,7 +241,7 @@ await store.upsert({
 ```ts title="vector-store.ts"
 import { OpenSearchVector } from "@mastra/opensearch";
 
-const store = new OpenSearchVector({ url: process.env.OPENSEARCH_URL });
+const store = new OpenSearchVector({ id: "opensearch", node: process.env.OPENSEARCH_URL });
 
 await store.createIndex({
   indexName: "my-collection",
@@ -259,7 +262,7 @@ await store.upsert({
 ```ts title="vector-store.ts"
 import { ElasticSearchVector } from "@mastra/elasticsearch";
 
-const store = new ElasticSearchVector({ url: process.env.ELASTICSEARCH_URL });
+const store = new ElasticSearchVector({ id: 'elasticsearch-vector', url: process.env.ELASTICSEARCH_URL });
 
 await store.createIndex({
   indexName: "my-collection",
@@ -280,6 +283,7 @@ await store.upsert({
 import { CouchbaseVector } from "@mastra/couchbase";
 
 const store = new CouchbaseVector({
+  id: 'couchbase-vector',
   connectionString: process.env.COUCHBASE_CONNECTION_STRING,
   username: process.env.COUCHBASE_USERNAME,
   password: process.env.COUCHBASE_PASSWORD,
@@ -319,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/).
@@ -331,6 +335,7 @@ For detailed setup instructions and best practices, see the [official LanceDB do
 import { S3Vectors } from "@mastra/s3vectors";
 
 const store = new S3Vectors({
+  id: 's3-vectors',
   vectorBucketName: "my-vector-bucket",
   clientConfig: {
     region: "us-east-1",
@@ -373,7 +378,7 @@ The dimension size must match the output dimension of your chosen embedding mode
 - Cohere embed-multilingual-v3: 1024 dimensions
 - Google text-embedding-004: 768 dimensions (or custom)
 
-important
+> **Note:**
 Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
 
 ### Naming Rules for Databases
@@ -537,7 +542,7 @@ The upsert operation:
 
 Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
 
-important
+> **Note:**
 Metadata is crucial for vector storage - without it, you'd only have numerical embeddings with no way to return the original text or filter results. Always store at least the source text as metadata.
 
 ```ts

package/dist/docs/rag/02-retrieval.md

@@ -171,7 +171,7 @@ The Vector Query Tool supports database-specific configurations that enable you
 > **Note:**
 These configurations are for **query-time options** like namespaces, performance tuning, and filtering—not for database connection setup. 
 
-Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ connectionUrl: '...' })`).
+Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ url: '...' })`).
 
 ```ts
 import { createVectorQueryTool } from "@mastra/rag";
@@ -258,11 +258,10 @@ requestContext.set("databaseConfig", {
   },
 });
 
-await pineconeQueryTool.execute({
-  context: { queryText: "search query" },
-  mastra,
-  requestContext,
-});
+await pineconeQueryTool.execute(
+  { queryText: "search query" },
+  { mastra, requestContext }
+);
 ```
 
 For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](https://mastra.ai/reference/v1/tools/vector-query-tool).

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.
@@ -54,6 +101,29 @@ Deletes a vector from the specified index by its ID.
 
 Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
 
+### createPayloadIndex()
+
+Creates a payload (metadata) index on a collection field to enable efficient filtering. This is **required** for Qdrant Cloud and any Qdrant instance with `strict_mode_config = true`.
+
+```typescript
+// Create a keyword index for filtering by source
+await store.createPayloadIndex({
+  indexName: "my_index",
+  fieldName: "source",
+  fieldSchema: "keyword",
+});
+
+const results = await store.query({
+  indexName: "my_index",
+  queryVector: queryVector,
+  filter: { source: "document-a" },
+});
+```
+
+### deletePayloadIndex()
+
+Removes a payload index from a collection field.
+
 ## Response Types
 
 Query results are returned in this format: