> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# LanceDB 스토리지

LanceDB 스토리지 구현은 LanceDB 데이터베이스 시스템을 사용하여 기존 데이터 스토리지와 벡터 작업을 모두 처리하는 데 탁월한 고성능 스토리지 솔루션을 제공합니다.

:::warning\[관측성이 지원되지 않음]

LanceDB 스토리지는 **Observability 도메인을 지원하지 않습니다**. `MastraStorageExporter`의 Trace를 LanceDB에 유지할 수 없으며, LanceDB를 유일한 스토리지 Provider로 사용하는 경우 [Studio의](https://mastra.zisheng.pro/ko/docs/studio/overview) Observability 기능이 작동하지 않습니다. Observability을 활성화하려면 [복합 스토리지](https://mastra.zisheng.pro/ko/reference/storage/composite)를 사용하여 Observability 데이터를 ClickHouse와 같이 지원되는 Provider로 라우팅하세요. :::

## 설치

**npm**:

```bash
npm install @mastra/lance@latest
```

**pnpm**:

```bash
pnpm add @mastra/lance@latest
```

**Yarn**:

```bash
yarn add @mastra/lance@latest
```

**Bun**:

```bash
bun add @mastra/lance@latest
```

## 용법

### 기본 저장소 사용량

```typescript
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()`

**name** (`string`): 스토리지 인스턴스의 이름 식별자

**uri** (`string`): LanceDB 데이터베이스에 연결할 URI입니다. 로컬 경로, 클라우드 DB URL 또는 S3 버킷 URL을 사용할 수 있습니다.

**options** (`ConnectionOptions`): 제한 시간 설정, 인증 등의 LanceDB 연결 옵션입니다.

## 추가 참고사항

### 스키마 관리

LanceStorage 구현은 스키마 생성 및 업데이트를 자동으로 처리합니다. 이는 Mastra의 스키마 유형을 LanceDB에서 내부적으로 사용되는 Apache Arrow 데이터 유형에 매핑합니다.

- `text`, `uuid` → Utf8
- `int`, `integer` → Int32
- `float`→ 플로트32
- `jsonb`, `json` → Utf8 (serialized)
- `binary`→ 바이너리

### 초기화

스토리지를 Mastra 클래스에 전달하면 스토리지 작업 전에 `init()`이 자동으로 호출됩니다.

```typescript
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 없이 스토어를 직접 사용하는 경우 테이블을 생성하려면 `init()`을 명시적으로 호출해야 합니다.

```typescript
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 스토리지는 다양한 배포 시나리오에 맞게 구성될 수 있습니다.

- **지역 개발**: 개발 및 테스트를 위해 로컬 파일 경로를 사용합니다.
  ```text
  /path/to/db
  ```
- **클라우드 배포**: 호스팅된 LanceDB 인스턴스에 연결
  ```text
  db://host:port
  ```
- **S3 스토리지**: 대용량 클라우드 스토리지를 위해 Amazon S3를 사용하세요.
  ```text
  s3://bucket/db
  ```

### 테이블 관리

LanceStorage는 테이블 관리 방법을 제공합니다.

- 커스텀 스키마로 테이블 생성
- 테이블 삭제
- 테이블 지우기(모든 레코드 삭제)
- 키별로 레코드 로드
- 단일 및 일괄 레코드 삽입