vearch

Vearch TypeScript SDK，面向 Vearch 3.5.x REST API，封装了集群监控、库和表空间管理、文档写入与检索、别名、RBAC、备份恢复等能力。

特性

• 基于 axios 的轻量封装
• 支持用户名密码自动生成 Authorization
• 覆盖 Vearch 常用管理和数据操作接口
• 提供完整 TypeScript 类型定义
• 适合 Node.js 服务端直接集成

版本对应关系

| Vearch 服务端版本 | SDK 版本 | | ----------------- | -------- | | 3.5.x | 3.5.x | | 3.4.x | 3.4.x |

环境要求

• Node.js: 建议 >= 18
• TypeScript: 项目内使用 5.x

当前仓库在 Node.js v22.22.0 下验证通过。

安装

npm install vearch

如果你是在当前仓库本地开发：

npm install
npm run build

快速开始

初始化客户端

import { Vearch } from "vearch";

const client = new Vearch({
  routerUrl: "http://127.0.0.1:9001",
  username: "root",
  password: "secret",
});

也可以直接传入已经生成好的请求头：

import { Vearch } from "vearch";

const client = new Vearch({
  routerUrl: "http://127.0.0.1:9001",
  Authorization: "Basic xxxxxxxxxxxxx",
});

查看集群状态

const stats = await client.clusterStats();
const health = await client.clusterHealth();
const servers = await client.servers();

console.log(stats.data);
console.log(health.data);
console.log(servers.data);

常用操作

1. 创建数据库

await client.createDb("demo_db");

const dbInfo = await client.viewDbInfo("demo_db");
console.log(dbInfo.data);

2. 创建表空间

await client.createSpace("demo_db", {
  name: "demo_space",
  partition_num: 1,
  replica_num: 1,
  fields: [
    {
      name: "feature",
      type: "vector",
      dimension: 128,
      index: {
        name: "feature_idx",
        type: "IVFPQ",
        params: {
          metric_type: "InnerProduct",
          ncentroids: 2048,
          nsubvector: 32,
        },
      },
    },
    {
      name: "title",
      type: "string",
    },
    {
      name: "category",
      type: "string",
    },
  ],
});

const spaceInfo = await client.viewSpaceInfo("demo_db", "demo_space", true);
console.log(spaceInfo.data);

3. 写入文档

await client.upsertDocument({
  db_name: "demo_db",
  space_name: "demo_space",
  documents: [
    {
      _id: "1",
      title: "hello vearch",
      category: "guide",
      feature: Array.from({ length: 128 }, () => Math.random()),
    },
    {
      _id: "2",
      title: "vector search",
      category: "example",
      feature: Array.from({ length: 128 }, () => Math.random()),
    },
  ],
});

4. 按 ID 或过滤条件查询

const queryResult = await client.queryDocument({
  db_name: "demo_db",
  space_name: "demo_space",
  document_ids: ["1", "2"],
  fields: ["title", "category"],
  limit: 10,
});

console.log(queryResult.data?.documents);

带过滤条件的查询：

const filtered = await client.queryDocument({
  db_name: "demo_db",
  space_name: "demo_space",
  filters: {
    operator: "AND",
    conditions: [
      {
        field: "category",
        operator: "=",
        value: "guide",
      },
    ],
  },
  fields: ["title", "category"],
  limit: 10,
});

console.log(filtered.data?.documents);

5. 向量检索

const searchResult = await client.searchDocument({
  db_name: "demo_db",
  space_name: "demo_space",
  vectors: [
    {
      field: "feature",
      feature: Array.from({ length: 128 }, () => Math.random()),
      min_score: 0,
    },
  ],
  fields: ["title", "category"],
  limit: 5,
});

console.log(searchResult.data?.documents);

6. 删除文档

await client.deleteDocument({
  db_name: "demo_db",
  space_name: "demo_space",
  document_ids: ["1", "2"],
});

API 总览

集群监控

• clusterStats()
• clusterHealth(db?, space?)
• servers()
• partitions()
• cleanLock()

数据库操作

• viewDbsInfo()
• createDb(name)
• viewDbInfo(db)
• delDb(db)
• viewSpacesInfo(db)

表空间操作

• createSpace(db, spaceInfo)
• deletePartitionSpaceGroup(db, space, group)
• addPartitionGroup(db, space, group)
• deleteSpace(db, space)
• viewSpaceInfo(db, space, detail?)

文档操作

• upsertDocument(options)
• queryDocument(options)
• searchDocument(options)
• deleteDocument(options)

别名操作

• createAlias(alias, db, space)
• updateAlias(alias, db, space)
• viewAliasInfo(alias)
• deleteAlias(alias)

RBAC

• createRole(options)
• deleteRole(roleName)
• viewRoleInfo(roleName)
• updateRolePrivileges(options)
• createUser(options)
• deleteUser(userName)
• viewUserInfo(userName)
• updateUser(options)

备份与迁移

• backupOrRestoreSpace(db, space, options)
• backupSpace(db, space, options)
• restoreSpace(db, space, options)
• changePartitionMember(options)

鉴权说明

构造函数支持两种鉴权方式：

1. 直接传 Authorization
2. 传 username 和 password，SDK 内部自动生成 Basic 认证头

如果你只想拿到认证值，也可以直接调用：

const client = new Vearch({ routerUrl: "http://127.0.0.1:9001" });
const authorization = client.getAuthorization("root", "secret");
console.log(authorization);

返回值约定

所有接口都返回统一结构：

interface IReturn<T> {
  code: number;
  request_id: string;
  msg?: string;
  data?: T;
}

不同 Vearch 接口和版本对 code 的约定可能存在差异，实际接入时建议同时判断 code、msg 和 data。

类型命名规则

• IO*: 输入参数类型，O 表示 option
• IR*: 返回结果类型，R 表示 response

例如：

• IOCreateSpace: 创建表空间参数
• IRCreateSpace: 创建表空间返回结果

开发

npm install
npm run build

项目结构：

• src/index.ts: SDK 主入口
• src/http.ts: HTTP 封装与拦截器
• src/type.ts: 全量类型定义
• test/*.json: 接口返回示例

注意事项

• routerUrl 必填，库表管理和数据请求都通过 Router 节点访问
• 向量检索时，vectors 中的 feature 维度需要与表空间字段定义一致
• 过滤条件是否可用依赖字段是否建立索引
• SDK 当前依赖 Vearch 3.5.x API 语义，升级服务端版本前建议先验证接口兼容性