@mastra/lance 1.0.1 → 1.0.2-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @mastra/lance
 
+## 1.0.2-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.1
 
 ### Patch Changes

package/dist/docs/SKILL.md

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.1",
+  "version": "1.0.2-alpha.0",
   "package": "@mastra/lance",
   "exports": {},
   "modules": {}

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

@@ -7,22 +7,22 @@ After generating embeddings, you need to store them in a database that supports
 **MongoDB**:
 
 ```ts
-import { MongoDBVector } from "@mastra/mongodb";
+import { MongoDBVector } from '@mastra/mongodb'
 
 const store = new MongoDBVector({
   id: 'mongodb-vector',
   uri: process.env.MONGODB_URI,
   dbName: process.env.MONGODB_DATABASE,
-});
+})
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 ### Using MongoDB Atlas Vector search
@@ -32,23 +32,23 @@ For detailed setup instructions and best practices, see the [official MongoDB At
 **PgVector**:
 
 ```ts
-import { PgVector } from "@mastra/pg";
+import { PgVector } from '@mastra/pg'
 
 const store = new PgVector({
   id: 'pg-vector',
   connectionString: process.env.POSTGRES_CONNECTION_STRING,
-});
+})
 
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 ### Using PostgreSQL with pgvector
@@ -58,50 +58,50 @@ PostgreSQL with the pgvector extension is a good solution for teams already usin
 **Pinecone**:
 
 ```ts
-import { PineconeVector } from "@mastra/pinecone";
+import { PineconeVector } from '@mastra/pinecone'
 
 const store = new PineconeVector({
   id: 'pinecone-vector',
   apiKey: process.env.PINECONE_API_KEY,
-});
+})
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 **Qdrant**:
 
 ```ts
-import { QdrantVector } from "@mastra/qdrant";
+import { QdrantVector } from '@mastra/qdrant'
 
 const store = new QdrantVector({
   id: 'qdrant-vector',
   url: process.env.QDRANT_URL,
   apiKey: process.env.QDRANT_API_KEY,
-});
+})
 
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 **Chroma**:
 
 ```ts
-import { ChromaVector } from "@mastra/chroma";
+import { ChromaVector } from '@mastra/chroma'
 
 // Running Chroma locally
 // const store = new ChromaVector()
@@ -112,151 +112,151 @@ const store = new ChromaVector({
   apiKey: process.env.CHROMA_API_KEY,
   tenant: process.env.CHROMA_TENANT,
   database: process.env.CHROMA_DATABASE,
-});
+})
 
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 **Astra**:
 
 ```ts
-import { AstraVector } from "@mastra/astra";
+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,
-});
+})
 
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 **libSQL**:
 
 ```ts
-import { LibSQLVector } from "@mastra/core/vector/libsql";
+import { LibSQLVector } from '@mastra/core/vector/libsql'
 
 const store = new LibSQLVector({
   id: 'libsql-vector',
   url: process.env.DATABASE_URL,
   authToken: process.env.DATABASE_AUTH_TOKEN, // Optional: for Turso cloud databases
-});
+})
 
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 **Upstash**:
 
 ```ts
