Table API

LanBuffer 提供兼容 LanceDB 的 Table HTTP API（默认端口 :7001），支持结构化数据存储、向量搜索、全文搜索与混合搜索。

数据以 Apache Arrow IPC 格式传输。

SDK 连接

注意： 上游 LanceDB 官方 SDK 与 LanBuffer 不兼容。请使用本仓库中修改的 @lancedb/lancedb SDK，它增加了 lanbuff:// 协议支持。

cd nodejs && npm install && npm run build

import * as lancedb from "@lancedb/lancedb";

const db = await lancedb.connect("lanbuff://127.0.0.1:7001");

表命名与命名空间

表标识符通过分隔符（默认 $）编码命名空间与表名。例如 ns1$ns2$tablename 表示命名空间 ns1/ns2 下的 tablename。

大多数端点支持 ?delimiter= 查询参数来自定义分隔符。

---

API 端点

列出所有表

GET /v1/table?page_token=&limit=&delimiter=

查询参数：

参数	类型	默认值	说明
page_token	string	空	分页游标
limit	number	—	每页最大条目数
delimiter	string	$	命名空间分隔符

响应：

{
  "tables": ["ns1$table1", "table2"],
  "page_token": "last_table_name"
}

curl 示例：

curl http://127.0.0.1:7001/v1/table

列出命名空间下的表

GET /v1/namespace/{id}/table/list/?page_token=&limit=&delimiter=

创建表

POST /v1/table/{id}/create/?delimiter=&mode=

查询参数：

参数	类型	默认值	说明
mode	string	create	create（已存在则报错）、overwrite（覆盖）、exist_ok（已存在则跳过）

请求体： Arrow IPC 流（二进制）。如果批次为空，则根据 schema 创建空表。

响应： 201 Created

SDK 示例：

const tbl = await db.createTable(
  "items",
  [
    { vector: [3.1, 4.1], item: "foo", price: 10.0 },
    { vector: [5.9, 26.5], item: "bar", price: 20.0 },
  ],
  { mode: "overwrite" },
);

描述表

POST /v1/table/{id}/describe/

请求体（可选 JSON）：

{"version": null}

响应：

{
  "version": 1,
  "schema": { /* Arrow JSON schema */ },
  "location": null
}

插入数据

POST /v1/table/{id}/insert/?delimiter=&mode=

查询参数：

参数	类型	默认值	说明
mode	string	append	overwrite（覆盖已有数据）或默认追加

请求体： Arrow IPC 流（二进制）

响应：

{"version": 0}

SDK 示例：

await tbl.add([
  { vector: [1.3, 1.4], item: "fizz", price: 100.0 },
]);

查询表

POST /v1/table/{id}/query/

请求体 JSON：

{
  "vector": [0.1, 0.2, 0.3],
  "k": 10,
  "offset": 0,
  "columns": ["col1", "col2"],
  "filter": "price < 50",
  "prefilter": true,
  "distance_type": "L2",
  "nprobes": 20,
  "refine_factor": 10,
  "vector_column": "vector",
  "bypass_vector_index": false,
  "with_row_id": false,
  "version": null
}

参数说明：

参数	类型	说明
vector	float[]	查询向量。为空数组或不提供时执行普通查询
k	number	返回最近邻数量
offset	number	跳过前 N 条结果
columns	string[]	返回的列（空则返回全部）
filter	string	SQL 过滤表达式
prefilter	bool	true（默认）先过滤再搜索，false 先搜索再过滤
distance_type	string	距离度量：L2、cosine、dot、hamming
nprobes	number	IVF 索引探测分区数
refine_factor	number	精炼因子，提高召回率
vector_column	string	向量列名（默认 vector）
bypass_vector_index	bool	跳过向量索引，暴力搜索

响应： Arrow IPC File（二进制）

详细的搜索用法请参考 向量搜索、全文搜索、混合搜索。

更新数据

POST /v1/table/{id}/update/

请求体 JSON：

{
  "updates": [["column_name", "expression"], ["price", "price * 1.1"]],
  "predicate": "item = 'foo'"
}

删除数据

POST /v1/table/{id}/delete/

请求体 JSON：

{"predicate": "price > 100"}

统计行数

POST /v1/table/{id}/count_rows/

请求体 JSON：

{"predicate": "optional filter", "version": null}

响应： JSON 数字

删除表

POST /v1/table/{id}/drop/

SDK 示例：

await db.dropTable("items");

---

索引管理

创建索引

POST /v1/table/{id}/create_index/

请求体 JSON：

{
  "column": "vector",
  "name": "my_index",
  "index_type": "IVF_PQ",
  "metric_type": "L2",
  "num_partitions": 256,
  "num_sub_vectors": 16,
  "num_bits": 8
}

支持的索引类型：

索引类型	说明
IVF_FLAT	IVF 平面索引，无量化
IVF_PQ	IVF + 乘积量化（默认）
IVF_SQ	IVF + 标量量化
IVF_HNSW_SQ	IVF + HNSW + 标量量化
IVF_RQ	IVF + 残差量化
BTREE	B-tree 索引（标量列）

支持的距离度量： L2（默认）、cosine、dot、hamming

列出索引

POST /v1/table/{id}/index/list/

响应：

{
  "indexes": [{"index_name": "my_index", "columns": ["vector"]}]
}

索引统计

POST /v1/table/{id}/index/{index_name}/stats/

响应：

{
  "num_indexed_rows": 1000,
  "num_unindexed_rows": 50,
  "index_type": "IVF_PQ",
  "distance_type": "l2",
  "num_indices": 1,
  "loss": null
}

删除索引

POST /v1/table/{id}/index/{index_name}/drop/

---

HTTP 直接验证

无需 SDK，可直接通过 HTTP 验证服务状态：

# 健康检查
curl http://127.0.0.1:7001/health

# 列出所有表
curl http://127.0.0.1:7001/v1/table