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

# 랜스 벡터 스토어

LanceVectorStore 클래스는 다음을 사용하여 벡터 검색을 제공합니다.[LanceDB](https://lancedb.github.io/lancedb/), Lance 컬럼 형식을 기반으로 구축된 임베디드 벡터 데이터베이스입니다. 로컬 개발 및 프로덕션 배포 모두에 효율적인 스토리지와 빠른 유사성 검색을 제공합니다.

## 팩토리 메소드

LanceVectorStore는 생성을 위해 팩토리 패턴을 사용합니다. 생성자를 직접 사용하는 대신 정적 `create()` 메서드를 사용해야 합니다.

**uri** (`string`): LanceDB 데이터베이스 경로 또는 클라우드 배포용 URI

**options** (`ConnectionOptions`): LanceDB의 추가 연결 옵션

## 생성자 예

정적 create 메서드를 사용하여 `LanceVectorStore` 인스턴스를 만들 수 있습니다.

```ts
import { LanceVectorStore } from '@mastra/lance'

// Connect to a local database
const vectorStore = await LanceVectorStore.create('/path/to/db')

// Connect to a LanceDB cloud database
const cloudStore = await LanceVectorStore.create('db://host:port')

// Connect to a cloud database with options
const s3Store = await LanceVectorStore.create('s3://bucket/db', {
  storageOptions: { timeout: '60s' },
})
```

## 행동 양식

### `createIndex()`

**tableName** (`string`): 인덱스를 생성할 테이블의 이름

**indexName** (`string`): 생성할 인덱스(열)의 이름

**dimension** (`number`): 벡터 차원(임베딩 Model과 일치해야 함)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 유사도 검색에 사용할 거리 측정 방식 (Default: `cosine`)

**indexConfig** (`LanceIndexConfig`): 인덱스 구성 (Default: `{ type: 'hnsw' }`)

#### `LanceIndexConfig`

**type** (`'ivfflat' | 'hnsw'`): 인덱스 유형 (Default: `hnsw`)

**type.ivfflat** (`ivfflat`): 근사 검색을 위해 벡터를 목록으로 클러스터링합니다.

**type.hnsw** (`hnsw`): 빠른 검색 속도와 높은 재현율을 제공하는 그래프 기반 인덱스입니다.

**numPartitions** (`number`): IVF 인덱스의 파티션 수 (Default: `128`)

**numSubVectors** (`number`): 곱 양자화를 위한 하위 벡터 수 (Default: `16`)

**hnsw** (`HNSWConfig`): HNSW 구성

**hnsw\.m** (`number`): 노드당 최대 연결 수(기본값: 16)

**hnsw\.efConstruction** (`number`): 빌드 시간 복잡도(기본값: 100)

### `createTable()`

**tableName** (`string`): 생성할 테이블의 이름

**data** (`Record<string, unknown>[] | TableLike`): 테이블의 초기 데이터

**options** (`Partial<CreateTableOptions>`): 추가 테이블 생성 옵션

### `upsert()`

**tableName** (`string`): 벡터를 업서트할 테이블의 이름

**vectors** (`number[][]`): 임베딩 벡터 배열

**metadata** (`Record<string, any>[]`): 각 벡터의 메타데이터

**ids** (`string[]`): 선택적 벡터 ID(제공하지 않으면 자동 생성)

### `query()`

**tableName** (`string`): 쿼리할 테이블의 이름

**queryVector** (`number[]`): 쿼리 벡터

**topK** (`number`): 반환할 결과 수 (Default: `10`)

**filter** (`Record<string, any>`): 메타데이터 필터

**includeVector** (`boolean`): 결과에 벡터를 포함할지 여부 (Default: `false`)

**columns** (`string[]`): 결과에 포함할 특정 열 (Default: `[]`)

**includeAllColumns** (`boolean`): 결과에 모든 열을 포함할지 여부 (Default: `false`)

### `listTables()`

테이블 이름 배열을 문자열로 반환합니다.

```typescript
const tables = await vectorStore.listTables()
// ['my_vectors', 'embeddings', 'documents']
```

### `getTableSchema()`

**tableName** (`string`): 설명할 테이블의 이름

지정된 테이블의 스키마를 반환합니다.

### `deleteTable()`

**tableName** (`string`): 삭제할 테이블의 이름

### `deleteAllTables()`

데이터베이스의 모든 테이블을 삭제합니다.

### `listIndexes()`

인덱스 이름의 배열을 문자열로 반환합니다.

### `describeIndex()`

**indexName** (`string`): 설명할 인덱스의 이름

인덱스에 대한 정보를 반환합니다.

```typescript
interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
  type: 'ivfflat' | 'hnsw'
  config: {
    m?: number
    efConstruction?: number
    numPartitions?: number
    numSubVectors?: number
  }
}
```

### `deleteIndex()`

**indexName** (`string`): 삭제할 인덱스의 이름

### `updateVector()`

ID 또는 메타데이터 필터를 기준으로 단일 벡터를 업데이트합니다. `id` 또는 `filter` 중 하나만 제공해야 하며, 둘 다 제공해서는 안 됩니다.

**indexName** (`string`): 벡터가 포함된 인덱스의 이름

**id** (`string`): 업데이트할 벡터의 ID(filter와 함께 사용할 수 없음)

**filter** (`Record<string, any>`): 업데이트할 벡터를 식별하는 메타데이터 필터(id와 함께 사용할 수 없음)

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): 업데이트할 벡터 및/또는 메타데이터가 포함된 객체

### `deleteVector()`

**indexName** (`string`): 벡터가 포함된 인덱스의 이름

**id** (`string`): 삭제할 벡터의 ID

### `deleteVectors()`

ID 또는 메타데이터 필터를 기준으로 여러 벡터를 삭제합니다. `ids` 또는 `filter` 중 하나만 제공해야 하며, 둘 다 제공해서는 안 됩니다.

**indexName** (`string`): 삭제할 벡터가 포함된 인덱스의 이름

**ids** (`string[]`): 삭제할 벡터 ID 배열(filter와 함께 사용할 수 없음)

**filter** (`Record<string, any>`): 삭제할 벡터를 식별하는 메타데이터 필터(ids와 함께 사용할 수 없음)

### `close()`

데이터베이스 연결을 닫습니다.

## 응답 유형

쿼리 결과는 다음 형식으로 반환됩니다.

```typescript
interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
  document?: string // Document text if available
}
```

## 오류 처리

상점에서는 포착할 수 있는 입력된 오류를 발생시킵니다.

```typescript
try {
  await store.query({
    tableName: 'my_vectors',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof Error) {
    console.log(error.message)
  }
}
```

## 모범 사례

- 사용 사례에 적합한 인덱스 유형을 사용하세요.

  - Memory 제약이 없을 때 더 높은 재현율과 성능을 제공하는 HNSW
  - 대규모 데이터 세트에서 Memory 효율성을 높이는 IVF

- 대규모 데이터 세트에서 최적의 성능을 얻으려면 `numPartitions` 및 `numSubVectors` 값을 조정하는 것을 고려하세요.

- 데이터베이스 사용을 마친 후 연결을 올바르게 종료하려면 `close()` 메서드를 사용하세요.

- 필터링 작업을 단순화하려면 일관된 스키마로 메타데이터를 저장하세요.

## 관련된

- [메타데이터 필터](https://mastra.zisheng.pro/ko/reference/rag/metadata-filters)