-import { UpstashVector } from "@mastra/upstash";
+import { UpstashVector } from '@mastra/upstash'
 
 // In upstash they refer to the store as an index
 const store = new UpstashVector({
   id: 'upstash-vector',
   url: process.env.UPSTASH_URL,
   token: process.env.UPSTASH_TOKEN,
-});
+})
 
 // There is no store.createIndex call here, Upstash creates indexes (known as namespaces in Upstash) automatically
 // when you upsert if that namespace does not exist yet.
 await store.upsert({
-  indexName: "myCollection", // the namespace name in Upstash
+  indexName: 'myCollection', // the namespace name in Upstash
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 **Cloudflare**:
 
 ```ts
-import { CloudflareVector } from "@mastra/vectorize";
+import { CloudflareVector } from '@mastra/vectorize'
 
 const store = new CloudflareVector({
   id: 'cloudflare-vector',
   accountId: process.env.CF_ACCOUNT_ID,
   apiToken: process.env.CF_API_TOKEN,
-});
+})
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 **OpenSearch**:
 
 ```ts
-import { OpenSearchVector } from "@mastra/opensearch";
+import { OpenSearchVector } from '@mastra/opensearch'
 
-const store = new OpenSearchVector({ id: "opensearch", node: process.env.OPENSEARCH_URL });
+const store = new OpenSearchVector({ id: 'opensearch', node: process.env.OPENSEARCH_URL })
 
 await store.createIndex({
-  indexName: "my-collection",
+  indexName: 'my-collection',
   dimension: 1536,
-});
+})
 
 await store.upsert({
-  indexName: "my-collection",
+  indexName: 'my-collection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 **ElasticSearch**:
 
 ```ts
-import { ElasticSearchVector } from "@mastra/elasticsearch";
+import { ElasticSearchVector } from '@mastra/elasticsearch'
 
 const store = new ElasticSearchVector({
   id: 'elasticsearch-vector',
   url: process.env.ELASTICSEARCH_URL,
   auth: {
-    apiKey : process.env.ELASTICSEARCH_API_KEY
-  }
-});
+    apiKey: process.env.ELASTICSEARCH_API_KEY,
+  },
+})
 
 await store.createIndex({
-  indexName: "my-collection",
+  indexName: 'my-collection',
   dimension: 1536,
-});
+})
 
 await store.upsert({
-  indexName: "my-collection",
+  indexName: 'my-collection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 ### Using Elasticsearch
@@ -266,7 +266,7 @@ For detailed setup instructions and best practices, see the [official Elasticsea
 **Couchbase**:
 
 ```ts
-import { CouchbaseVector } from "@mastra/couchbase";
+import { CouchbaseVector } from '@mastra/couchbase'
 
 const store = new CouchbaseVector({
   id: 'couchbase-vector',
@@ -276,36 +276,36 @@ const store = new CouchbaseVector({
   bucketName: process.env.COUCHBASE_BUCKET,
   scopeName: process.env.COUCHBASE_SCOPE,
   collectionName: process.env.COUCHBASE_COLLECTION,
-});
+})
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 **Lance**:
 
 ```ts
-import { LanceVectorStore } from "@mastra/lance";
+import { LanceVectorStore } from '@mastra/lance'
 
-const store = await LanceVectorStore.create("/path/to/db");
+const store = await LanceVectorStore.create('/path/to/db')
 
 await store.createIndex({
-  tableName: "myVectors",
-  indexName: "myCollection",
+  tableName: 'myVectors',
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 
 await store.upsert({
-  tableName: "myVectors",
+  tableName: 'myVectors',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 ### Using LanceDB
@@ -315,26 +315,26 @@ LanceDB is an embedded vector database built on the Lance columnar format, suita
 **S3 Vectors**:
 
 ```ts
-import { S3Vectors } from "@mastra/s3vectors";
+import { S3Vectors } from '@mastra/s3vectors'
 
 const store = new S3Vectors({
   id: 's3-vectors',
-  vectorBucketName: "my-vector-bucket",
+  vectorBucketName: 'my-vector-bucket',
   clientConfig: {
-    region: "us-east-1",
+    region: 'us-east-1',
   },
-  nonFilterableMetadataKeys: ["content"],
-});
+  nonFilterableMetadataKeys: ['content'],
+})
 
 await store.createIndex({
-  indexName: "my-index",
+  indexName: 'my-index',
   dimension: 1536,
-});
+})
 await store.upsert({
-  indexName: "my-index",
+  indexName: 'my-index',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({ text: chunk.text })),
-});
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
 ```
 
 ## Using Vector Storage
@@ -348,9 +348,9 @@ Before storing embeddings, you need to create an index with the appropriate dime
 ```ts
 // Create an index with dimension 1536 (for text-embedding-3-small)
 await store.createIndex({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   dimension: 1536,
-});
+})
 ```
 
 The dimension size must match the output dimension of your chosen embedding model. Common dimension sizes are:
@@ -527,13 +527,13 @@ After creating an index, you can store embeddings along with their basic metadat
 ```ts
 // Store embeddings with their corresponding metadata
 await store.upsert({
-  indexName: "myCollection", // index name
+  indexName: 'myCollection', // index name
   vectors: embeddings, // array of embedding vectors
-  metadata: chunks.map((chunk) => ({
+  metadata: chunks.map(chunk => ({
     text: chunk.text, // The original text content
     id: chunk.id, // Optional unique identifier
   })),
-});
+})
 ```
 
 The upsert operation:
@@ -552,9 +552,9 @@ Vector stores support rich metadata (any JSON-serializable fields) for filtering
 ```ts
 // Store embeddings with rich metadata for better organization and filtering
 await store.upsert({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   vectors: embeddings,
-  metadata: chunks.map((chunk) => ({
+  metadata: chunks.map(chunk => ({
     // Basic content
     text: chunk.text,
     id: chunk.id,
@@ -565,14 +565,14 @@ await store.upsert({
 
     // Temporal metadata
     createdAt: new Date().toISOString(),
-    version: "1.0",
+    version: '1.0',
 
     // Custom fields
     language: chunk.language,
     author: chunk.author,
     confidenceScore: chunk.score,
   })),
-});
+})
 ```
 
 Key metadata considerations:
@@ -592,9 +592,9 @@ The most common use case is deleting all vectors for a specific document when a
 ```ts
 // Delete all vectors for a specific document
 await store.deleteVectors({
-  indexName: "myCollection",
-  filter: { docId: "document-123" },
-});
+  indexName: 'myCollection',
+  filter: { docId: 'document-123' },
+})
 ```
 
 This is particularly useful when:
@@ -610,22 +610,19 @@ You can also use complex filters to delete vectors matching multiple conditions:
 ```ts
 // Delete all vectors for multiple documents
 await store.deleteVectors({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   filter: {
-    docId: { $in: ["doc-1", "doc-2", "doc-3"] },
+    docId: { $in: ['doc-1', 'doc-2', 'doc-3'] },
   },
-});
+})
 
 // Delete vectors for a specific user's documents
 await store.deleteVectors({
-  indexName: "myCollection",
+  indexName: 'myCollection',
   filter: {
-    $and: [
-      { userId: "user-123" },
-      { status: "archived" },
-    ],
+    $and: [{ userId: 'user-123' }, { status: 'archived' }],
   },
-});
+})
 ```
 
 ### Delete by Vector IDs
@@ -635,9 +632,9 @@ If you have specific vector IDs to delete, you can pass them directly:
 ```ts
 // Delete specific vectors by their IDs
 await store.deleteVectors({
-  indexName: "myCollection",
-  ids: ["vec-1", "vec-2", "vec-3"],
-});
+  indexName: 'myCollection',
+  ids: ['vec-1', 'vec-2', 'vec-3'],
+})
 ```
 
 ## Best Practices

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

@@ -35,18 +35,18 @@ bun add @mastra/lance@latest
 ### Basic Storage Usage
 
 ```typescript
