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

# Elasticsearch Vector 存储

`ElasticSearchVector` 类使用 [Elasticsearch](https://www.elastic.co/elasticsearch/) 的 `dense_vector` 字段类型和 k-NN 搜索功能提供 Vector 搜索。 它属于 `@mastra/elasticsearch` 包。

## 安装

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## 用法

```typescript
import { ElasticSearchVector } from "@mastra/elasticsearch";

const store = new ElasticSearchVector({
  id: "elasticsearch-vector",
  url: process.env.ELASTICSEARCH_URL,
});

// Create an index
await store.createIndex({
  indexName: "my-collection",
  dimension: 1536,
});

// Add vectors with metadata
const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
const metadata = [
  { text: "first document", category: "A" },
  { text: "second document", category: "B" }
];
await store.upsert({
  indexName: "my-collection",
  vectors,
  metadata,
});

// Query similar vectors
const results = await store.query({
  indexName: "my-collection",
  queryVector: [0.1, 0.2, ...],
  topK: 10,
  filter: { category: "A" },
});
```

## 构造函数选项

**id** (`string`): 此 Vector 存储实例的唯一标识符

**url** (`string`): Elasticsearch 连接 URL（例如 'http\://localhost:9200'）

## 方法

### `createIndex()`

使用指定配置创建新索引。

**indexName** (`string`): 要创建的索引名称

**dimension** (`number`): Vector 维度（必须与嵌入模型匹配）

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 相似度搜索使用的距离度量 (Default: `cosine`)

### `upsert()`

在索引中添加或更新 Vector 及其元数据。

**indexName** (`string`): 要插入数据的索引名称

**vectors** (`number[][]`): 嵌入 Vector 数组

**metadata** (`Record<string, any>[]`): 每个 Vector 的元数据

**ids** (`string[]`): 可选的 Vector ID（未提供时自动生成）

### `query()`

搜索相似 Vector，并可选择使用元数据筛选。

**indexName** (`string`): 要搜索的索引名称

**queryVector** (`number[]`): 用于查找相似 Vector 的查询 Vector

**topK** (`number`): 要返回的结果数量 (Default: `10`)

**filter** (`Record<string, any>`): 元数据筛选条件

**includeVector** (`boolean`): 结果中是否包含 Vector 数据 (Default: `false`)

### `describeIndex()`

获取索引信息。

**indexName** (`string`): 要描述的索引名称

返回：

```typescript
interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}
```

### `deleteIndex()`

删除索引及其中的所有数据。

**indexName** (`string`): 要删除的索引名称

### `listIndexes()`

列出所有 Vector 索引。

返回：`Promise<string[]>`

### `updateVector()`

按 ID 或元数据筛选条件更新单个 Vector。必须提供 `id` 或 `filter`，但不能同时提供两者。

**indexName** (`string`): 包含该 Vector 的索引名称

**id** (`string`): 要更新的 Vector ID（与 filter 互斥）

**filter** (`Record<string, any>`): 用于识别待更新 Vector 的元数据筛选条件（与 id 互斥）

**update** (`object`): 包含 Vector 和/或元数据的更新数据

**update.vector** (`number[]`): 新的 Vector 数据

**update.metadata** (`Record<string, any>`): 新的元数据

### `deleteVector()`

按 ID 删除单个 Vector。

**indexName** (`string`): 包含该 Vector 的索引名称

**id** (`string`): 要删除的 Vector ID

### `deleteVectors()`

按 ID 或元数据筛选条件删除多个 Vector。必须提供 `ids` 或 `filter`，但不能同时提供两者。

**indexName** (`string`): 包含待删除 Vector 的索引名称

**ids** (`string[]`): 要删除的 Vector ID 数组（与 filter 互斥）

**filter** (`Record<string, any>`): 用于识别待删除 Vector 的元数据筛选条件（与 ids 互斥）

## 响应类型

查询结果以以下格式返回：

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

## 相关内容

- [元数据筛选](https://mastra.zisheng.pro/reference/rag/metadata-filters)