[图数据库/TypeDB] typedb 2.x 与 typedb 3.x 的区别

1 区别对比

• TypeDB 3.x 是一次不兼容的大重写：引擎从 Java 换成 Rust，查询语言升到 TypeQL 3，推理从「【规则隐式补全】」改成「【函数显式调用】」。
• 协议、Schema、数据和驱动都不能直接沿用 2.x。
• 官方对照见 TypeDB 2.x to 3.x: what’s changed - typedb.com

迁移流程见 migration process - typedb.com 。3.0.0 于 2024-12-20 发布；截至 2026-10 驱动已到 3.14.x。

---

1. 引擎与产品层

维度	TypeDB 2.x	TypeDB 3.x
实现	以 Java 为主	Rust 重写，架构更简、内存更小
性能（官方宣称）	基线	事务负载约 3–5 倍，并称可与 MongoDB 事务负载相当
隔离	Session + Transaction	取消 Session，连接后直接开 read / write / schema 事务
鉴权	视版本/版本套件而定	所有版本都带用户管理
语义取向	更偏谓词逻辑 + 规则推理	更偏类型论：数据模型与计算分离

事务仍是 ACID，隔离级别为 snapshot isolation，读写可并发。

---

2. 数据模型：最大语义变化

【属性(Attribute)】不再是「小实体」。 3.x 把 attribute 收成【纯值概念】：

• 【属性】不能再拥有属性（2.x 的 bio has bio-version 必须改模，否则导入报错）。

• 【属性】不能再扮演【角色】（plays）。

• 【属性类型】即使 非 abstract 也可以【子类型化】。

• 【根类型】不再预定义：不能写 person sub entity，必须写 entity person / relation friendship / attribute name。

• owns / plays 不再用 as 覆盖：【子类型】必须继承【超类型】的全部 owns/plays，不能「藏」掉【父类定义】。relates 仍可用 as 特化。

• 默认基数（2.x 没有这套默认约束）：

  • owns、relates：@card(0..1)
  • plays：@card(0..)
  • 一对多必须显式写 @card(0..)，否则插入第二条会失败。

整数类型名：long → integer（底层仍是 64 位有符号整数）。

---

3. TypeQL：从「单条查询」到「流水线」

Schema

• 2.x

# 2.x
define
  person sub entity, owns age, plays friendship:friend;
  friendship sub relation, relates friend;
  age sub attribute, value long;
  object sub entity, abstract;
  phone-number sub attribute, regex "\\d{10}";
  rule my-rule: when { ... } then { ... };

在 TypeQL 里，A sub B 表示 A 是 B 的【子类型】：A 继承 B 的约束和角色（owns 拥有哪些属性 / plays 扮演哪些角色 / relates 与谁有链接关系 等）。
2.x 里常写成 person sub entity，意思是「person 是一种实体」。
3.x 改成直接声明种类：entity person；【子类型关系】语法仍可写，例如 entity person, sub animal;。

• 3.x

# 3.x
define
  entity person, owns age, plays friendship:friend;
  relation friendship, relates friend;
  attribute age, value integer;
  entity object @abstract;
  attribute phone-number, value string @regex("\\d{10}");
  fun reachable($from: node) -> { node }:
    match ...;
    return { $to };

【约束】从【散落关键字】收成 @ 注解：@abstract、@regex、@card、@key、@unique、@range、@values（枚举）。另有 redefine，专门改已有 Schema。

undefine / delete 必须指向明确目标，例如：

undefine owns age from person;
undefine @abstract from friendship relates friend;
delete has $name of $x;
delete links (friend: $p) of $rel;

数据查询

2.x	3.x
get $x;	match 本身就出行；过滤用 select
值变量 ?x	一律 $x，赋值用 let $x = ...
$f (friend: $p) isa friendship;	$f isa friendship (friend: $p);（括号在 isa 后面）
get; sum; 聚合	独立阶段 reduce
客户端拼多条查询	Query pipeline：match → reduce → match → insert/delete/update/put → fetch
fetch 较松散	fetch { ... } 与 JSON 结构对齐；[] 多答案、() 单答案；$x.* 展开全部属性

• 【关系构造】也统一了：

insert
  $p isa person;
  $f isa friendship (friend: $p);   # 3.x
  $a isa age 20;

• 2.x 常见写法是 $f (friend: $p) isa friendship; 和 $a isa age; $a == 20;。

---

4. 推理：Rules → Functions

这是使用体验上最大的断裂。

	2.x Rules	3.x Functions
触发	查询时 隐式 补全实例（像多了几条「看不见的数据」）	查询里 显式 let $x, $y in reachable();
结果	推断出 schema 里已有类型的实例	返回概念、值、流、布尔；不强制变成新实例
规划器	可自动决定哪些角色是输入/输出	参数与返回值要你自己定；「上下文绑定函数」规划中
无限/开放世界	可通过嵌套 relation 在理论上生成任意大模型	当前受类型域限制（如 integer）；规划用 list 补齐

同一条「可达」规则，3.x 往往要拆成「枚举对 / 从某点出发 / 布尔判定」等多个函数。【函数】仍是 按需、目标驱动 求值，不在【写入时物化】全部结果。

详见 Functions v/s rules。

---

5. 驱动与客户端 API

2.x：query().insert()、query().define()、concept.delete()、getHas()、setLabel() 等概念树 API。

3.x：几乎全部走 transaction.query("...")。概念对象还在，但 Thing 改名为 Instance；改 【schema/数据】用 TypeQL，不用 OOP 方法。

3.x 官方驱动现状（约 3.14）： Rust、Python、Java、C#、C，以及 TypeScript HTTP（@typedb/driver-http）。Node.js gRPC 与 C++ 的 2.x 驱动尚未升到 3.x，可用 HTTP API 代替。文档里「暂时缺失」一节可能滞后，以 typedb-driver 为准。

---

6. 2.x 有、3.x 仍弱或已拿掉的能力

仍在演进（官方 diff 页）：

• 用 as 限制子类型实例化继承来的 owns/plays（不能再「隐藏」父类 【trait】）。

刻意移除：

• 属性拥有属性、属性扮演角色。
• Session。
• 规则推理与静默补全。

设计上 3.x 还做不到 2.x 那种「任意嵌套 relation 撑开开放世界搜索」；官方计划用 【list】 补。

---

7. 迁移要点

2.x 与 3.x 不能在线滚动升级。标准路径：

1. 用 2.x typedb server export 导出 schema 文本 + 二进制数据。
2. 手工改 schema（kind、integer、@ 注解、基数、去掉 rules）。
3. 若有「属性拥有属性」，先在 2.x 里把所有权挪到实体/关系上。
4. 3.x Console：database import <db> <schema.typeql> <data.typedb>。
5. 再定义 functions，改应用查询与驱动。

3.4.0 起导出二进制在版本间对齐，专门用于这种不兼容升级。

---

8. 怎么选

• 新项目：直接 3.x。流水线、基数/@values/@range、函数，都是 2.x 长期缺口。
• 重度依赖 rule 静默推理、属性嵌套、owns/plays 覆盖、Node.js gRPC：先对照 missing features 和建模改造成本，再迁。
• 只做简单实体-关系-属性 CRUD：语言表面改得多，模型本身大多能一对一翻过去；真正费时的是 默认 @card(0..1) 和 规则改函数。

小结： 2.x 是「带规则的多态知识库」；3.x 是「带约束、流水线和显式函数的【类型数据库】」。 不是补丁升级，是同一产品线的第二代。

Y 推荐文献

X 参考文献