LanceDB Node.js SDK 的 CreateNamespaceResponse 接口:深入理解命名空间创建返回值

原创2026-09-23 15:12:101,653 阅读
文章标签:向量数据库数据库全文检索数据湖多模态嵌入式数据库列式数据库

LanceDB Node.js SDK 的 CreateNamespaceResponse 接口:深入理解命名空间创建返回值

导读

CreateNamespaceResponse 是 LanceDB JavaScript/TypeScript SDK(@lancedb/lancedb)中 Connection.createNamespace() 方法的返回类型,用于描述"命名空间创建操作"的结果:包括服务端实际生效的命名空间属性(properties)以及可选的事务标识(transactionId)。本篇以该接口为切入点,结合 Node.js 接口定义 与 Rust NAPI 底层实现,完整讲解命名空间创建的调用链、三种创建模式(create / exist_ok / overwrite)、返回值语义、异常处理规则,并给出可运行的实战示例,帮助你准确消费创建结果、排查冲突与校验错误。

接口定义:两个可选字段

接口的完整定义见 CreateNamespaceResponse.md,它包含两个可选属性:

interface CreateNamespaceResponse {
  /** 创建成功后由服务端返回的命名空间属性(键值对) */
  optional properties?: Record<string, string>;
  /** 本次创建操作对应的事务 ID(由服务端生成) */
  optional transactionId?: string;
}
属性 类型 必填 含义
properties Record<string, string> 否 服务端确认生效的命名空间属性集合,与创建请求中传入的 properties 一一对应
transactionId string 否 服务端为本次创建操作分配的事务 ID,可用于后续追踪或审计该操作

两个字段都标注为可选(optional),原因在于:具体哪些字段会被填充,取决于连接类型与后端实现——本地嵌入式(Local/OSS)连接与 LanceDB Cloud(远程目录)连接的响应内容可能不同。因此消费返回值时应使用可选链(?.)或显式判空,而不是假定字段必然存在。

返回值的来源:从 TypeScript 到 Rust 的完整调用链

CreateNamespaceResponse 并非凭空构造的普通对象,它由底层 Rust 核心(通过 napi-rs 绑定)构造后透传给 TypeScript 层。整个调用链如下:

  1. TypeScript 层声明:connection.ts 中的抽象方法签名:
abstract createNamespace(
  namespacePath: string[],
  options?: Partial<CreateNamespaceOptions>,
): Promise<CreateNamespaceResponse>;
  1. Rust NAPI 层实现:connection.rs 中定义了与接口一一对应的原生结构体:
#[napi(object)]
pub struct CreateNamespaceResponse {
    pub properties: Option<HashMap<String, String>>,
    pub transaction_id: Option<String>,
}

可见 TypeScript 侧的 properties 对应 Rust 侧的 Option<HashMap<String, String>>,transactionId 对应 Option<String>——TS 的"可选"语义来自 Rust 的 Option,而 Record<string, string> 则映射为 HashMap<String, String>。

  1. Rust 侧构造响应:create_namespace 方法 组装请求并构造返回值:
let resp = self
    .get_inner()?
    .create_namespace(req)
    .await
    .default_error()?;
Ok(CreateNamespaceResponse {
    properties: resp.properties,
    transaction_id: resp.transaction_id,
})

从源码结构可以推断:resp.properties 与 resp.transaction_id 直接来自 LanceDB 核心库 create_namespace 调用的返回结果,Rust 层只是做了一次字段透传。也就是说,返回值的内容由底层数据库/目录服务决定——这正是两个字段均为可选的根本原因。

配套请求参数:CreateNamespaceOptions

要理解返回值,必须先理解"创建请求"能携带什么。与响应配对的请求类型是 CreateNamespaceOptions,其完整定义在 connection.ts:

export interface CreateNamespaceOptions {
  /** Creation mode. */
  mode?: "create" | "exist_ok" | "overwrite";
  /** Properties to set on the new namespace. */
  properties?: Record<string, string>;
}
参数 类型 默认行为 说明
mode "create" | "exist_ok" | "overwrite" 未传时由后端决定 create:目标已存在则报错;exist_ok:已存在则静默跳过;overwrite:已存在则覆盖重建
properties Record<string, string> 空 创建时写入命名空间的键值属性,例如 { "team": "analytics", "env": "prod" }

