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

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @mastra/qdrant
 
+## 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/dist/docs/README.md

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

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.4
 > **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.4",
   "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,
 });
@@ -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,
@@ -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

@@ -54,6 +54,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:

package/dist/index.cjs

@@ -725,6 +725,161 @@ var QdrantVector = class extends vector.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 error.MastraError({
+        id: storage.createVectorErrorId("QDRANT", "CREATE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: "indexName must be a non-empty string",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName, fieldName, fieldSchema }
+      });
+    }
+    if (!fieldName || typeof fieldName !== "string" || fieldName.trim() === "") {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("QDRANT", "CREATE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: "fieldName must be a non-empty string",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName, fieldName, fieldSchema }
+      });
+    }
+    if (!validSchemas.includes(fieldSchema)) {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("QDRANT", "CREATE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: `fieldSchema must be one of: ${validSchemas.join(", ")}`,
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName, fieldName, fieldSchema }
+      });
+    }
+    try {
+      await this.client.createPayloadIndex(indexName, {
+        field_name: fieldName,
+        field_schema: fieldSchema,
+        wait
+      });
+    } catch (error$1) {
+      const message = error$1?.message || error$1?.toString() || "";
+      if (error$1?.status === 409 || message.toLowerCase().includes("exists")) {
+        this.logger.info(`Payload index for field "${fieldName}" already exists on collection "${indexName}"`);
+        return;
+      }
+      throw new error.MastraError(
+        {
+          id: storage.createVectorErrorId("QDRANT", "CREATE_PAYLOAD_INDEX", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName, fieldName, fieldSchema }
+        },
+        error$1
+      );
+    }
+  }
+  /**
+   * 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 error.MastraError({
+        id: storage.createVectorErrorId("QDRANT", "DELETE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: "indexName must be a non-empty string",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName, fieldName }
+      });
+    }
+    if (!fieldName || typeof fieldName !== "string" || fieldName.trim() === "") {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("QDRANT", "DELETE_PAYLOAD_INDEX", "INVALID_ARGS"),
+        text: "fieldName must be a non-empty string",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName, fieldName }
+      });
+    }
+    try {
+      await this.client.deletePayloadIndex(indexName, fieldName, { wait });
+    } catch (error$1) {
+      const message = error$1?.message || error$1?.toString() || "";
+      if (error$1?.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 error.MastraError(
+        {
+          id: storage.createVectorErrorId("QDRANT", "DELETE_PAYLOAD_INDEX", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName, fieldName }
+        },
+        error$1
+      );
+    }
+  }
 };
 
 // src/vector/prompt.ts