Convex向量存储

🌐 Convex Vector Store

ConvexVector 类使用 Convex 提供向量存储和相似性搜索。它将嵌入存储在 Convex 中，并执行余弦相似度搜索。

🌐 The ConvexVector class provides vector storage and similarity search using Convex. It stores embeddings inside Convex and performs cosine similarity search.

安装

🌐 Installation

npm

npm install @mastra/convex@latest

pnpm

pnpm add @mastra/convex@latest

Yarn

yarn add @mastra/convex@latest

Bun

bun add @mastra/convex@latest

Convex配置

🌐 Convex Setup

在使用 ConvexVector 之前，你需要设置 Convex 模式和存储处理器。有关设置说明，请参阅 Convex Storage Setup。

🌐 Before using ConvexVector, you need to set up the Convex schema and storage handler. See Convex Storage Setup for setup instructions.

构造函数选项

🌐 Constructor Options

deploymentUrl:

string

Convex deployment URL (e.g., https://your-project.convex.cloud)

adminAuthToken:

string

Convex admin authentication token

storageFunction?:

string

= mastra/storage:handle

Path to the storage mutation function

构造函数示例

🌐 Constructor Examples

基本配置

🌐 Basic Configuration

import { ConvexVector } from "@mastra/convex";

const vectorStore = new ConvexVector({
  id: 'convex-vectors',
  deploymentUrl: "https://your-project.convex.cloud",
  adminAuthToken: "your-admin-token",
});

自定义存储功能

🌐 Custom Storage Function

const vectorStore = new ConvexVector({
  id: 'convex-vectors',
  deploymentUrl: "https://your-project.convex.cloud",
  adminAuthToken: "your-admin-token",
  storageFunction: "custom/path:handler",
});

方法

🌐 Methods

createIndex()

indexName:

string

Name of the index to create

dimension:

number

Vector dimension (must match your embedding model)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Distance metric for similarity search (only cosine is currently supported)

await vectorStore.createIndex({
  indexName: "my_vectors",
  dimension: 1536,
});

upsert()

indexName:

string

Name of the index to upsert vectors into

vectors:

number[][]

Array of embedding vectors

metadata?:

Record<string, any>[]

Metadata for each vector

ids?:

string[]

Optional vector IDs (auto-generated if not provided)

await vectorStore.upsert({
  indexName: "my_vectors",
  vectors: [[0.1, 0.2, 0.3, ...]],
  metadata: [{ label: "example" }],
  ids: ["vec-1"],
});

query()

indexName:

string

Name of the index to query

queryVector:

number[]

Query vector

topK?:

number

= 10

Number of results to return

filter?:

Record<string, any>

Metadata filters

includeVector?:

boolean

= false

Whether to include the vector in the result

const results = await vectorStore.query({
  indexName: "my_vectors",
  queryVector: [0.1, 0.2, 0.3, ...],
  topK: 5,
  filter: { category: "documents" },
});

listIndexes()

返回一个由索引名称组成的字符串数组。

🌐 Returns an array of index names as strings.

const indexes = await vectorStore.listIndexes();
// ["my_vectors", "embeddings", ...]

describeIndex()

indexName:

string

Name of the index to describe

返回：

🌐 Returns:

interface IndexStats {
  dimension: number;
  count: number;
  metric: "cosine" | "euclidean" | "dotproduct";
}

deleteIndex()

indexName:

string

Name of the index to delete

删除索引及其所有向量。

🌐 Deletes the index and all its vectors.

await vectorStore.deleteIndex({ indexName: "my_vectors" });

updateVector()

通过 ID 或元数据过滤器更新单个向量。必须提供 id 或 filter 中的一个，但不能同时提供两者。

🌐 Update a single vector by ID or by metadata filter. Either id or filter must be provided, but not both.

indexName:

string

Name of the index containing the vector

id?:

string

ID of the vector to update (mutually exclusive with filter)

filter?:

Record<string, any>

Metadata filter to identify vector(s) to update (mutually exclusive with id)

update:

{ vector?: number[]; metadata?: Record<string, any>; }

Object containing the vector and/or metadata to update

// Update by ID
await vectorStore.updateVector({
  indexName: "my_vectors",
  id: "vector123",
  update: {
    vector: [0.1, 0.2, 0.3],
    metadata: { label: "updated" },
  },
});

// Update by filter
await vectorStore.updateVector({
  indexName: "my_vectors",
  filter: { category: "product" },
  update: {
    metadata: { status: "reviewed" },
  },
});

deleteVector()

indexName:

string

Name of the index containing the vector

id:

string

ID of the vector to delete

await vectorStore.deleteVector({ indexName: "my_vectors", id: "vector123" });

deleteVectors()

通过 ID 或元数据过滤器删除多个向量。必须提供 ids 或 filter 中的一个，但不能同时提供两者。

🌐 Delete multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.

indexName:

string

Name of the index containing the vectors to delete

ids?:

string[]

Array of vector IDs to delete (mutually exclusive with filter)

filter?:

Record<string, any>

Metadata filter to identify vectors to delete (mutually exclusive with ids)

// Delete by IDs
await vectorStore.deleteVectors({
  indexName: "my_vectors",
  ids: ["vec1", "vec2", "vec3"],
});

// Delete by filter
await vectorStore.deleteVectors({
  indexName: "my_vectors",
  filter: { status: "archived" },
});

响应类型

🌐 Response Types

查询结果以此格式返回：

🌐 Query results are returned in this format:

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

元数据过滤

🌐 Metadata Filtering

ConvexVector 支持使用各种运算符进行元数据过滤：

🌐 ConvexVector supports metadata filtering with various operators:

// Simple equality
const results = await vectorStore.query({
  indexName: "my_vectors",
  queryVector: embedding,
  filter: { category: "documents" },
});

// Comparison operators
const results = await vectorStore.query({
  indexName: "my_vectors",
  queryVector: embedding,
  filter: {
    price: { $gt: 100 },
    status: { $in: ["active", "pending"] },
  },
});

// Logical operators
const results = await vectorStore.query({
  indexName: "my_vectors",
  queryVector: embedding,
  filter: {
    $and: [
      { category: "electronics" },
      { price: { $lte: 500 } },
    ],
  },
});

支持的过滤器操作符

🌐 Supported Filter Operators

运算符	描述
$eq	等于
$ne	不等于
$gt	大于
$gte	大于或等于
$lt	小于
$lte	小于或等于
$in	在数组中
$nin	不在数组中
$and	逻辑与
$or	逻辑或

架构

🌐 Architecture

ConvexVector 在 mastra_vectors 表中存储向量，结构如下：

🌐 ConvexVector stores vectors in the mastra_vectors table with the following structure:

• id：唯一向量标识符
• indexName：索引名称
• embedding：向量数据（浮点数组）
• metadata：可选的 JSON 元数据

向量相似性搜索使用余弦相似度进行，该相似度在 Convex 函数中计算。

🌐 Vector similarity search is performed using cosine similarity, computed in the Convex function.

相关

🌐 Related

• Convex存储
• 元数据过滤器
• Convex 文档