@mastra/convex 1.0.3 → 1.0.4-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @mastra/convex
 
+## 1.0.4-alpha.0
+
+### Patch Changes
+
+- Add a clear runtime error when `queryVector` is omitted for vector stores that require a vector for queries. Previously, omitting `queryVector` would produce confusing SDK-level errors; now each store throws a structured `MastraError` with `ErrorCategory.USER` explaining that metadata-only queries are not supported by that backend. ([#13286](https://github.com/mastra-ai/mastra/pull/13286))
+
+- Updated dependencies [[`df170fd`](https://github.com/mastra-ai/mastra/commit/df170fd139b55f845bfd2de8488b16435bd3d0da), [`ae55343`](https://github.com/mastra-ai/mastra/commit/ae5534397fc006fd6eef3e4f80c235bcdc9289ef), [`c290cec`](https://github.com/mastra-ai/mastra/commit/c290cec5bf9107225de42942b56b487107aa9dce), [`f03e794`](https://github.com/mastra-ai/mastra/commit/f03e794630f812b56e95aad54f7b1993dc003add), [`aa4a5ae`](https://github.com/mastra-ai/mastra/commit/aa4a5aedb80d8d6837bab8cbb2e301215d1ba3e9), [`de3f584`](https://github.com/mastra-ai/mastra/commit/de3f58408752a8d80a295275c7f23fc306cf7f4f), [`d3fb010`](https://github.com/mastra-ai/mastra/commit/d3fb010c98f575f1c0614452667396e2653815f6), [`702ee1c`](https://github.com/mastra-ai/mastra/commit/702ee1c41be67cc532b4dbe89bcb62143508f6f0), [`f495051`](https://github.com/mastra-ai/mastra/commit/f495051eb6496a720f637fc85b6d69941c12554c), [`e622f1d`](https://github.com/mastra-ai/mastra/commit/e622f1d3ab346a8e6aca6d1fe2eac99bd961e50b), [`861f111`](https://github.com/mastra-ai/mastra/commit/861f11189211b20ddb70d8df81a6b901fc78d11e), [`00f43e8`](https://github.com/mastra-ai/mastra/commit/00f43e8e97a80c82b27d5bd30494f10a715a1df9), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`96a1702`](https://github.com/mastra-ai/mastra/commit/96a1702ce362c50dda20c8b4a228b4ad1a36a17a), [`cb9f921`](https://github.com/mastra-ai/mastra/commit/cb9f921320913975657abb1404855d8c510f7ac5), [`114e7c1`](https://github.com/mastra-ai/mastra/commit/114e7c146ac682925f0fb37376c1be70e5d6e6e5), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`72df4a8`](https://github.com/mastra-ai/mastra/commit/72df4a8f9bf1a20cfd3d9006a4fdb597ad56d10a)]:
+  - @mastra/core@1.8.0-alpha.0
+
 ## 1.0.3
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-convex
 description: Documentation for @mastra/convex. Use when working with @mastra/convex APIs, configuration, or implementation.
 metadata:
   package: "@mastra/convex"
-  version: "1.0.3"
+  version: "1.0.4-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.3",
+  "version": "1.0.4-alpha.0",
   "package": "@mastra/convex",
   "exports": {
     "mastraStorage": {

package/dist/docs/references/reference-storage-convex.md

@@ -41,7 +41,7 @@ Before using `ConvexStore`, you need to set up the Convex schema and storage han
 In `convex/schema.ts`:
 
 ```typescript
-import { defineSchema } from 'convex/server';
+import { defineSchema } from 'convex/server'
 import {
   mastraThreadsTable,
   mastraMessagesTable,
@@ -51,7 +51,7 @@ import {
   mastraVectorIndexesTable,
   mastraVectorsTable,
   mastraDocumentsTable,
-} from '@mastra/convex/schema';
+} from '@mastra/convex/schema'
 
 export default defineSchema({
   mastra_threads: mastraThreadsTable,
@@ -62,7 +62,7 @@ export default defineSchema({
   mastra_vector_indexes: mastraVectorIndexesTable,
   mastra_vectors: mastraVectorsTable,
   mastra_documents: mastraDocumentsTable,
-});
+})
 ```
 
 ### 2. Create the Storage Handler
@@ -70,9 +70,9 @@ export default defineSchema({
 In `convex/mastra/storage.ts`:
 
 ```typescript
-import { mastraStorage } from '@mastra/convex/server';
+import { mastraStorage } from '@mastra/convex/server'
 
-export const handle = mastraStorage;
+export const handle = mastraStorage
 ```
 
 ### 3. Deploy to Convex
@@ -86,13 +86,13 @@ npx convex deploy
 ## Usage
 
 ```typescript
-import { ConvexStore } from "@mastra/convex";
+import { ConvexStore } from '@mastra/convex'
 
 const storage = new ConvexStore({
   id: 'convex-storage',
   deploymentUrl: process.env.CONVEX_URL!,
   adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
-});
+})
 ```
 
 ## Parameters
@@ -106,22 +106,22 @@ const storage = new ConvexStore({
 ## Constructor Examples
 
 ```ts
-import { ConvexStore } from "@mastra/convex";
+import { ConvexStore } from '@mastra/convex'
 
 // Basic configuration
 const store = new ConvexStore({
   id: 'convex-storage',
-  deploymentUrl: "https://your-project.convex.cloud",
-  adminAuthToken: "your-admin-token",
-});
+  deploymentUrl: 'https://your-project.convex.cloud',
+  adminAuthToken: 'your-admin-token',
+})
 
 // With custom storage function path
 const storeCustom = new ConvexStore({
   id: 'convex-storage',
-  deploymentUrl: "https://your-project.convex.cloud",
-  adminAuthToken: "your-admin-token",
-  storageFunction: "custom/path:handler",
-});
+  deploymentUrl: 'https://your-project.convex.cloud',
+  adminAuthToken: 'your-admin-token',
+  storageFunction: 'custom/path:handler',
+})
 ```
 
 ## Additional Notes

package/dist/docs/references/reference-vectors-convex.md

@@ -45,13 +45,13 @@ Before using `ConvexVector`, you need to set up the Convex schema and storage ha
 ### Basic Configuration
 
 ```ts
-import { ConvexVector } from "@mastra/convex";
+import { ConvexVector } from '@mastra/convex'
 
 const vectorStore = new ConvexVector({
   id: 'convex-vectors',
-  deploymentUrl: "https://your-project.convex.cloud",
-  adminAuthToken: "your-admin-token",
-});
+  deploymentUrl: 'https://your-project.convex.cloud',
+  adminAuthToken: 'your-admin-token',
+})
 ```
 
 ### Custom Storage Function
@@ -59,10 +59,10 @@ const vectorStore = new ConvexVector({
 ```ts
 const vectorStore = new ConvexVector({
   id: 'convex-vectors',
-  deploymentUrl: "https://your-project.convex.cloud",
-  adminAuthToken: "your-admin-token",
-  storageFunction: "custom/path:handler",
-});
+  deploymentUrl: 'https://your-project.convex.cloud',
+  adminAuthToken: 'your-admin-token',
+  storageFunction: 'custom/path:handler',
+})
 ```
 
 ## Methods
@@ -77,9 +77,9 @@ const vectorStore = new ConvexVector({
 
 ```typescript
 await vectorStore.createIndex({
-  indexName: "my_vectors",
+  indexName: 'my_vectors',
   dimension: 1536,
-});
+})
 ```
 
 ### upsert()
@@ -127,7 +127,7 @@ const results = await vectorStore.query({
 Returns an array of index names as strings.
 
 ```typescript
-const indexes = await vectorStore.listIndexes();
+const indexes = await vectorStore.listIndexes()
 // ["my_vectors", "embeddings", ...]
 ```
 
@@ -139,9 +139,9 @@ Returns:
 
 ```typescript
 interface IndexStats {
-  dimension: number;
-  count: number;
-  metric: "cosine" | "euclidean" | "dotproduct";
+  dimension: number
+  count: number
+  metric: 'cosine' | 'euclidean' | 'dotproduct'
 }
 ```
 
@@ -152,7 +152,7 @@ interface IndexStats {
 Deletes the index and all its vectors.
 
 ```typescript
-await vectorStore.deleteIndex({ indexName: "my_vectors" });
+await vectorStore.deleteIndex({ indexName: 'my_vectors' })
 ```
 
 ### updateVector()
@@ -170,22 +170,22 @@ Update a single vector by ID or by metadata filter. Either `id` or `filter` must
 ```typescript
 // Update by ID
 await vectorStore.updateVector({
-  indexName: "my_vectors",
-  id: "vector123",
+  indexName: 'my_vectors',
+  id: 'vector123',
   update: {
     vector: [0.1, 0.2, 0.3],
-    metadata: { label: "updated" },
+    metadata: { label: 'updated' },
   },
-});
+})
 
 // Update by filter
 await vectorStore.updateVector({
-  indexName: "my_vectors",
-  filter: { category: "product" },
+  indexName: 'my_vectors',
+  filter: { category: 'product' },
   update: {
-    metadata: { status: "reviewed" },
+    metadata: { status: 'reviewed' },
   },
-});
+})
 ```
 
 ### deleteVector()
@@ -195,7 +195,7 @@ await vectorStore.updateVector({
 **id:** (`string`): ID of the vector to delete
 
 ```typescript
-await vectorStore.deleteVector({ indexName: "my_vectors", id: "vector123" });
+await vectorStore.deleteVector({ indexName: 'my_vectors', id: 'vector123' })
 ```
 
 ### deleteVectors()
@@ -211,15 +211,15 @@ Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` m
 ```typescript
 // Delete by IDs
 await vectorStore.deleteVectors({
-  indexName: "my_vectors",
-  ids: ["vec1", "vec2", "vec3"],
-});
+  indexName: 'my_vectors',
+  ids: ['vec1', 'vec2', 'vec3'],
+})
 
 // Delete by filter
 await vectorStore.deleteVectors({
-  indexName: "my_vectors",
-  filter: { status: "archived" },
-});
+  indexName: 'my_vectors',
+  filter: { status: 'archived' },
+})
 ```
 
 ## Response Types
@@ -228,10 +228,10 @@ Query results are returned in this format:
 
 ```typescript
 interface QueryResult {
-  id: string;
-  score: number;
-  metadata: Record<string, any>;
-  vector?: number[]; // Only included if includeVector is true
+  id: string
+  score: number
+  metadata: Record<string, any>
+  vector?: number[] // Only included if includeVector is true
 }
 ```
 
@@ -242,32 +242,29 @@ ConvexVector supports metadata filtering with various operators:
 ```typescript
 // Simple equality
 const results = await vectorStore.query({
-  indexName: "my_vectors",
+  indexName: 'my_vectors',
   queryVector: embedding,
-  filter: { category: "documents" },
-});
+  filter: { category: 'documents' },
+})
 
 // Comparison operators
 const results = await vectorStore.query({
-  indexName: "my_vectors",
+  indexName: 'my_vectors',
   queryVector: embedding,
   filter: {
     price: { $gt: 100 },
-    status: { $in: ["active", "pending"] },
+    status: { $in: ['active', 'pending'] },
   },
-});
+})
 
 // Logical operators
 const results = await vectorStore.query({
-  indexName: "my_vectors",
+  indexName: 'my_vectors',
   queryVector: embedding,
   filter: {
-    $and: [
-      { category: "electronics" },
-      { price: { $lte: 500 } },
-    ],
+    $and: [{ category: 'electronics' }, { price: { $lte: 500 } }],
   },
-});
+})
 ```
 
 ### Supported Filter Operators

package/dist/index.cjs

@@ -993,6 +993,15 @@ var ConvexVector = class extends vector.MastraVector {
     includeVector = false,
     filter
   }) {
+    if (!queryVector) {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("CONVEX", "QUERY", "MISSING_VECTOR"),
+        text: "queryVector is required for Convex queries. Metadata-only queries are not supported by this vector store.",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName }
+      });
+    }
     const vectors = await this.callStorage({
       op: "queryTable",
       tableName: this.vectorTable(indexName)