跳到主要内容

LanceDB 存储

LanceDB 存储实现使用 LanceDB 数据库系统提供高性能存储方案，擅长处理传统数据存储和向量操作。

不支持 Observability

LanceDB 存储不支持 observability 域。来自 MastraStorageExporter 的 Trace 无法持久化到 LanceDB，并且仅将 LanceDB 作为存储 Provider 时，Studio 的 observability 功能无法使用。若要启用 observability，请使用组合存储将 observability 数据路由到 ClickHouse 等受支持的 Provider。

安装
安装的直接链接

npm install @mastra/lance@latest

使用方法
使用方法的直接链接

基本存储用法
基本存储用法的直接链接

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' },
})

参数
参数的直接链接

LanceStorage.create()
lancestoragecreate的直接链接

name:

string
存储实例的名称标识符

uri:

string
用于连接 LanceDB 数据库的 URI。可以是本地路径、云数据库 URL 或 S3 存储桶 URL

options?:

ConnectionOptions
LanceDB 的连接选项，例如超时设置、身份验证等。

补充说明
补充说明的直接链接

Schema 管理
Schema 管理的直接链接

LanceStorage 实现会自动处理 schema 创建和更新。它将 Mastra 的 schema 类型映射为 LanceDB 内部使用的 Apache Arrow 数据类型：

  • text, uuid → Utf8
  • int, integer → Int32
  • float → Float32
  • jsonb, json → Utf8（序列化）
  • binary → Binary

初始化
初始化的直接链接

将 storage 传递给 Mastra class 时，会在任何存储操作之前自动调用 init()：

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
})

如果不通过 Mastra 而直接使用 storage，必须显式调用 init() 来创建表：

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: '...' })
注意

如果未调用 init()，不会创建表，存储操作将静默失败或抛出错误。

部署选项
部署选项的直接链接

LanceDB 存储可针对不同部署场景进行配置：

  • 本地开发：使用本地文件路径进行开发和测试 
    /path/to/db
  • 云端部署：连接到托管的 LanceDB 实例 
    db://host:port
  • S3 存储：使用 Amazon S3 进行大容量云存储 
    s3://bucket/db

表管理
表管理的直接链接

LanceStorage 提供用于管理表的方法：

  • 使用自定义 schema 创建表
  • 删除表
  • 清空表（删除所有记录）
  • 按键加载记录
  • 插入单条和批量记录
On this page