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; }

两个字段都标注为可选（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>;

2. 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>。

3. 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>; }

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是字符串数组，如["parent", "child"]表示在父命名空间下创建子命名空间。对应测试见 connection.test.ts。
• exist_ok适合幂等初始化：在应用启动时确保命名空间存在，重复执行不会报错。
• properties建议回读校验：由于返回字段可选，若业务依赖属性生效，可在创建后调用describeNamespace二次确认。

错误语义与边界行为

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

关闭连接后所有命名空间操作（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 中关于数据库级命名空间的实现。

• 向量数据库
• 数据库
• 人工智能
• 后端