Rust 侧对 mode 做了严格的校验与规范化,见 connection.rs:入参会被转为小写并与三个合法值比对,非法值会抛出明确错误:

Invalid mode '{}': expected one of 'create', 'exist_ok', 'overwrite'

这一点有对应测试用例覆盖(connection.test.ts):当传入 mode: "frobnicate" 时,测试断言 Promise 以 Invalid mode 'frobnicate' 错误被拒绝。

实战示例:创建命名空间并消费返回值

下面是一个完整的可运行示例,展示如何创建命名空间、读取返回值并验证结果:

import { connect } from "@lancedb/lancedb";

const db = await connect("./data/lancedb");

// 1. 基础创建:不指定 mode 与 properties
const resp1 = await db.createNamespace(["analytics"]);
console.log(resp1.properties);    // undefined 或 {}
console.log(resp1.transactionId); // undefined 或事务 ID

// 2. 携带属性创建,并使用 exist_ok 容忍已存在
const resp2 = await db.createNamespace(["analytics", "realtime"], {
  mode: "exist_ok",
  properties: { team: "analytics", env: "prod" },
});
console.log(resp2.properties?.team); // "analytics"(若服务端返回)

// 3. 覆盖已存在的命名空间
await db.createNamespace(["analytics", "realtime"], {
  mode: "overwrite",
  properties: { env: "staging" },
});

// 4. 安全地消费可选字段
if (resp2.transactionId) {
  console.log(`创建事务 ID:${resp2.transactionId}`);
}

几点实践建议:

  • 路径支持层级:namespacePath 是字符串数组,如 <a href="https://link.gitcode.com/i/afa10d1e9d0d382b952f312dd6cf89cb" target="_blank">"parent", "child"] 表示在父命名空间下创建子命名空间。对应测试见 [connection.test.ts。
  • exist_ok 适合幂等初始化:在应用启动时确保命名空间存在,重复执行不会报错。
  • properties 建议回读校验:由于返回字段可选,若业务依赖属性生效,可在创建后调用 describeNamespace 二次确认。

错误语义与边界行为

命名空间创建并不是"永远成功"的操作,理解以下边界行为能帮助你写出健壮的代码(均有测试佐证,见 connection.test.ts):

场景 行为
重复创建同名命名空间(默认/create 模式) Promise 被拒绝并抛出错误
传入非法 mode 抛出 Invalid mode '...' 校验错误
连接已关闭后调用 抛出 Connection is closed 错误
创建后描述该命名空间 describeNamespace 返回有效响应,验证创建成功

关闭连接后所有命名空间操作(createNamespace、dropNamespace、describeNamespace、listNamespaces)都会统一失败,这由 Rust 层 get_inner 方法 中的 Connection is closed 检查保证。

Python SDK 的对称实现

虽然本接口文档面向 JS 生态,但同一能力在 Python SDK 中保持了对等的语义,可作为交叉印证。Python 侧的同步与异步 create_namespace 都返回 CreateNamespaceResponse(包含 properties 与 transaction_id),见 db.py 与 db.py。

值得注意的是,Python 侧的 mode 校验逻辑位于独立的工具模块 namespace_utils.py:模式被统一规范为小写,合法集合为 {"create", "exist_ok", "overwrite"},非法输入抛出 ValueError。这与 Rust NAPI 层的校验策略一致,说明"三种模式 + 非法值报错"是 LanceDB 跨语言统一的设计约定。

小结

  • CreateNamespaceResponse 承载两个可选字段:properties(命名空间属性)与 transactionId(事务 ID),二者均由底层服务决定是否填充;
  • 返回值由 Rust 核心 CreateNamespaceResponse 结构体 构造,TypeScript 接口仅是 #[napi(object)] 的声明映射;
  • 配合 CreateNamespaceOptions 的三种模式(create / exist_ok / overwrite)与 properties,可以灵活实现幂等创建、覆盖重建与元数据标注;
  • 消费返回值时应容忍可选字段,并结合 describeNamespace 验证、依赖 Invalid mode 与 Connection is closed 等错误语义完成健壮的错误处理。

如需进一步了解命名空间的查询与删除,可继续阅读配套的 DescribeNamespaceResponse 与 DropNamespaceOptions 文档,以及仓库中的 catalog.ts 中关于数据库级命名空间的实现。

登录后查看全文
lancedb