# https://github.com/cozodb/cozo 项目说明书

生成时间：2026-06-24 00:48:36 UTC

## 目录

- [项目概览与系统架构](#page-1)
- [核心功能、查询引擎与图算法](#page-2)
- [语言绑定、存储后端与部署](#page-3)
- [生态集成、可扩展性与社区议题](#page-4)

<a id='page-1'></a>

## 项目概览与系统架构

### 相关页面

相关主题：[核心功能、查询引擎与图算法](#page-2), [语言绑定、存储后端与部署](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/cozodb/cozo/blob/main/README.md)
- [cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md)
- [cozo-bin/src/repl.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/repl.rs)
- [cozo-bin/src/server.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/server.rs)
- [cozo-lib-c/README.md](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/README.md)
- [cozo-lib-c/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/src/lib.rs)
- [cozo-lib-java/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-java/src/lib.rs)
- [cozo-lib-nodejs/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/src/lib.rs)
- [cozo-lib-nodejs/package.json](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/package.json)
- [cozo-lib-wasm/README.md](https://github.com/cozodb/cozo/blob/main/cozo-lib-wasm/README.md)
- [cozo-lib-wasm/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-wasm/src/lib.rs)
- [cozorocks/README.md](https://github.com/cozodb/cozo/blob/main/cozorocks/README.md)
- [cozorocks/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/lib.rs)
- [cozorocks/src/bridge/mod.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/mod.rs)
- [cozorocks/src/bridge/tx.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/tx.rs)
</details>

# 项目概览与系统架构

## 项目简介与定位

CozoDB 是一个用 Rust 编写、围绕 Datalog 查询语言构建的嵌入式关系型/图数据库。从主仓库的 `README.md` 可以看到，项目强调将传统关系查询、图遍历与现代向量检索（HNSW 索引）融合于同一种声明式语言之中。0.7 系列版本在此基础上又引入了 MinHash-LSH 近重复检测、全文检索和 JSON 值支持。仓库采用多 crate 工作区布局：以核心库 `cozo-core` 为中心，向外辐射出多个语言绑定与一个独立的二进制发行包 `cozo-bin`（含 REPL 与 HTTP 服务端）。

资料来源：[README.md:1-40]()

## 整体系统架构

下图展示了仓库顶层模块的依赖关系与运行时分层。核心引擎 `cozo-core` 暴露 `DbInstance` 抽象，对上层语言绑定隐藏存储细节；存储后端通过 trait 抽象在 `cozo-core` 内部实现，RocksDB 引擎则由独立的 `cozorocks` crate 通过 CXX 桥接 C++ API 提供。

```mermaid
graph TD
    A[cozo-bin CLI/REPL/Server] --> B[cozo-core DbInstance]
    C[cozo-lib-c FFI] --> B
    D[cozo-lib-java JNI] --> B
    E[cozo-lib-nodejs Neon] --> B
    F[cozo-lib-wasm wasm-bindgen] --> B
    G[cozo-lib-swift] --> B
    B --> H[Storage: mem / sqlite]
    B --> I[cozorocks CXX Bridge]
    I --> J[RocksDB C++]
    A --> K[axum HTTP Server]
    A --> L[rustyline REPL]
```

`DbInstance` 是所有绑定的统一入口：FFI 层使用 `BTreeMap<i32, DbInstance>` 通过 `AtomicI32` 自增 ID 来管理多个数据库句柄，调用方拿到的是可跨线程 `clone` 的句柄引用。资料来源：[cozo-lib-c/src/lib.rs:23-40]() 与 [cozo-lib-java/src/lib.rs:15-30]() 展示了同一种句柄管理模式在 C 和 Java 绑定中的实现。

## 存储引擎抽象

`cozo-bin` 的 `repl.rs` 明确说明，REPL 接受 `--engine` 参数，可选值包括 `mem`、`sqlite`、`rocksdb` 等。资料来源：[cozo-bin/src/repl.rs:69-78]()。`DbInstance::new(&engine, path, config)` 的调用形式表明存储路径与配置以 JSON 字符串注入，由核心层根据 engine 名选择实现。

对于 RocksDB 后端，`cozorocks` 内部通过 CXX 暴露 `DbBuilder`/`Tx`/`DbIter` 等高层包装。`bridge/mod.rs` 将 C++ 端 `StatusCode`/`StatusSeverity`/`StatusSubCode` 映射为 Rust `miette` 错误，提供 `is_ok`、`is_not_found` 等便捷方法，使上层能够以统一方式处理底层 I/O 失败。资料来源：[cozorocks/src/bridge/mod.rs:24-58]()。事务对象 `Tx` 在 `bridge/tx.rs` 中通过 `set_snapshot`/`fill_cache` 等链式方法配置，并最终 `start()` 进入就绪态。资料来源：[cozorocks/src/bridge/tx.rs:30-50]()。

## 多语言绑定与运行时分发

| 绑定 | 技术 | 关键暴露面 | 资料来源 |
| --- | --- | --- | --- |
| C | `extern "C"` FFI，句柄表 + `AtomicI32` | `cozo_open` / `cozo_run_query` | [cozo-lib-c/src/lib.rs:30-55]() |
| Java | JNI，`BTreeMap<i32, DbInstance>` | `Java_org_cozodb_CozoJavaBridge_openDb` | [cozo-lib-java/src/lib.rs:36-60]() |
| Node.js | Neon，`crossbeam::channel` 异步派发 | `index.d.ts` 类型定义 | [cozo-lib-nodejs/src/lib.rs:1-40]() |
| WASM | `wasm-bindgen`，`wee_alloc` 可选 | `CozoDb::new` 默认 `mem` 引擎 | [cozo-lib-wasm/src/lib.rs:21-48]() |
| Swift | CocoaPods `CozoSwiftBridge` | 通过独立子仓库分发 | [README.md:18-22]() |
| CLI/REPL/Server | `rustyline` + `axum` | REPL 元命令与 `text-query` HTTP 端点 | [cozo-bin/src/repl.rs:69-78](), [cozo-bin/README.md:50-65]() |

`cozo-bin` 内的 HTTP 服务由 `axum` 框架构建，使用 `tower_http` 注入 CORS、压缩与可选的鉴权层；`/text-query` 是默认查询端点，JSON 体内携带 `script` 与 `params` 字段。资料来源：[cozo-bin/src/server.rs:1-30]() 与 [cozo-bin/README.md:50-70]()。WASM 端默认以 `mem` 引擎初始化以保证浏览器内可用，资料来源：[cozo-lib-wasm/src/lib.rs:30-38]()。

## 社区关注点与维护状态

根据社区讨论，v0.7.6 是最新发布版本，变更记录显示主要为文档注释更新。社区对维护节奏有疑问（issue #301），并集中关注三个方向：

1. **跨设备同步**：issue #240 与 #252 探讨基于 CRDT 的多端同步方案，参考项目如 `vlcn-io/cr-sqlite` 与 `madgen/datalog-crdt`；目前核心层尚未提供内置 CRDT 支持。
2. **向量生态集成**：issue #238 希望将 CozoDB 作为 LangChain/LlamaIndex 的向量+图存储后端；HNSW 索引已落地（v0.6），但量化嵌入（如二值向量，issue #256）尚未原生支持。
3. **构建可移植性**：通过 `wasm-pack --target web` 配合 `CARGO_PROFILE_RELEASE_LTO=fat` 发布体积可控的 WASM 产物。资料来源：[cozo-lib-wasm/README.md:1-18]()。

## See Also

- `cozo-lib-c/README.md`：C 绑定构建与 `libcozo_c` 预编译产物说明
- `cozo-bin/README.md`：REPL 元命令与 HTTP 查询 API
- `cozorocks/README.md`：RocksDB C++ 绑定层
- `cozo-lib-wasm/README.md`：浏览器端打包与 web worker 部署建议

---

<a id='page-2'></a>

## 核心功能、查询引擎与图算法

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [生态集成、可扩展性与社区议题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/cozodb/cozo/blob/main/README.md)
- [cozo-bin/src/repl.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/repl.rs)
- [cozo-bin/src/server.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/server.rs)
- [cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md)
- [cozorocks/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/lib.rs)
- [cozorocks/src/bridge/db.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/db.rs)
- [cozorocks/src/bridge/tx.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/tx.rs)
- [cozo-lib-c/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/src/lib.rs)
- [cozo-lib-java/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-java/src/lib.rs)
- [cozo-lib-nodejs/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/src/lib.rs)
- [cozo-lib-wasm/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-wasm/src/lib.rs)
- [cozo-core/src/fts/README.md](https://github.com/cozodb/cozo/blob/main/cozo-core/src/fts/README.md)
</details>

# 核心功能、查询引擎与图算法

## 1. 概述与定位

CozoDB 是一款以 Datalog 为查询语言的关系型/图混合数据库，核心设计目标是"在单个引擎中同时支持事务性关系存储、可表达递归的图遍历、向量近邻搜索与全文本检索"。根据 [README.md](https://github.com/cozodb/cozo/blob/main/README.md) 的描述，0.6 版本引入了基于 HNSW 索引的向量搜索，0.7 版本进一步加入了 MinHash-LSH 近重复检索、全文搜索以及 JSON 值支持，使 Datalog 子句可以直接参与相似度匹配，而不再需要将检索任务外置到专用向量库中。

社区对此方向有强烈兴趣：Issue #238 询问 CozoDB 能否作为 LlamaIndex/LangChain 的向量与图存储后端 [Issue #238](https://github.com/cozodb/cozo/issues/238)；Issue #256 建议引入二值/低精度嵌入以提升吞吐量 [Issue #256](https://github.com/cozodb/cozo/issues/256)。这些诉求的共同前提是——查询引擎必须把向量、全文、图遍历统一到一种声明式语言中。

## 2. 架构总览

整个项目以 Rust 编写的 `cozo` 核心库为基准，通过多语言绑定暴露 API，并通过可执行程序 `cozo-bin` 提供 REPL 与 HTTP 服务。下图展示了主要组件的层次关系：

```mermaid
graph TD
  A[客户端：C / Java / Node.js / WASM / HTTP] --> B[cozo 核心库]
  C[cozo-bin 可执行程序] --> B
  B --> D{存储引擎}
  D --> E[mem: 内存]
  D --> F[sqlite: 嵌入式]
  D --> G[rocksdb: 持久化 LSM]
  B --> H[查询能力层]
  H --> H1[递归 Datalog]
  H --> H2[HNSW 向量搜索]
  H --> H3[MinHash-LSH]
  H --> H4[全文搜索 FTS]
  H --> H5[图算法]
  G --> I[cozorocks C++ 桥接]
```

如 [cozorocks/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/lib.rs) 所示，RocksDB 后端通过 `cxx` 桥接暴露 `DbBuilder`、`Tx`、`TxBuilder`、`DbIter` 等结构体，将 C++ 端事务、迭代器、状态码原语对应到 Rust 侧。`RocksDbStatus` 进一步把 RocksDB 的 `StatusCode` / `StatusSubCode` / `StatusSeverity` 转换为统一的错误模型 [cozorocks/src/bridge/mod.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/mod.rs)。

## 3. 查询引擎与执行入口

### 3.1 核心 API

所有语言绑定最终都调用 `DbInstance` 上的同一组方法，签名差异仅在参数编码上：

| 绑定 | 入口文件 | 关键导出 |
| --- | --- | --- |
| C ABI | [cozo-lib-c/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/src/lib.rs) | `cozo_open`、`cozo_run_query`（基于 `BTreeMap<i32, DbInstance>` 的句柄表） |
| JNI | [cozo-lib-java/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-java/src/lib.rs) | `Java_org_cozodb_CozoJavaBridge_openDb` 等 |
| Node.js (N-API) | [cozo-lib-nodejs/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/src/lib.rs) | `rows2js` / `named_rows2js` 把 `DataValue` 转 JS 数组 |
| WASM | [cozo-lib-wasm/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-wasm/src/lib.rs) | `CozoDb::new` 默认走 `mem` 引擎；`run` / `import_relations` / `export_relations` |

以 C 绑定为例，`cozo_open` 接受引擎名 `"mem"`/`"sqlite"`/`"rocksdb"`、UTF-8 路径与 JSON 选项字符串，成功时回填 `db_id`，失败时返回必须用 `cozo_free_str` 释放的 C 字符串 [cozo-lib-c/src/lib.rs:31-49](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/src/lib.rs)。

### 3.2 REPL 与 HTTP 服务

[cozo-bin/src/repl.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/repl.rs) 中 `ReplArgs` 用 clap 解析 `--engine`（默认 `mem`）、`--path`（默认 `cozo.db`）、`--config`（默认 `{}`）三个参数；输入行若以空格开头则视为续行，必须以换行结束才算完整 [cozo-bin/src/repl.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/repl.rs)。REPL 中可用的元命令包括 `%set`/`%unset`/`%params`/`%run`/`%import`/`%save`/`%backup`/`%restore` 等，详见 [cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md)。

HTTP 服务由 [cozo-bin/src/server.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/server.rs) 基于 axum 实现，默认监听 `127.0.0.1:9070`，POST `/text-query` 接受形如 `{"script": "...", "params": {}}` 的 JSON，参数通过 `$name` 在脚本内插值——这一点对避免脚本注入非常关键 [cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md)。

### 3.3 事务与存储选项

RocksDB 后端通过 `DbOpts` 暴露细粒度调参，包括 `create_if_missing`、`paranoid_checks`、`enable_blob_files`、`use_bloom_filter`、`block_cache_size` 等 [cozorocks/src/bridge/db.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/db.rs)。事务对象 `Tx` 支持 `verify_checksums`、`fill_cache`、`set_snapshot`、`start`、`put`、`get` 等操作，允许构建者按需控制一致性快照与缓存行为 [cozorocks/src/bridge/tx.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/tx.rs)。这意味着上层查询既能使用默认的轻量事务，也能在需要时下沉到 LSM 层做可控的写入路径。

## 4. 扩展能力与社区关注点

### 4.1 向量、文本与图

- **HNSW 向量索引**：可在关系上声明，对每行可索引多个向量列并配合过滤器，满足"多模态+可过滤"的近邻检索 [README.md](https://github.com/cozodb/cozo/blob/main/README.md)。
- **MinHash-LSH**：用于近重复文档/集合检测，与图遍历在同一查询中组合 [README.md](https://github.com/cozodb/cozo/blob/main/README.md)。
- **全文搜索 (FTS)**：[cozo-core/src/fts/README.md](https://github.com/cozodb/cozo/blob/main/cozo-core/src/fts/README.md) 指明停用词表来源是 [stopwords-iso](https://raw.githubusercontent.com/stopwords-iso/stopwords-iso/master/python/stopwordsiso/stopwords-iso.json)，表明内置 FTS 复用了通用多语言资源。
- **递归 Datalog 与图算法**：由于 Datalog 天然支持递归闭包，CozoDB 可直接表达最短路径、连通分量、传递闭包等经典图算法。

### 4.2 已知限制与社区诉求

- **CRDT / 跨设备同步**：Issue #240 与 #252 都希望把 `cr-sqlite` 风格的 CRDT 引入 CozoDB，实现去中心化多端合并 [Issue #240](https://github.com/cozodb/cozo/issues/240)、[Issue #252](https://github.com/cozodb/cozo/issues/252)。当前 `cozo` 核心尚无内置 CRDT 层，第三方集成需要自行在外层包装合并逻辑。
- **维护活跃度**：Issue #301 指出距上次提交已过一年，引发社区对长期维护的担忧 [Issue #301](https://github.com/cozodb/cozo/issues/301)。使用者应在依赖关系中固定版本并关注后续提交。
- **向量库生态对接**：Issue #238 期待 LlamaIndex/LangChain 适配器，目前需要用户在应用层自行完成 `DataValue` ↔ 框架数据结构的转换 [Issue #238](https://github.com/cozodb/cozo/issues/238)。

## 5. 常见使用模式小结

1. **嵌入式单进程** → 选用 `mem` 或 `sqlite` 引擎，通过 C/Rust/Node.js/Java/WASM 绑定直接调用 `run`。
2. **服务端多用户** → 启动 `cozo-bin` 的 HTTP 模式，客户端仅以 JSON 提交脚本与参数，避免拼接字符串。
3. **大规模持久化 + 向量召回** → 选用 `rocksdb` 引擎，按需调整 `DbOpts` 中的布隆过滤器、blob 文件、块缓存等参数。
4. **检索增强生成 (RAG)** → 在同一脚本内把 HNSW 召回、全文过滤、图遍历与关系连接组合，输出排序后的候选集。

## See Also

- [cozo-bin/src/server.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/server.rs) — HTTP 服务实现
- [cozorocks/src/bridge/db.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/db.rs) — RocksDB 选项
- [cozo-core/src/fts/README.md](https://github.com/cozodb/cozo/blob/main/cozo-core/src/fts/README.md) — 全文搜索与停用词
- [Issue #238](https://github.com/cozodb/cozo/issues/238) — LangChain/LlamaIndex 集成讨论
- [Issue #240](https://github.com/cozodb/cozo/issues/240)、[Issue #252](https://github.com/cozodb/cozo/issues/252) — CRDT 同步探讨
- [Issue #301](https://github.com/cozodb/cozo/issues/301) — 项目维护状态

---

<a id='page-3'></a>

## 语言绑定、存储后端与部署

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [生态集成、可扩展性与社区议题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/cozodb/cozo/blob/main/README.md)
- [cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md)
- [cozo-bin/src/server.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/server.rs)
- [cozo-bin/src/repl.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/repl.rs)
- [cozo-bin/src/client.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/client.rs)
- [cozo-core/README.md](https://github.com/cozodb/cozo/blob/main/cozo-core/README.md)
- [cozo-lib-c/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/src/lib.rs)
- [cozo-lib-nodejs/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/src/lib.rs)
- [cozo-lib-nodejs/package.json](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/package.json)
- [cozo-lib-java/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-java/src/lib.rs)
- [cozo-lib-wasm/README.md](https://github.com/cozodb/cozo/blob/main/cozo-lib-wasm/README.md)
- [cozorocks/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/lib.rs)
- [cozorocks/src/bridge/mod.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/mod.rs)

</details>

# 语言绑定、存储后端与部署

## 概述

CozoDB 采用「核心 + 多语言适配器 + 多存储后端」的分层设计：核心 Datalog 引擎位于 [`cozo-core`](https://github.com/cozodb/cozo/blob/main/cozo-core/README.md) 中，对外暴露 `DbInstance`、`NamedRows`、`DataValue` 等统一抽象，仓库上层则以独立子 crate 形式提供 C / Node.js / Java / WASM 等多语言绑定，并由 [`cozo-bin`](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md) 子项目提供 HTTP 服务、REPL 与命令行客户端两种部署形态。存储层则通过统一的 `engine` 字符串切换 `mem` / `sqlite` / `rocksdb` 三种后端，从而在不修改业务代码的前提下满足从嵌入式到高吞吐服务的不同部署需求。

## 语言绑定

### C 语言绑定

`cozo-lib-c` 是其它绑定的基座，它以全局 `HANDLES` 表把 `DbInstance` 句柄映射为 `i32` 句柄 ID，从而绕开 C-ABI 中不能直接传递 Rust 类型的限制。资料来源：[cozo-lib-c/src/lib.rs:1-45]()。

关键 API 摘要：

| 函数 | 作用 |
| --- | --- |
| `cozo_open` | 打开数据库，返回 `db_id` |
| `cozo_run_query` | 执行 CozoScript，可携带命名参数 |
| `cozo_close` | 关闭数据库并释放句柄 |
| `cozo_export` / `cozo_import` | 数据集导入导出 |
| `cozo_backup` / `cozo_restore` | 备份与恢复 |
| `cozo_import_from_backup` | 从备份字符串批量灌入数据 |
| `cozo_free_str` | 释放 Cozo 返回的 C 字符串（必须成对调用） |

调用方在 `cozo_open` 时传入 `engine` 字段（`"mem"`、`"sqlite"` 或 `"rocksdb"`）以及 JSON 形式的 `options`，即可选择底层存储实现。资料来源：[cozo-lib-c/src/lib.rs:31-80]()。

### Node.js 绑定

[`cozo-lib-nodejs`](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/package.json) 通过 `neon` 暴露给 JavaScript，并使用 `@mapbox/node-pre-gyp` 在安装阶段拉取对应平台与 napi 版本的预编译产物（`napi_versions: [6]`）。在 Rust 侧，`rows2js` 与 `named_rows2js` 把内部 `Vec<DataValue>` 转换成嵌套的 JS 数组／对象，而 `value2js` 负责把 `DataValue` 的 `Null` / `Bool` / `Num` / `Str` / `List` / `Set` 等变体映射为 JavaScript 值类型。资料来源：[cozo-lib-nodejs/src/lib.rs:1-50]()。

### Java 绑定

`cozo-lib-java` 使用 JNI，将 `Java_org_cozodb_CozoJavaBridge_openDb` 等方法导出为 Java 端可调用的 `native` 入口。引擎标识、路径、配置都以 `JString` 传入并通过 `env.get_string(...).unwrap().into()` 解码为 Rust `String`，沿用与 C 端一致的 `HANDLES` 句柄池。资料来源：[cozo-lib-java/src/lib.rs:1-50]()。

### WASM 绑定

`cozo-lib-wasm` 通过 `wasm-pack` 构建，发布版本使用 `wasm-pack build --target web --release` 并设置 `CARGO_PROFILE_RELEASE_LTO=fat` 以减小体积。注意 `--target web` 是默认推荐项；若需在 Web Worker 中跨浏览器运行，则需要改用 `--target no-modules` 并自行编写胶水代码。资料来源：[cozo-lib-wasm/README.md:1-15]()。

## 存储后端

### 引擎选型

在所有绑定中，存储后端都通过 `engine` 字符串与 JSON `options` 选择，Cozo 自身内置 `mem`、`sqlite`、`rocksdb` 三种实现（参见 [`cozo-lib-c/src/lib.rs`](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/src/lib.rs) 中的注释）。三者的典型适用场景如下：

| 后端 | 持久化 | 适用场景 |
| --- | --- | --- |
| `mem` | 否 | 单元测试、临时图计算、Demo |
| `sqlite` | 是（单文件） | 嵌入式 / 桌面 / 移动端 |
| `rocksdb` | 是（LSM 目录） | 服务端高并发、大数据量 |

### RocksDB 桥接

`cozorocks` 子 crate 通过 `autocxx` / `bindgen` 把 RocksDB 的 C++ API 暴露为 `RocksDbBridge`、`TxBridge`、`SstFileWriterBridge`、`PinnableSlice` 等 Rust 抽象，并最终在 [`cozorocks/src/lib.rs`](https://github.com/cozodb/cozo/blob/main/cozorocks/src/lib.rs) 中以 `DbBuilder`、`RocksDb`、`TxBuilder`、`Tx`、`IterBuilder`、`DbIter`、`PinSlice` 等高层 API 重新暴露。状态码、严重级别与子码（`StatusCode` / `StatusSeverity` / `StatusSubCode`）与 RocksDB C++ 头文件保持一致，便于在出错时通过 `RocksDbStatus::is_ok`、`is_not_found`、`is_ok_or_not_found` 等辅助方法快速分支处理。资料来源：[cozorocks/src/bridge/mod.rs:1-80]()。

## 部署模式

### HTTP 服务

`cozo-bin` 通过 `axum` 暴露多端点服务：默认监听 `127.0.0.1:9070`，其中 `POST /text-query` 接收形如 `{"script": "...", "params": {...}}` 的 JSON 请求，返回值始终是包含 `ok` 字段的 JSON 对象；命名参数应当通过 `params` 传入，避免脚本字符串拼接造成的注入风险。资料来源：[cozo-bin/README.md:30-60]()。在 `cozo-bin/src/server.rs` 中还实现了 SSE、`/import`、备份/恢复等路由，并通过 `tower_http` 引入 CORS、压缩与可选鉴权层。资料来源：[cozo-bin/src/server.rs:1-50]()。

### REPL 与 CLI

`cozo-bin/src/repl.rs` 借助 `rustyline` 提供交互式解释器，常用元命令包括 `%set` / `%unset` / `%clear` / `%params` 用于参数管理，`%run` 跑脚本，`%import` 导入 JSON，`%save` 把下次查询结果落盘，`%backup` / `%restore` 做整库备份恢复。资料来源：[cozo-bin/src/repl.rs:1-50]()。命令行入口由 `cozo-bin/src/main.rs` 解析 `--engine` 等参数选择后端，再根据子命令分发到服务端、REPL 或 [`cozo-bin/src/client.rs`](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/client.rs) 的客户端模式。

### 端到端架构

```mermaid
flowchart LR
    subgraph Apps["客户端"]
        A1[Node.js / Python / Java / Go / Swift]
        A2[Browser / WebAssembly]
        A3[HTTP / curl 客户端]
    end
    subgraph Bindings["语言绑定层"]
        B1[cozo-lib-c]
        B2[cozo-lib-nodejs]
        B3[cozo-lib-java]
        B4[cozo-lib-wasm]
    end
    subgraph Server["服务层"]
        S1[cozo-bin HTTP server<br/>axum :9070]
        S2[cozo-bin REPL / CLI]
    end
    subgraph Core["核心引擎 cozo-core"]
        C1[Datalog 解析与求值]
        C2[索引：HNSW / MinHash / FTS]
    end
    subgraph Storage["存储后端"]
        ST1[mem]
        ST2[sqlite]
        ST3[rocksdb<br/>cozorocks 桥接]
    end
    A1 --> B1
    A1 --> B2
    A1 --> B3
    A2 --> B4
    A3 --> S1
    B1 --> S1
    B2 --> S1
    B3 --> S1
    B4 --> S1
    S1 --> C1
    S2 --> C1
    C1 --> C2
    C1 --> ST1
    C1 --> ST2
    C1 --> ST3
```

## 选型与运维建议

- **嵌入式 / 移动端**：选择 `sqlite` 后端，配合 Java（Android）或 Swift 绑定，单文件即可携带；如需更高写入吞吐，可切换到 `rocksdb` 并在 `options` 中调高 `block_cache_size`。资料来源：[cozorocks/src/bridge/mod.rs:40-80]()。
- **浏览器与边缘**：优先使用 `cozo-lib-wasm` 的 `--target web` 产物，在需要跨标签页通信时改用 `--target no-modules` + Web Worker。资料来源：[cozo-lib-wasm/README.md:1-15]()。
- **服务化部署**：通过 `cozo-bin` 的 HTTP 模式运行，统一以 `POST /text-query` 暴露能力，并以命名参数 `params` 接收外部输入；社区曾多次讨论在多设备间同步的需求（如 issue #240、#252），目前官方并未提供内置 CRDT，可结合外部同步层或自定义触发器实现。资料来源：[cozo-bin/README.md:30-60]()。
- **维护状态**：社区 issue #301 关注项目是否仍在维护；截至当前最新发布 `v0.7.6`，绑定层与 `cozo-bin` 的核心入口（`cozo_run_query` 文档更新等）仍有持续提交，建议升级前关注 release notes 与 changelog。资料来源：[cozo-lib-nodejs/package.json:1-25]()。

## See Also

- [README.md](https://github.com/cozodb/cozo/blob/main/README.md) — 项目总体介绍与新版本说明
- [cozo-core/README.md](https://github.com/cozodb/cozo/blob/main/cozo-core/README.md) — 核心 Datalog 引擎
- [cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md) — HTTP 服务与 REPL 详细说明
- [cozorocks/README.md](https://github.com/cozodb/cozo/blob/main/cozorocks/README.md) — RocksDB C++ 绑定说明

---

<a id='page-4'></a>

## 生态集成、可扩展性与社区议题

### 相关页面

相关主题：[核心功能、查询引擎与图算法](#page-2), [语言绑定、存储后端与部署](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/cozodb/cozo/blob/main/README.md)
- [cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md)
- [cozo-bin/src/server.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/server.rs)
- [cozo-bin/src/repl.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/repl.rs)
- [cozo-lib-c/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/src/lib.rs)
- [cozo-lib-java/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-java/src/lib.rs)
- [cozo-lib-nodejs/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/src/lib.rs)
- [cozo-lib-nodejs/package.json](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/package.json)
- [cozo-lib-wasm/README.md](https://github.com/cozodb/cozo/blob/main/cozo-lib-wasm/README.md)
- [cozorocks/README.md](https://github.com/cozodb/cozo/blob/main/cozorocks/README.md)
- [cozorocks/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/lib.rs)
- [cozorocks/src/bridge/mod.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/mod.rs)
</details>

# 生态集成、可扩展性与社区议题

本页聚焦 CozoDB 在多语言绑定、存储引擎可扩展性、AI/向量生态集成以及社区当前关注的议题。CozoDB 以 `cozo-core` 为核心，通过若干外围 crate 将能力暴露给不同的宿主语言与运行环境。资料来源：[README.md](https://github.com/cozodb/cozo/blob/main/README.md)

## 语言绑定生态

Cozo 通过一组独立的 crate 把同一份核心逻辑暴露到多种宿主语言与运行时。下表汇总了仓库内可见的绑定层。

| 绑定层 | 仓库子目录 | 主要职责 | 关键引用 |
|---|---|---|---|
| C ABI | `cozo-lib-c` | 提供 `cozo_open`、`cozo_run_query`、`cozo_backup`、`cozo_import_relations` 等 C 导出符号，并要求返回字符串必须经 `cozo_free_str` 释放 | [cozo-lib-c/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/src/lib.rs) |
| Java/JNI | `cozo-lib-java` | 通过 `Java_org_cozodb_CozoJavaBridge_openDb` 等 JNI 入口暴露数据库句柄管理 | [cozo-lib-java/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-java/src/lib.rs) |
| Node.js (N-API) | `cozo-lib-nodejs` | 使用 `neon` 将 `DataValue`/`NamedRows` 转换为 JS 对象，配合 `node-pre-gyp` 分发预编译二进制 | [cozo-lib-nodejs/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/src/lib.rs) |
| WebAssembly | `cozo-lib-wasm` | 通过 `wasm-pack` 构建为 `--target web` 的 ES 模块，推荐在浏览器或 Web Worker 中使用 | [cozo-lib-wasm/README.md](https://github.com/cozodb/cozo/blob/main/cozo-lib-wasm/README.md) |
| RocksDB FFI | `cozorocks` | 基于 `autocxx`/`bindgen` 封装 RocksDB C++ API，提供 `RocksDb`、`DbIter`、`Tx` 等高层抽象 | [cozorocks/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/lib.rs) |

各绑定在内部都通过一个共享的句柄表（`BTreeMap<i32, DbInstance>`）与核心层通信，C 与 Java 版本使用 `lazy_static` 维护该表，而 Node.js 版本则借助 `crossbeam::channel` 的 `Sender` 将跨线程任务派发到核心。资料来源：[cozo-lib-c/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-c/src/lib.rs), [cozo-lib-java/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozo-lib-java/src/lib.rs)

## 存储引擎与服务器层可扩展性

`cozo-bin` 同时承担两条用途：交互式 REPL 与 HTTP 服务器。命令行参数允许用户在启动时选择后端存储引擎，并通过 meta 命令（`%set`、`%run`、`%backup`、`%restore` 等）扩展会话行为。资料来源：[cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md), [cozo-bin/src/repl.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/repl.rs)

HTTP 服务基于 `axum` + `tower-http`，路由包括 `POST /text-query`、`GET /export/{relations}`、`PUT /import`、`POST /backup`、`POST /import-from-backup`，并通过 `AsyncRequireAuthorizationLayer` 启用 token 鉴权。实验性的 `GET(SSE) /changes/{relation}` 端点允许客户端订阅关系变更事件，为同步或审计类需求提供了钩子。资料来源：[cozo-bin/src/server.rs](https://github.com/cozodb/cozo/blob/main/cozo-bin/src/server.rs)

```mermaid
flowchart LR
    A[cozo-lib-c / Java / Node / WASM] --> B[cozo-core DbInstance]
    C[cozo-bin CLI / REPL] --> B
    D[cozo-bin HTTP Server axum] --> B
    B --> E[(mem / sqlite / rocksdb)]
    E -.变更流.-> D
```

存储引擎层通过 `cozorocks` 暴露 RocksDB 的 `DbBuilder`、`TxBuilder`、`SstFileWriter`，错误码使用 `StatusCode`/`StatusSubCode`/`StatusSeverity` 三元组表达，桥接层会把 `kNotFound` 等情况归类为可恢复错误。资料来源：[cozorocks/src/lib.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/lib.rs), [cozorocks/src/bridge/mod.rs](https://github.com/cozodb/cozo/blob/main/cozorocks/src/bridge/mod.rs)

## 向量检索与 AI 生态集成

v0.6 在 Datalog 内部引入了 HNSW 索引，可对包含向量的关系建立多个索引并附加过滤条件；v0.7 又补充了 MinHash-LSH（用于近似去重）、全文检索以及 JSON 值类型。资料来源：[README.md](https://github.com/cozodb/cozo/blob/main/README.md)

这使得 Cozo 有潜力直接作为向量/图存储后端嵌入 RAG 链路。社区已有相关讨论：Issue #238 询问是否能与 LangChain / LlamaIndex 的 VectorStore 接口对接；Issue #256 关注 int8/binary 等低精度嵌入的存储需求。受限于当前主线尚未提供专门的 Python 绑定或 LangChain 适配器，集成一般通过两种路径实现：
1. 在 Python 进程中以子进程方式调用 `cozo-bin` HTTP 服务，复用 `/text-query` 与 `/export` 端点；
2. 通过 `cozo-lib-c` 在自定义扩展中直接执行查询脚本。

## 社区议题与项目状态

社区讨论中关注度最高的两类话题分别是 **跨设备同步** 与 **维护活跃度**：

- **CRDT 同步**：Issue #240 与 #252 均询问能否像 `cr-sqlite` 那样基于 Datalog CRDT 实现多端合并。截至当前仓库源码，Cozo 并没有内置 CRDT 合并算子，但 `cozo-bin` 的 SSE `/changes/{relation}` 端点已经为外部实现变更订阅提供了基础原语。资料来源：[cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md)
- **维护状态**：Issue #301 指出距离上一次提交已有一年。最新发布版本为 v0.7.6，仅包含 `@michaelsbradleyjr` 在 PR #190 中对 `cozo_run_query` 文档注释的更新；用户应在使用前查阅 release notes 与 changelog 以确认兼容性。资料来源：[cozo-lib-nodejs/package.json](https://github.com/cozodb/cozo/blob/main/cozo-lib-nodejs/package.json)

对于希望在生产环境中部署的用户，建议：

1. 锁定具体版本（`Cargo.toml` 或 `package.json` 中显式指定），避免 minor 版本漂移；
2. 优先通过 `cozo-bin` HTTP 服务或官方维护的语言绑定接入，避免直接 fork 核心；
3. 若需要 CRDT、自定义向量量化或第三方 AI 框架适配，应在 issue 中先与维护者确认 roadmap，再决定是上游贡献还是外部封装。

## 参见

- 项目主页与文档：[README.md](https://github.com/cozodb/cozo/blob/main/README.md)
- 服务器/CLI 详细说明：[cozo-bin/README.md](https://github.com/cozodb/cozo/blob/main/cozo-bin/README.md)
- RocksDB 绑定：[cozorocks/README.md](https://github.com/cozodb/cozo/blob/main/cozorocks/README.md)
- WASM 构建说明：[cozo-lib-wasm/README.md](https://github.com/cozodb/cozo/blob/main/cozo-lib-wasm/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：cozodb/cozo

摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Destroying a DbInstance。

## 1. 安装坑 · 来源证据：Destroying a DbInstance

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Destroying a DbInstance
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/cozodb/cozo/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：`env_logger` should not be a dependency of `cozo-core`

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`env_logger` should not be a dependency of `cozo-core`
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/cozodb/cozo/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：cargo update breaks due to newer rayon version

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：cargo update breaks due to newer rayon version
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/cozodb/cozo/issues/298 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/cozodb/cozo | README/documentation is current enough for a first validation pass.

## 5. 运行坑 · 来源证据：Benchmarks don't compile: missing ScriptMutability argument

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Benchmarks don't compile: missing ScriptMutability argument
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/cozodb/cozo/issues/307 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 运行坑 · 来源证据：Regression: newrocks feature does not compile correctly

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Regression: newrocks feature does not compile correctly
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/cozodb/cozo/issues/289 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 运行坑 · 来源证据：Sled backend: fix broken del() and implement time travel support

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Sled backend: fix broken del() and implement time travel support
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/cozodb/cozo/issues/306 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 运行坑 · 运行可能依赖外部服务

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | https://github.com/cozodb/cozo | matched external service / cloud / webhook / database keyword

## 9. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/cozodb/cozo | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/cozodb/cozo | no_demo; severity=medium

## 11. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/cozodb/cozo | no_demo; severity=medium

## 12. 安全/权限坑 · 来源证据：RUSTSEC-2024-0379 affects this crate

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RUSTSEC-2024-0379 affects this crate
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/cozodb/cozo/issues/291 | 来源类型 github_issue 暴露的待验证使用条件。

## 13. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/cozodb/cozo | issue_or_pr_quality=unknown

## 14. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/cozodb/cozo | release_recency=unknown

<!-- canonical_name: cozodb/cozo; human_manual_source: deepwiki_human_wiki -->