Lance Namespace 核心 API 解析：Lance 命名空间与表管理的统一接口

Lance Namespace 核心 API 解析Lance 命名空间与表管理的统一接口【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance命名空间Namespace是 Lance 多模态数据湖中组织与管理表的基础抽象。本文围绕rust/lance-namespacecrate 的核心 API 与 trait 设计展开结合lance-namespace-impls的后端实现、错误码体系与 Schema 转换工具说明如何通过一套统一接口在不同后端目录、REST 等上完成命名空间与表的创建、查询、版本管理与索引操作让读者能够直接编写或对接基于LanceNamespace的应用代码。一、crate 定位接口层与实现层分离Lance 仓库采用接口与实现分离的架构来构建命名空间系统。根据 rust/lance-namespace/README.mdlance-namespace这一 crate 只负责提供核心 API 与 trait 定义包括LanceNamespacetrait —— 命名空间操作的统一主接口Arrow Schema 与 JSON 之间的转换工具命名空间操作的请求/响应模型通过lance-namespace-reqwest-client复用。而真正的后端实现REST、Directory 等位于lance-namespace-implscrate见 rust/lance-namespace-impls/README.md。这一点在 README 中被明确标注理解这个分层是使用本 crate 的前提你依赖lance-namespace编写面向接口的代码通过lance-namespace-impls选择具体后端。从 rust/lance-namespace/Cargo.toml 可以看到其依赖构成async-trait异步 trait 支持、arrowSchema 类型、lance-coreError/Result基础类型、serde/serde_json序列化、snafu错误派生、bytes流式数据以及lance-namespace-reqwest-client请求/响应模型。二、LanceNamespacetrait统一操作入口trait 的定义位于 rust/lance-namespace/src/namespace.rs。它被声明为#[async_trait] pub trait LanceNamespace: Send Sync std::fmt::Debug { // 方法定义... }即所有实现必须满足Send Sync Debug约束方法均为异步。trait 内每个方法都提供了默认实现默认行为是返回Error::not_supported(...)见 rust/lance-namespace/src/namespace.rs 等处的模式。这意味着后端只需实现自己支持的操作未实现的操作会得到明确的 not implemented 错误而非编译期强制全部实现。2.1 命名空间级操作方法说明典型错误码list_namespaces列出命名空间NamespaceNotFound父命名空间不存在describe_namespace描述命名空间NamespaceNotFoundcreate_namespace创建命名空间NamespaceAlreadyExistsdrop_namespace删除命名空间NamespaceNotFound/NamespaceNotEmptynamespace_exists判断命名空间是否存在NamespaceNotFound2.2 表级操作方法说明list_tables/list_all_tables列出命名空间内/全局所有表describe_table/table_exists描述与检查表register_table/deregister_table注册与注销表不删除数据create_table/declare_table用 Arrow IPC 数据建表 / 仅声明元数据的表drop_table删除表count_table_rows统计表行数insert_into_table/merge_insert_into_table/update_table/delete_from_table数据写入与变更query_table查询表返回 Arrow IPC 字节流Bytesrename_table/restore_table重命名 / 恢复历史版本值得注意create_table、insert_into_table、merge_insert_into_table这类携带数据的操作除请求结构体外还接收一个Bytes参数Arrow IPC 流这是命名空间 API 传输表数据的统一通道。2.3 索引、版本与演进操作索引create_table_index/create_table_scalar_index/list_table_indices/describe_table_index_stats/drop_table_index版本管理list_table_versions/describe_table_version/create_table_version/batch_delete_table_versionsSchema 演进alter_table_add_columns/alter_table_alter_columns/alter_table_drop_columns/alter_table_backfill_columns/update_table_schema_metadata标签与分支list_table_tags/create_table_tag/get_table_tag_version/update_table_tag/delete_table_tag以及create_table_branch/list_table_branches/delete_table_branch物化视图与事务create_materialized_view/refresh_materialized_view、describe_transaction/alter_transaction查询计划explain_table_query_plan/analyze_table_query_plan统计get_table_stats。此外trait 定义了一个非异步方法namespace_id()见 rust/lance-namespace/src/namespace.rs返回该命名空间实例的人类可读唯一标识例如rest(endpointhttps://api.example.com)或dir(root/path/to/data)。该标识用于命名空间实例的相等性比较与哈希两个 ID 相同的实例被认为等价并共享缓存资源。三、统一错误码体系跨语言一致的数字契约命名空间系统的错误处理是文档与实现中反复强调的设计重点。在 rust/lance-namespace/src/error.rs 中定义了ErrorCode枚举#[repr(u32)]每个错误类型拥有在所有 Lance Namespace 实现Python、Java、Rust、REST中全局唯一的数字编码编码错误码含义0Unsupported后端不支持该操作1NamespaceNotFound命名空间不存在2NamespaceAlreadyExists命名空间已存在3NamespaceNotEmpty命名空间非空含表或子命名空间4TableNotFound表不存在5TableAlreadyExists表已存在6-7TableIndexNotFound/TableIndexAlreadyExists索引不存在/已存在8-9TableTagNotFound/TableTagAlreadyExists标签不存在/已存在10TransactionNotFound事务不存在11TableVersionNotFound表版本不存在12TableColumnNotFound表列不存在13InvalidInput请求参数非法14ConcurrentModification乐观并发冲突15PermissionDenied权限不足16Unauthenticated认证失败17ServiceUnavailable服务暂不可用18Internal内部错误19InvalidTableState表状态非法20TableSchemaValidationErrorSchema 校验失败21Throttling限流22-23TableBranchNotFound/TableBranchAlreadyExists分支不存在/已存在ErrorCode提供as_u32()与from_u32()双向转换NamespaceError枚举基于snafu派生则携带每条错误的人类可读消息并实现Intolance_core::Error原始错误被保留在source字段中可通过downcast_ref::NamespaceError()还原见 rust/lance-namespace/src/error.rs 与 rust/lance-namespace/src/error.rs 的示例。对于跨语言场景例如从 REST 响应重建错误NamespaceError::from_code(code, message)可以直接由数字码还原出对应变体。该模块自带测试覆盖了错误码往返、未知码映射、NamespaceError转lance_core::Error后的 downcast 验证等见 rust/lance-namespace/src/error.rs。四、Schema 转换工具Arrow 与 JSON 表示互转命名空间 API 在跨进程/跨语言传输时需要一种与语言无关的 Schema 表示。lance-namespace在 rust/lance-namespace/src/schema.rs 中提供了完整的双向转换arrow_schema_to_json(ArrowSchema) - ResultJsonArrowSchema将 Arrow Schema 序列化为JsonArrowSchema字段 可选元数据convert_json_arrow_schema(JsonArrowSchema) - ResultArrowSchema反向还原。转换覆盖了完整的 Arrow 类型体系标量类型null、bool、各类int8/16/32/64、uint*、float16/32/64、utf8、large_utf8、binary、large_binary、date32/64、timestamp、duration、interval、fixed_size_binaryDecimal 类型decimal32/64/128/256将精度与标度编码进length字段precision * 1000 scale解码时处理负标度嵌套类型list、large_list、fixed_size_list、struct、map均递归转换内部字段并保留字段级元数据特殊处理dictionary类型解包为其值类型见 rust/lance-namespace/src/schema.rskeys_sortedtrue的 Map、RunEndEncoded、ListView、Utf8View等类型当前会返回明确错误而非静默降级。Schema 与字段的元数据metadata在双向转换中都会被保留——包括 Arrow 扩展类型标记如ARROW:extension:name相关行为由 rust/lance-namespace/src/schema.rs 的test_extension_metadata_preserved_in_json_roundtrip测试验证。test_json_arrow_type_roundtrip则系统性地验证了所有支持类型的往返一致性见 rust/lance-namespace/src/schema.rs。五、模型复用与兼容性垫片5.1 请求/响应模型来自 reqwest clientlance-namespace自身不定义请求/响应数据结构而是从lance-namespace-reqwest-client批量导入见 rust/lance-namespace/src/namespace.rs 的 import 清单并在 rust/lance-namespace/src/lib.rs 中通过pub mod models、pub mod apis及pub use lance_namespace_reqwest_client as reqwest_client对外再导出。同时crate 根部重新导出了lance_core::{Error, Result}与namespace::LanceNamespace使得使用方只需use lance_namespace::LanceNamespace;即可开始编码。5.2 兼容性垫片老 SDK 与新后端的桥接rust/lance-namespace/src/compat.rs 提供了面向向后兼容的反序列化垫片。典型场景是 Java/Python SDK 的请求经过 JNI 与 PyO3 以 JSON 到达 Rust 实现时旧版本lance-namespace 0.11 及更早发送的on: id是标量字符串而当前模型要求on: [id]列表。merge_insert_request_from_json会检测到标量on字段并将其提升为单元素列表从而让旧客户端继续工作见 rust/lance-namespace/src/compat.rs。其单元测试覆盖了标量提升、列表原样保留、缺失/null 保持原状、非法类型仍被拒绝四种情形。六、后端连接lance-namespace-implsREADME 明确指出实际使用时应通过lance-namespace-impls的connect获取后端实例use lance_namespace::LanceNamespace; // use lance_namespace_impls::connect; // let namespace connect(rest, properties).await?; // let namespace connect(dir, properties).await?; async fn example(namespace: dyn LanceNamespace) { // List tables in the namespace let tables namespace.list_tables(Default::default()).await; }lance-namespace-impls提供两种后端见 rust/lance-namespace-impls/README.mdDirectory Namespace始终可用以文件系统目录结构存储表每个表即一个 Lance 数据集支持本地文件系统以及 S3dir-aws、GCSdir-gcp、Azure Blobdir-azure、阿里云 OSSdir-oss等对象存储REST Namespacerestfeature连接远程 Lance 命名空间服务器的 REST API 客户端。6.1 通过connect函数连接use lance_namespace_impls::connect; use std::collections::HashMap; #[tokio::main] async fn main() - Result(), Boxdyn std::error::Error { // 连接本地目录后端 let mut props HashMap::new(); props.insert(root.to_string(), /path/to/data.to_string()); let namespace connect(dir, props).await?; // 连接 S3 上的目录后端 let mut props HashMap::new(); props.insert(root.to_string(), s3://my-bucket/path.to_string()); props.insert(storage.region.to_string(), us-west-2.to_string()); let namespace connect(dir, props).await?; Ok(()) }Directory 后端的关键配置属性为root本地路径或云存储 URI与storage.*系列存储选项如storage.region、storage.access_key_id。6.2ConnectBuilder流式构建连接除函数式connect外lance-namespace-impls还提供ConnectBuilder见 rust/lance-namespace-impls/src/connect.rs支持链式配置use lance_namespace_impls::ConnectBuilder; // 连接目录实现并复用 Lance session 的对象存储注册表 let session Arc::new(Session::default()); let namespace ConnectBuilder::new(dir) .property(root, /path/to/data) .property(storage.region, us-west-2) .session(session) .connect() .await?;ConnectBuilder的能力包括property/properties批量注入配置、session共享 Lance 会话复用对象存储连接、context_provider注入按请求动态生成的上下文headers.前缀键会被转换为 HTTP 请求头。connect()根据impl_name分发rest需要restfeature否则返回Unsupported错误dir始终可用未知实现名会得到包含可用后端列表的错误消息。connect.rs内的测试验证了目录后端在临时目录上的建连与list_tables调用见 rust/lance-namespace-impls/src/connect.rs。七、Python 生态中的命名空间接入命名空间抽象并不局限于 Rust。在 Python 侧python/python/lance/namespace.py 通过lance_namespace包导入与 Rust 端相同的请求/响应模型并提供DirectoryNamespace、RestNamespace、RestAdapter以及DynamicContextProvider抽象基类。DynamicContextProvider支持通过dynamic_context_provider.*属性动态加载自定义提供类实现每次操作前的上下文注入见 python/python/lance/namespace.py。同时lance.dataset等入口支持传入namespace_client参数通过lance.namespace.connect()创建的命名空间实例可以经由describe_table()解析表的位置与存储选项从而让数据集操作与远程/目录命名空间无缝衔接见 python/python/lance/init.py 的文档说明。八、使用建议与总结面向接口编程业务代码应只依赖lance-namespace的LanceNamespacetrait通过connect/ConnectBuilder在运行时选择后端便于在本地目录、对象存储与远程 REST 服务之间切换。用错误码做跨语言处理优先匹配ErrorCode的数字编码而非解析消息文本NamespaceError::from_code可在 REST 等边界处无损重建错误类型。注意兼容垫片若你维护基于旧版本on字段的 Java/Python SDKmerge_insert_request_from_json已保证向后兼容但反向Rust 调用 Java 实现仍要求 jar 与当前模型匹配。Schema 传输命名空间 API 用JsonArrowSchema描述表结构自定义后端实现时必须正确调用arrow_schema_to_json/convert_json_arrow_schema并注意少数暂不支持的 Arrow 类型会返回明确错误。lance-namespace以接口 错误码契约 Schema 转换三层结构为 Lance 的命名空间系统提供了跨语言、跨后端的统一抽象是构建多租户表管理、元数据服务与远程数据访问时的核心基础组件。【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考