lancedb

构建 LanceDB 流水线

使用此技能生成可在本地表和远程表（适用于 LanceDB Enterprise/Cloud）之间移植，并符合所选 SDK 惯用写法的 LanceDB 流水线。

LanceDB 表模式

LanceDB 有两种常见的执行模式：

• 本地表：嵌入式、开源、进程内的 LanceDB。客户端从本地路径或对象存储 URI 打开数据，并在应用进程中执行查询。
• 远程表：通过 db://... URI 打开的 LanceDB Enterprise/Cloud 表。数据可能非常庞大，通常由对象存储提供支持，并通过远程服务进行查询。

不要假设远程表支持仅适用于本地表的辅助函数。如果用户询问 LanceDB Enterprise、Cloud、db://...、生产环境中的远程访问或远程表，请重点介绍远程表路径：使用 search() / query()，通过 select() 和 limit() 限制读取量，并避免使用表级的完整物化 API。

工作流

1. 确定 SDK：Python、TypeScript，或两者。
2. 确定表模式：本地／嵌入式 OSS、远程 Enterprise／Cloud，或两者通用。如果用户提到“LanceDB Enterprise”，选择远程表路径。如果任务涉及作业（列出、检查、创建或取消作业），则始终选择远程路径，并且需要连接远程服务——请先参阅下文“连接到 LanceDB 远程服务”，然后再进行其他操作。
3. 编写或修改代码前，先阅读对应语言分支的内容：
   • Python 模式：references/python/patterns.md
   • Python API 快速参考：references/python/api_reference.md
   • Python 性能指南：references/python/performance.md
   • TypeScript 模式：references/typescript/patterns.md
   • TypeScript API 快速参考：references/typescript/api_reference.md
   • TypeScript 性能指南：references/typescript/performance.md
   • 列元数据编写（两个 SDK）：references/column_metadata.md
   • 分支操作（两个 SDK）：references/branch_ops.md
   • 远程服务连接解析（作业、原始 REST）：references/remote_connect.md
   • 作业操作 REST API（list/describe/cancel/query_events）：references/remote_jobs.md
4. 从所选 SDK 的 patterns.md 开始阅读。选择方法名称或结果收集器时，阅读 api_reference.md。任务涉及数据导入、索引、筛选、查询调优、诊断或大型数据集时，阅读 performance.md。任务涉及记录、标记、分类或分组表列（字段描述、lancedb:tag:* 标签、逻辑列族）时，阅读 column_metadata.md。任务涉及分支生命周期（列出／创建／删除）、写入非 main 分支，或验证更改是否未影响 main 分支时，阅读 branch_ops.md。任务涉及作业或直接访问 Enterprise 部署的 REST API 时，阅读 remote_connect.md；作业 REST 方法本身（list、describe、cancel、query_events）则阅读 remote_jobs.md。
5. 对于 Python 模式，优先使用 Pydantic 模型，并在写入前验证记录。如果 Arrow 原生、流式或高度动态的数据更适合使用 PyArrow 模式，则使用 PyArrow 模式。
6. 读取时优先使用带有显式 select() 和 limit() 的 search() 或 query() 构建器。
7. 在远程或通用代码中，避免将整张表完全物化。这是本地与远程读取的主要陷阱。
8. 嵌入式 OSS 数据导入成功后，调用 table.optimize()。不要对 Enterprise／Cloud 调用此方法；远程维护会自动进行。
9. 对于远程 Enterprise／Cloud 写入，绝不要先删除表再复用同一表名，也不要对同一表名使用 mode="overwrite"——请参阅下文“Enterprise：绝不要先删除表再复用同一表名”。这是本地与远程写入的主要陷阱。
10. 如果要审查现有文件或仓库，请对相关路径运行 scripts/check_materialization.py，并在编辑前检查每条发现。
11. 对照源代码树核实不熟悉或非简单的 API 声明，不要依赖记忆。

核心通用性规则

