跳至主要內容

LanceDB 儲存空間

LanceDB 儲存空間實作採用 LanceDB 資料庫系統，提供高效能的儲存解決方案，擅長同時處理傳統資料儲存與向量操作。

不支援可觀測性

LanceDB 儲存空間不支援 observability domain。MastraStorageExporter 的 Trace 無法持久化至 LanceDB；若 LanceDB 是唯一的儲存 Provider，Studio 的可觀測性功能也無法運作。若要啟用可觀測性，請使用複合儲存空間，將可觀測性資料路由至 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 bucket 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 類別時，系統會在進行任何儲存操作前自動呼叫 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 建立資料表
  • 刪除資料表
  • 清除資料表（刪除所有記錄）
  • 依 key 載入記錄
  • 插入單筆與批次記錄
On this page