-import { LanceStorage } from "@mastra/lance";
+import { LanceStorage } from '@mastra/lance'
 
 // Connect to a local database
-const storage = await LanceStorage.create("my-storage", "/path/to/db");
+const storage = await LanceStorage.create('my-storage', '/path/to/db')
 
 // Connect to a LanceDB cloud database
-const storage = await LanceStorage.create("my-storage", "db://host:port");
+const storage = await LanceStorage.create('my-storage', 'db://host:port')
 
 // Connect to a cloud database with custom options
-const storage = await LanceStorage.create("my-storage", "s3://bucket/db", {
-  storageOptions: { timeout: "60s" },
-});
+const storage = await LanceStorage.create('my-storage', 's3://bucket/db', {
+  storageOptions: { timeout: '60s' },
+})
 ```
 
 ## Parameters
@@ -76,29 +76,29 @@ The LanceStorage implementation automatically handles schema creation and update
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
 
 ```typescript
-import { Mastra } from "@mastra/core";
-import { LanceStorage } from "@mastra/lance";
+import { Mastra } from '@mastra/core'
+import { LanceStorage } from '@mastra/lance'
 
-const storage = await LanceStorage.create("my-storage", "/path/to/db");
+const storage = await LanceStorage.create('my-storage', '/path/to/db')
 
 const mastra = new Mastra({
   storage, // init() is called automatically
-});
+})
 ```
 
 If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
 
 ```typescript
-import { LanceStorage } from "@mastra/lance";
+import { LanceStorage } from '@mastra/lance'
 
-const storage = await LanceStorage.create("my-storage", "/path/to/db");
+const storage = await LanceStorage.create('my-storage', '/path/to/db')
 
 // Required when using storage directly
-await storage.init();
+await storage.init()
 
 // Access domain-specific stores via getStore()
-const memoryStore = await storage.getStore('memory');
-const thread = await memoryStore?.getThreadById({ threadId: "..." });
+const memoryStore = await storage.getStore('memory')
+const thread = await memoryStore?.getThreadById({ threadId: '...' })
 ```
 
 > **Warning:** If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.