LanceDB storage

The LanceDB storage implementation provides a high-performance storage solution using the LanceDB database system, which excels at handling both traditional data storage and vector operations.

:::warning[Observability Not Supported] LanceDB storage doesn't support the observability domain. Traces from the DefaultExporter can't be persisted to LanceDB, and Mastra Studio's observability features won't work with LanceDB as your only storage provider. To enable observability, use composite storage to route observability data to a supported provider like ClickHouse or PostgreSQL. :::

Installation

npm install @mastra/lance@latest

Usage

Basic Storage Usage

import { LanceStorage } from '@mastra/lance'

// Connect to a local database
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')

// Connect to a cloud database with custom options
const storage = await LanceStorage.create('my-storage', 's3://bucket/db', {
  storageOptions: { timeout: '60s' },
})

Parameters

LanceStorage.create()

<PropertiesTable content={[ { name: 'name', type: 'string', description: 'Name identifier for the storage instance', isOptional: false, }, { name: 'uri', type: 'string', description: 'URI to connect to the LanceDB database. Can be a local path, cloud DB URL, or S3 bucket URL', isOptional: false, }, { name: 'options', type: 'ConnectionOptions', description: 'Connection options for LanceDB, such as timeout settings, authentication, etc.', isOptional: true, }, ]} />

Additional notes

Schema Management

The LanceStorage implementation automatically handles schema creation and updates. It maps Mastra's schema types to Apache Arrow data types, which are used by LanceDB internally:

• text, uuid → Utf8
• int, integer → Int32
• float → Float32
• jsonb, json → Utf8 (serialized)
• binary → Binary

Initialization

When you pass storage to the Mastra class, init() is called automatically before any storage operation:

import { Mastra } from '@mastra/core'
import { LanceStorage } from '@mastra/lance'

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:

import { LanceStorage } from '@mastra/lance'

const storage = await LanceStorage.create('my-storage', '/path/to/db')

// Required when using storage directly
await storage.init()

// Access domain-specific stores via getStore()
const memoryStore = await storage.getStore('memory')
const thread = await memoryStore?.getThreadById({ threadId: '...' })

:::warning If init() isn't called, tables won't be created and storage operations will fail silently or throw errors. :::

Deployment Options

LanceDB storage can be configured for different deployment scenarios:

• Local Development: Use a local file path for development and testing
  Copy

  /path/to/db
  

• Cloud Deployment: Connect to a hosted LanceDB instance
  Copy

  db://host:port
  

• S3 Storage: Use Amazon S3 for scalable cloud storage
  Copy

  s3://bucket/db
  

Table Management

LanceStorage provides methods for managing tables:

• Create tables with custom schemas
• Drop tables
• Clear tables (delete all records)
• Load records by key
• Insert single and batch records