不要编写假设远程表也支持本地表 API 的代码。远程表可能非常庞大，因此整表物化辅助方法会被有意设为不可用或不安全。

这并不意味着禁止转换结果。收集有界的查询／搜索结果是常见做法：

• Python：table.search(...).select([...]).limit(10).to_pandas()
• TypeScript：await table.search(...).select([...]).limit(10).toArray()

不安全的模式是整表级别或无界的收集，以及在远程代码中使用仅适用于本地的数据集访问方式：

• Python：table.to_pandas()、table.to_arrow()、table.to_polars()；table.to_lance() 是仅适用于本地／OSS 的数据集访问方式，不是物化操作
• TypeScript：await table.toArrow()、未使用 limit() 的 await table.query().toArray()

企业版：绝不删除后立即复用同一个表名

LanceDB Enterprise/Cloud 将控制平面（DDL：创建/删除/重命名）与数据平面（提供读取服务的查询节点）分开。查询节点会缓存表名对应的数据集，最长可达 table_cache_ttl——默认 300 秒（5 分钟）。删除或覆盖表后，控制平面会立即更新，但在缓存条目过期之前，数据平面仍会提供旧数据集。在此期间，两个平面的状态不一致。

这会导致以下故障：你执行 drop_table("t")，然后立即执行 create_table("t", ...)（或 create_table("t", ..., mode="overwrite")）。DDL 返回成功，但对 t 的所有查询都会返回 500 Internal Server Error（查询节点解析到的是已过期/已删除的数据集），而新执行的 describe 可能仍会显示旧架构/版本。这看起来像是写入悄无声息地失败了；实际上并没有——只是名称仍处于缓存中。

mode="overwrite" 也有同样的问题——它在底层会先删除再创建同名表。

要实现可移植的 Enterprise 数据导入，请遵循以下规则：

1. **在缓存 TTL 内，绝不复用刚刚删除/覆盖的表名。**不要使用 mode="overwrite" 原地替换现有 Enterprise 表。
2. 要加载或重新加载数据，请写入新的表名（例如 <table>_v2，或添加带运行标记的后缀）。全新名称没有数据平面缓存条目，因此可以立即写入和读取。
3. 创建表之前，调用 list_tables() 并在名称已存在时明确报错，不要覆盖——请提示使用新名称。
4. 如果要使用特定的最终名称，但该名称当前被旧表占用：删除旧表，等待 TTL 到期（约 5 分钟），然后执行 rename_table(fresh_name, final_name)。如果旧数据集仍在缓存中时重命名为该名称，也会遇到同样的竞争问题，因此必须等待。rename_table 是受支持的控制平面操作。
5. 将表名交给用户时，请告知仍需等待传播完成的步骤（通常是：“旧的 t 已删除；约 5 分钟后执行重命名”）。

此限制仅适用于 Enterprise/Cloud。Local/OSS 表没有单独的数据平面，因此在那里使用 mode="overwrite" 和立即复用同名表都没有问题。

连接到 LanceDB 远程服务

LanceDB Enterprise/Cloud 部署由实现 lance-namespace OpenAPI 规范（https://github.com/lance-format/lance-namespace/blob/main/docs/src/spec.yaml）的服务提供。每个远程（db://...）连接都会与此类服务通信，有些操作也仅在服务端提供。具体来说，所有与作业相关的操作（列出、检查、创建或取消作业）都在服务端运行——本地/OSS 没有对应功能。在执行任何作业操作，或直接调用 Enterprise 部署的 REST API 之前，请先阅读 references/remote_connect.md，解析基础 URL、凭据和数据库请求头，并验证连接。然后使用 references/remote_jobs.md 中记录的四种作业 REST 方法（list、describe、cancel、query_events）。

脚本

在审查或修改现有代码库时运行扫描器：

python skills/lancedb/scripts/check_materialization.py path/to/file_or_dir

该脚本会报告 Python 和 TypeScript 中可能存在的不安全全表物化操作。请将结果视为审查提示，而非自动认定存在缺陷的证据。