[图数据库/知识图谱] TypeDB 使用指南

0 序

适用对象:已有 JDBC / 关系型数据库基础、想快速上手 TypeDB 的 Java 开发者。
本教程以 xxx 平台 xxx-common-typedb + xxx-modules/xxx-object-service 的真实接入方式为蓝本,
版本基于 TypeDB 官方 Java Driver com.typedb:typedb-driver 3.14.0(gRPC 协议,默认端口 1729)。

  • 全篇默认以 typedb 3.x 展开描述。

1 安装部署篇

方式1: Docker(推荐,Linux/Windows/macOS 通用)

亲测

  • 前置步骤: 安装 Docker 环境(Windows 中对应是 Docker Desktop)

  • 拉取镜像、并创建/运行容器

# 拉取并运行 TypeDB 服务(gRPC 端口 1729;Studio HTTP 端口 8000)
docker run -d --name typedb -p 1729:1729 -p 8000:8000 typedb/typedb:3.14.0
  或 docker run -d --name typedb -p 1729:1729 -p 8000:8000 typedb/typedb:latest
  • TypeDB 3.x 默认账密: admin / password

方式2: Docker Compose(推荐,Linux/Windows/macOS 通用)

亲测(假设 Windows 系统)

  • 前置步骤: 安装 Docker 环境(Windows 中对应是 Docker Desktop)

新建、并配置 docker-compose-typedb.yml

假设将 typedb 数据库的数据存储在外部的 Windows 系统下 D:\Program-Data\TypeDB-Data\ 目录。

# docker run -d --name typedb -p 1729:1729 -p 8000:8000 typedb/typedb:3.14.0
services:
  typedb:
    image: typedb/typedb:3.14.0
    container_name: typedb
    restart: always

    ports:
      - "1729:1729"
      - "8000:8000"

    volumes:
      # 数据目录
      #- /data/datasource/typedb/data:/var/lib/typedb/data
      - /D/Program-Data/TypeDB-Data/data:/var/lib/typedb/data

      # TypeDB 配置文件
      #- /data/datasource/typedb/config/config.yml:/opt/typedb/server/config.yml:ro
      - /D/Program-Data/TypeDB-Data/config/config.yml:/opt/typedb/server/config.yml:ro

    command:
      - --config=/opt/typedb/server/config.yml

    ulimits:
      nofile:
        soft: 65535
        hard: 65535

注:记得手动创建 /D/Program-Data/TypeDB-Data/config/、/D/Program-Data/TypeDB-Data/data/ 2个路径。

新建、并配置 config.yml

server:
  listen-address: "0.0.0.0:1729"

  http:
    enabled: true
    listen-address: "0.0.0.0:8000"

  admin:
    enabled: true
    port: 1728

  authentication:
    token-expiration-seconds: 5000

  encryption:
    enabled: false
    certificate:
    certificate-key:
    ca-certificate:

storage:
  data-directory: "/opt/typedb/server/data"

  rocksdb:
    cache-size: "8gb"
    write-buffers-limit: "2gb"

logging:
  directory: "/opt/typedb/server/logs"

diagnostics:
  monitoring:
    enabled: true
    port: 4104

  reporting:
    metrics: true
    errors: true

拉取镜像、并启动容器

docker-compose -f "D:\Program-Data\Docker-Compose-Files\docker-compose-typedb.yml" pull

docker-compose -f "D:\Program-Data\Docker-Compose-Files\docker-compose-typedb.yml" up -d

补充:日常运维命令

确认指定服务容器是否在运行

> docker ps --filter "name=typedb"
CONTAINER ID   IMAGE                  COMMAND                   CREATED          STATUS          PORTS                                                                                      NAMES
8d705f2abe14   typedb/typedb:3.14.0   "/opt/typedb-server-…"   13 minutes ago   Up 13 minutes   0.0.0.0:1729->1729/tcp, [::]:1729->1729/tcp, 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp   typedb

> docker inspect typedb
(略)

进入容器内

PS D:\Program-Data\Docker-Compose-Files> docker exec -it typedb /bin/bash
root@8d705f2abe14:/opt/typedb-server-linux-x86_64#

执行指定指令

PS D:\Program-Data\Docker-Compose-Files> docker exec -it typedb sh -c "cat /etc/os-release && pwd && ls -la"
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
VERSION="22.04.5 LTS (Jammy Jellyfish)"
VERSION_CODENAME=jammy
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=jammy

/opt/typedb-server-linux-x86_64

total 40
drwxr-xr-x 4 root root  4096 Jan  1  2000 .
drwxr-xr-x 1 root root  4096 Oct 31 02:20 ..
-rwxr--r-- 1 root root 16726 Jan  1  2000 LICENSE
drwxr-xr-x 2 root root  4096 Jan  1  2000 admin
drwxr-xr-x 2 root root  4096 Jan  1  2000 server
-rwxr--r-- 1 root root  2480 Jan  1  2000 typedb

What's next:
    Try Docker Debug for seamless, persistent debugging tools in any container or image → docker debug typedb
    Learn more at https://docs.docker.com/go/debug-cli/
	

PS D:\Program-Data\Docker-Compose-Files> docker exec -it typedb sh -c "ps -ef"
UID          PID    PPID  C STIME TTY          TIME CMD
root           1       0  0 02:20 ?        00:00:10 /opt/typedb-server-linux-x86_64/server/typedb_server_bin --storage.data-directory=/var/lib/typedb/data --config=/opt/typedb/server/config.yml
root         166       0  0 02:39 pts/0    00:00:00 sh -c ps -ef
root         172     166  0 02:39 pts/0    00:00:00 ps -ef

查看指定服务最近的日志

# 实时跟踪:
docker logs -f --tail 100 typedb

# 按时间过滤
docker logs --since 2026-10-30T00:00:00 typedb

# 在容器内搜索日志关键词 /opt/typedb/server/logs
PS D:\Program-Data\Docker-Compose-Files> docker exec -it typedb sh -c "grep -nR 'Ready' -A 2 /opt/typedb/server/logs"
/opt/typedb/server/logs/typedb.log.2026-10-31-02:2:Ready!
/opt/typedb/server/logs/typedb.log.2026-10-31-02-3-
/opt/typedb/server/logs/typedb.log.2026-10-31-02-4-2026-10-31T02:20:27.735727Z  INFO ThreadId(01) server/lib.rs:503: Hardware info - cpu: 16, memory: 11 GB (10 GB free), data directory: 1006 GB (949 GB free)


# 将日志导出到宿主机文件
docker logs typedb > /tmp/typedb-$(date +'%Y%m%d%H%M%S').log
grep -nRi "启动" /tmp/typedb-20261031*.log 
    注: Windows 系统下,/tmp 目录对应在 C:\Users\{USER}\AppData\Local\Temp

例如:

PS D:\Program-Data\Docker-Compose-Files> docker logs --tail=50 typedb
2026-10-31T02:20:27.731265Z  INFO ThreadId(01) server/lib.rs:498:
Ready!

=====================================================================================
     ________ __      __ _____    _______  _____    _____       _______  _______
    |__    __|\  \  /  /|   _  \ |   _   ||   _  \ |   _  \    |   _   ||   _   |
       |  |    \  \/  / |  | |  ||  | |__||  | |  ||  | |  |   |  | |  ||  | |__|
       |  |     \    /  |  |/  / |  |___  |  | |  ||  |/  /    |  | |__||  |___
       |  |      |  |   |   __/  |   ___| |  | |  ||   _  \    |  |  __ |   ___|
       |  |      |  |   |  |     |  |  __ |  | |  ||  | |  |   |  | |  ||  |  __
       |  |      |  |   |  |     |  |_|  ||  |/  / |  |/  /    |  |_|  ||  |_|  |
       |__|      |__|   |__|     |_______||_____/  |_____/     |_______||_______|

=====================================================================================

Running TypeDB CE 3.14.0.
Serving:
  gRPC:       0.0.0.0:1729
  HTTP:       0.0.0.0:8000
  Admin:      /var/lib/typedb/data/admin.sock (Unix socket)
  Monitoring: http://127.0.0.1:4104/diagnostics (Prometheus scrape)
              http://127.0.0.1:4104/diagnostics?format=json (JSON)
TLS: disabled
  WARNING: TLS NOT ENABLED. Credentials are transmitted unencrypted in plaintext.
  Drivers must be configured to connect *without TLS*.

To connect:
  Studio:  https://studio.typedb.com/connect?address=http://127.0.0.1:8000&username=admin
  Console: typedb console --address 127.0.0.1:1729 --tls-disabled --username admin

2026-10-31T02:20:27.735727Z  INFO ThreadId(01) server/lib.rs:503: Hardware info - cpu: 16, memory: 11 GB (10 GB free), data directory: 1006 GB (949 GB free)

方式3:系统包仓库(Debian/Ubuntu)

未亲测

curl -1sLf 'https://repo.typedb.com/public/public-release/setup.deb.sh' | sudo -E bash
sudo apt install typedb

方式4:直接下载二进制(Linux/macOS/Windows)

Windows 提示:TypeDB 3.x 提供 Windows 发行包,可直接运行 typedb server;若使用 Docker 需启用 Docker Desktop。

2 客户端使用篇

TypeDB Studio

  • URL

image

  • Schema
    image

  • Data
    image

  • Graph
    image

Java Driver

<!-- TypeDB 官方 Java Driver (gRPC 协议, 默认端口 1729) -->
<typedb-driver.version>3.14.0</typedb-driver.version>

<!-- TypeDB 官方 Java Driver (3.11.5),包含 gRPC 客户端与 JNI 原生层 -->
<dependency>
    <groupId>com.typedb</groupId>
    <artifactId>typedb-driver</artifactId>
    <version>${typedb-driver.version}</version>
</dependency>

3 核心概念篇(与关系型数据库的对照)

  • 从传统的关系型数据库到图数据库,跨度相对较大。为此有必要先做一个概念对比。

  • TypeDB 3.x 的核心是“类型优先的知识图谱数据库”:它不是二维表,而是用带类型的实体、关系和属性把数据织成图;查询用 TypeQL,并且 schema 里还能定义推理规则。

核心概念与 MySQL 对照

TypeDB 3.x 说明 MySQL 近似
类型 Type 实体、关系、属性在 schema 中定义的类型 表、列、约束的 DDL 定义
实体 Entity 有独立身份的实例,如“一个人”“一家公司” 一行数据/一个主键对象
属性 Attribute 挂到实体或关系上的值,如姓名、薪水 表中的一个列/单元格
关系 Relation 多个实例之间的关联,关系本身是一等公民 外键关联或“关系表”
角色 Role 关系两端或各端的具体语义,如“雇主/雇员” 外键字段所表达的语义
实例 Instance 实际存在的数据项 行记录
类型层次 子类型继承父类型 MySQL 没有原生的表继承
owns / plays 类型拥有哪些属性、能参与哪些角色 列定义、外键约束
key / unique / cardinality 标识和数量约束 主键、唯一约束、CHECK
规则 Rule 用逻辑推导新事实 视图、触发器或应用层逻辑
TypeQL 建 schema、查询、推理的语言 SQL

TypeDB 概念模型

graph TB TD["TypeDB 3.x"] --> ET["Entity Type 实体类型"] TD --> RT["Relation Type 关系类型"] TD --> AT["Attribute Type 属性类型"] TD --> Rule["Rule 推理规则"] ET -->|owns 拥有| AT ET -->|plays 扮演| Role["Role Type 角色类型"] RT -->|relates 关联| Role ET -->|sub 子类型| ET2["子 Entity Type"]

一个简单 TypeQL schema 片段

define
  name sub attribute, value string;
  person sub entity,
    owns name @key,
    plays employment:employee;
  company sub entity,
    owns name @key,
    plays employment:employer;
  employment sub relation,
    relates employee,
    relates employer;

对应的 MySQL 直觉是:

CREATE TABLE person (...) ;
CREATE TABLE company (...) ;
CREATE TABLE employment (
  employee_id ...,
  employer_id ...,
  FOREIGN KEY ... 
);

核心差异表

维度 TypeDB 3.x MySQL
建模方式 实体、关系、属性都是显式类型 表、行、列
关系表达 关系是独立对象,有角色,可再建模 关系靠外键和 JOIN 推导
推理能力 支持规则推理,可查询“派生”数据 需视图、存储过程或应用逻辑
查询语言 TypeQL,面向类型化图遍历 SQL,面向集合运算和表连接
类型约束 强类型 schema,角色/属性约束清晰 列类型 + 约束,表间关系较松散
擅长场景 知识图谱、多跳关系、反欺诈、推荐、复杂业务规则 高并发事务、CRUD、成熟报表生态

映射视角

flowchart LR subgraph MySQL模式 T[Table 表] --> R[Row 行] T --> C[Column 列] C --> V[Cell Value 值] end subgraph TypeDB模式 E[Entity 实体] --> A[Attribute 属性] REL[Relation 关系] --> ROLE[Role 角色] E --> ROLE end R -. "近似实例" .-> E C -. "近似属性" .-> A V -. "近似属性值" .-> A
  • 总结:

    • TypeDB 3.x 更强调“关系本身的类型语义和推理”,而 MySQL 更强调“用规范化表和 SQL 集合运算来描述同一套业务数据”。

    • 如果你需要表达复杂多跳关系并希望数据库替你推导新事实,TypeDB 会更顺手;如果主要是 CRUD、事务和报表,MySQL 仍是更经典的选择。

重要语法:TypeDB/TypeQL 的注释

  • TypeQL 只有行注释:【#】 起,直到行尾。没有【块注释】(没有 /* */)。
# 整行注释
match
  $customer isa customer;          # 行尾注释
  # $customer has risk-rating "high";  # 临时关掉一条约束

TypeDB 引擎会忽略 # 之后的内容。不要和 schema 里的 @ 注解(如 @card、@key)搞混,那不是注释。

重要语法:TypeDB 的 database / schema

  • 官方文档 & 官方示例

https://typedb.com/docs/core-concepts/typedb/databases/

# https://typedb.com/docs/core-concepts/typedb/databases/
# TypeDB 3.x schema:person / employee / employment
# 用法:TypeDB Studio 或 Console 中以 schema 事务执行后 commit

define                                    -- 模式查询:向 schema 新增类型/能力(幂等;不含变量)
  entity person,                          -- 声明独立实体类型 person(【entity】:独立存在的【对象类型】)
    owns name,                            -- person 可拥有属性 name(【owns】:实现【属性】的所有权接口)
    owns email,                           -- person 可拥有属性 email
    plays employment:employee;            -- person 可扮演雇佣关系中的 employee 角色
                                          -- 【plays】:实现【角色接口】;employment:employee 是【关系:角色】限定名

  attribute name, value string;           -- 【attribute】 声明【属性类型】 name,取值类型为 string
                                          -- attribute:以值为身份的类型;【value】:规定【唯一的值类型】

  attribute email, value string;          -- 声明属性类型 email,取值类型为 string

  entity employee sub person,             -- 声明实体类型 employee,它是 person 的【sub/子类型】
                                          -- 【sub】:同 kind 单继承;【子类型】继承【超类型】的 owns / plays
    owns employee-id;                     -- 在继承之外,employee 额外可拥有 employee-id

  attribute employee-id, value string;    -- 声明属性类型 employee-id,取值类型为 string

  relation employment,                    -- relation 声明【关系类型】 employment(relation:依赖角色参与者而存在)
    relates employee;                     -- 为该关系定义角色 employee(relates:声明角色接口)
                                          -- 完整角色名是 employment:employee,与实体 employee 不冲突
  • database/schema 的定义: define / undefine
  • 对象类型/实体类型的定义: entity / sub
  • 属性的定义: owns + attribute(value)
  • 关系的定义: play + relation(relates)

当然,也可调整顺序:

define

attribute name, 
  value string;
attribute email, value string;
attribute employee-id, value string;

entity person,
  owns email,
  owns name,
  plays employment:employee;

entity employee,
  sub person,
  owns employee-id;

relation employment,
  relates employee;

书写规则

符号/关键字 作用
define 整段是 schema 定义查询,不是数据插入
entity / attribute / relation 三种类型 kind
, 同一主语上串联多条能力(owns / plays / relates / sub)
; 一条【定义语句】结束
owns 属性声明/能力声明: 实体/关系「拥有」某个 attribute
plays 角色声明:实体/关系「扮演」某个 relation 的角色
relates 关系声明/链接声明:关系「声明」角色
sub 子类型;employee 会继承 person 的 name、email 以及 plays employment:employee
value string 数据类型声明:该 attribute 存字符串;同类值相同则是同一属性实例
employment:employee 【角色】必须带【关系作用域】,避免和其他关系里的【同名角色】混淆
  • TypeDB 3.14 里:一个 database 只对应一份 schema。

  • Attribute声明(owns): owns person-id;owns employee-id;owns id;三者的区别?

三者语法相同,都是「当前类型拥有某个属性」;差在挂上的属性类型不同,因而作用域、唯一性和能否多态查询都不同。

owns id owns person-id owns employee-id
挂的属性 通用 id 专属于人的 person-id 专属于雇员的 employee-id
意图 所有「有标识」的对象共用一类 ID 只标识【Person/人】 只标识【雇员/Employee】
谁该写 超类型 / 多种实体共用 person employee(常为 person 子类型)
查询 $x has id $v 直接命中所有拥有 id 的对象 不会命中,除非 person-id sub id 同上,除非 employee-id sub id
@key 唯一范围 所有拥有 id 的类型(含其子类型)共用一把钥匙 只在 person 族内唯一 只在 employee 族内唯一

推荐建模(抽象超属性 + 具体子属性):

define
  attribute id @abstract;                          -- 不能直接实例化,只当「标识」的总类
  attribute person-id   sub id, value string;      -- 人的证件号
  attribute employee-id sub id, value string;      -- 工号

  entity person,
    owns person-id @key;                           -- 每个人恰好一个、且不重复的 person-id

  entity employee sub person,
    owns employee-id @key;                         -- 继承 person-id,再加工号

对应的 UML类图:

classDiagram class id { <<abstract>> } class person-id { string } class employee-id { string } class person { owns person-id } class employee { owns employee-id inherits person-id } id <|-- person-id id <|-- employee-id person <|-- employee person --> person-id : owns employee --> employee-id : owns

数据侧对比:

-- 爱丽丝:普通人,只有 person-id
insert $p isa person, has person-id "P-001";

-- 鲍勃:雇员,两个 ID 都有(person-id 从 person 继承而来)
insert $e isa employee,
  has person-id "P-002",
  has employee-id "E-100";
查询 结果
$x has person-id $id 爱丽丝、鲍勃
$x has employee-id $id 只有鲍勃
$x has id $id(若上面两个都 sub id) 两个 ID 实例都算,多态扫全部标识

总结: id 是总类,person-id / employee-id 是特化;owns 只决定「谁能持有」;真正的语义差在属性类型本身,不在 owns 这个关键字。

重要语法:TypeDB 写入数据

# ============================================================
# TypeDB 3.x 样例数据:20 条 person 记录
#   - 前 10 条同时是 employee(sub person),各带 employee-id,
#     并为每位员工创建一条 employment 关系
#     (employment 只 relates employee,默认 @card(0..1),即一元关系)
#   - 后 10 条只是 person,用于体现 person / employee 的多态性
#
# 用法:先执行 schema.tql(schema 事务),再以 write 事务执行本文件后 commit
# ============================================================

insert

  # ---------- 员工(employee)01-10 ----------
  $p01 isa employee,
    has name "张伟",
    has email "zhang.wei@example.com",
    has employee-id "EMP-0001";
  employment(employee: $p01);

  $p02 isa employee,
    has name "王芳",
    has email "wang.fang@example.com",
    has employee-id "EMP-0002";
  employment(employee: $p02);

  $p03 isa employee,
    has name "李娜",
    has email "li.na@example.com",
    has employee-id "EMP-0003";
  employment(employee: $p03);

  $p04 isa employee,
    has name "刘洋",
    has email "liu.yang@example.com",
    has employee-id "EMP-0004";
  employment(employee: $p04);

  $p05 isa employee,
    has name "陈静",
    has email "chen.jing@example.com",
    has employee-id "EMP-0005";
  employment(employee: $p05);

  $p06 isa employee,
    has name "杨帆",
    has email "yang.fan@example.com",
    has employee-id "EMP-0006";
  employment(employee: $p06);

  $p07 isa employee,
    has name "赵敏",
    has email "zhao.min@example.com",
    has employee-id "EMP-0007";
  employment(employee: $p07);

  $p08 isa employee,
    has name "周杰",
    has email "zhou.jie@example.com",
    has employee-id "EMP-0008";
  employment(employee: $p08);

  $p09 isa employee,
    has name "吴磊",
    has email "wu.lei@example.com",
    has employee-id "EMP-0009";
  employment(employee: $p09);

  $p10 isa employee,
    has name "郑雪",
    has email "zheng.xue@example.com",
    has employee-id "EMP-0010";
  employment(employee: $p10);

  # ---------- 非员工(只是 person)11-20 ----------
  $p11 isa person,
    has name "孙浩",
    has email "sun.hao@example.com";

  $p12 isa person,
    has name "马晓东",
    has email "ma.xiaodong@example.com";

  $p13 isa person,
    has name "朱琳",
    has email "zhu.lin@example.com";

  $p14 isa person,
    has name "胡俊",
    has email "hu.jun@example.com";

  $p15 isa person,
    has name "林晓薇",
    has email "lin.xiaowei@example.com";

  $p16 isa person,
    has name "何雨",
    has email "he.yu@example.com";

  $p17 isa person,
    has name "高翔",
    has email "gao.xiang@example.com";

  $p18 isa person,
    has name "罗宇",
    has email "luo.yu@example.com";

  $p19 isa person,
    has name "梁晨",
    has email "liang.chen@example.com";

  $p20 isa person,
    has name "宋瑶",
    has email "song.yao@example.com";

重要语法:TypeDB 查询数据-查询示例

# 样例数据入库后的校验查询(read 事务执行)
# 注意:一次只能执行一条查询,按需分段复制

# 1) 查询员工信息 | 应为 10 行
match
  $p isa employee,
    has name $n,
    has email $e,
    has employee-id $id;
select $n, $e, $id;

# 2) 统计总人数 | 应为 20
match $p isa person;
reduce $person-count = count;


# 3) 员工与其 employment 关系的连查(应为 10 行)
match
  $p isa employee, has employee-id $id;
  employment(employee: $p);
select $id;

# 4) 只查"非员工"(应为 10 行,用 subtype 排除)
match
  $p isa person, has name $n;
  not { $p isa employee; };
select $n;

# 5) 以 fetch 输出 JSON 结果
match
  $p isa employee, has name $n, has email $e, has employee-id $id;
fetch
  { "name": $n, "email": $e, "employee-id": $id };

重要语法:TypeDB 查询数据-查询语法: match / select / reduce / fetch

  • TypeDB 3.x 的查询语法: match / select / reduce / fetch

https://typedb.com/docs/typeql-reference/pipelines/match/index.md

定位

这四者都是查询管线(pipeline)中的阶段,但职责完全不同:

  • match 负责"找数据"
  • select / reduce 负责"裁剪 / 归并行答案"
  • fetch 负责"把行答案翻译成 JSON 文档"

前三个输出的是行(rows),fetch 输出的是文档(documents)。

核心对比表

对比维度 match select reduce fetch
阶段性质 数据检索 + 过滤(pattern 匹配) 变量裁剪算子 聚合算子 结果格式转换(行 → 文档)
语法签名 match <pattern> select <var> [, <var> ...]; reduce <var> = <op> [(<var>)][, ...] [groupby <var>]; fetch { <fetch_body> };
是否读写数据 只读(检索、过滤) 只读(不改数据,只改行内容) 只读(不改数据,只压缩行数) 只读(不改数据,只改输出格式)
输入 行答案;若为管线首阶段则输入空行 {} 上一阶段的行答案 上一阶段的行答案 上一阶段的行答案(可为 match/insert 等任何产行阶段)
输出 行答案(每个输入行 × 模式的全部组合) 行答案,只保留指定变量 行答案,只保留聚合变量 + groupby 变量 文档(JSON),每个输入行一个文档
输出变量规则 新增未绑定的输出变量,其余透传 未列出的变量被丢弃 除聚合变量与分组变量外全部丢弃 结构由 fetch 体决定,与查询结构一一对应
是否可出现在管线中间 ✅ 可多次出现、可穿插(官方示例:match → reduce → match → select) ✅ 可,但之后的行只剩选定变量 ✅ 可,后续阶段可继续用聚合/分组变量 ❌ 终止阶段,后面不能再接任何阶段
语句顺序是否影响结果 ❌ 不影响(由优化器决定执行顺序) — — —
主要用途 按模式取实体/关系/属性,做逻辑组合(or、not、{}) 瘦身结果集、只取需要的变量(减少传输量) 计数、求和、均值、最大最小、分组统计(类 SQL 的 GROUP BY + 聚合) 直接产出前端/接口可用的 JSON(含嵌套、列表、子查询)
你 schema 中的典型写法 match $p isa employee, has employee-id $id; select $id; | reduce $c = count; fetch { "employee-id": $id };

语法形态速查表

关键字 官方语法形态 说明
match match <pattern> <pattern> 是合法 pattern,体内语句可用 ; 并列、or / not / {} 组合
select select $a; / select $a, $b; 变量列表,逗号分隔,末尾 ;
reduce reduce $x = count;
reduce $x = sum($v), $y = mean($v);
reduce $x = count groupby $g;
聚合可多个并列;groupby 产生"每组一行"
fetch fetch { $p.* };(全属性)
fetch { "k": $v };(键值)
fetch { "k": $p.name };(按属性类型)
fetch { "k": [$p.email] };(多值列表)
fetch { "k": { ...嵌套... } };
键值语句用逗号分隔,最后一个逗号可省;key 是任意字符串字面量

reduce 支持的聚合运算符(3.x):

运算符 含义
count 答案总数;带变量时统计该变量的去重值个数
max / min 最大值 / 最小值
mean 算术平均
median 中位数
std 样本标准差
sum 求和
list 把指定变量的取值归约为一个列表

管线位置与组合规则

match → (insert | delete | update | put) → select / require / distinct / sort / offset / limit / reduce → fetch
  • match 可重复出现,reduce 之后还能再接 match 继续补数据(此时只能用聚合变量和 groupby 变量)。
  • select / reduce 都会"丢变量",所以顺序很关键:先 reduce 再 select 想选已被丢弃的变量就会报错/取不到。
  • fetch 必须是最后一段;fetch 内部若需要子查询,用只读管线 + return,而不是 select。

基于 person/employee schema 的四个示例

# 1) match:取员工,输出行里会带上 $p / $n / $e / $id 全部绑定变量
match
  $p isa employee,                 # $p = 实体槽:绑定"一条 employee 实例",类型由 isa employee 确定
    has name $n,                   # $n = 属性槽:绑定 $p 拥有的那个 name 属性实例(值是 string,但 $n 是实例)
    has email $e,                  # $e = 属性槽:绑定 $p 拥有的 email 属性实例
    has employee-id $id;           # $id = 属性槽:绑定 $p 拥有的 employee-id 属性实例

select $n, $e, $id;                # 只保留这三个属性槽,把 $p 从每行里剔掉:行数不变,行变窄

# 2) select:行数不变,但行里只剩 $n、$e($p、$id 被丢弃)
match
  $p isa employee,
    has name $n,
    has email $e,
    has employee-id $id;
select $n, $e;

# 3) reduce:把多行压成一行(总员工数)
match
  $p isa employee;
reduce $employee-count = count;

# 3b) reduce + groupby:每个 name 一组,输出"每组一行"
match
  $p isa person, has name $n;
reduce $people = count groupby $n;

# 4) fetch:输出 JSON 文档(可用 $p.name 按属性类型取值,[$p.email] 表示可多值的列表)
match
  $p isa employee;
fetch {
  "name": $p.name,
  "emails": [$p.email],
  "all-attributes": { $p.* }
};
# 组合用法:match → reduce(groupby) → match → sort → select(行答案)
match
  $p isa employee, has name $n;
reduce $dup = count groupby $n;
match
  $n has name $n;      # 可选:继续用分组变量补数据
sort $dup desc;
select $n, $dup;

常见坑

  1. fetch 不是算子而是终点:写在 fetch 之后任何阶段都会直接报错;反过来 match 作为最后一段是合法的(输出行答案)。
  2. select $x 不等于"只打印 $x":它真的把其他变量从行里删掉,后续阶段无法再引用。
  3. reduce 之后变量会消失:不 groupby 的变量在 reduce 后不复存在,想保留就必须 groupby。
  4. count 的语义差别:reduce $c = count; 数的是"答案行数";reduce $c = count($x); 数的是 $x 的去重取值个数。
  5. fetch 的 key 顺序不保证:输出是文档(等价 JSON),文档键无序,别依赖顺序做断言。
  6. fetch 里取值要区分写法:$x 取变量本身、$x.name 取该实例的某类属性、[$x.email] 是列表(属性基数可大于 1 时必须用列表)、{ ... } 是嵌套文档。

小结

  • 要"查数据" → match
  • 要"少带几个变量" → select
  • 要"统计 / 分组" → reduce
  • 要"给前端/接口的 JSON" → fetch(放最后)

重要语法:TypeDB 查询数据-查询语法: match + label (查询元数据、或检测类型/属性等是否存在)

  • label 是 TypeQL 3.x 的「类型标签(type label)约束」关键字:它匹配的对象是 schema 里的类型定义本身,并不匹配类型下的数据实例。

作用

  • 把类型变量 $t 绑定到「label 恰好等于该字符串」的那个 type(entity、attribute 或 relation 类型)。

因此,它用于 查询元数据或检测类型是否存在,而不是【查询对象数据】。

语法

match $t label obj_vehicle;                       -- 任意类型,label 精确匹配
match entity $t; $t label obj_vehicle; limit 1;    -- 限定根类型为 entity
match $t label obj_vehicle2; $t owns $a; ...        -- 继续对类型加约束

----
match $t label person; # 查询 entity=person 是否存在

match $t label employee; # 查询 entity=eployee 是否存在

match attribute $t; $t label employee-id; limit 1; # 查询 attribute=employee-id 是否存在

image

  • 检查 entity 是否 owns 该 attribute (如: 检查 entity=obj_vehicle2,attribute=vehicle2-brand_name 是否存在)

通常才是真正想确认的

match entity $t; $t label obj_vehicle2; attribute $a; $a label brand_name; $t owns $a; limit 1;

image

要点:

  • label 只能接在类型变量上,其后跟裸标签名(不加引号,也不要写 isa)。
  • 同一个 match 里,标签可以同时与 sub、owns、plays、value 等类型层面的约束组合使用。
  • label 的匹配区分大小写,并且必须是 label 的全名。带路径的 label 不适用,例如 xxx 这类 scoped label 在本项目里不会出现。
  • 如果目标 label 不存在,查询会直接抛 Type label 'xxx' not found,而不会返回空结果;这一点与 isa 不同,isa 匹配不到时只会返回空。

和 isa 的区别

写法 匹配的东西 典型用途
$x isa obj_vehicle2; 类型为 obj_vehicle2 的实例数据 查对象
$t label obj_vehicle2; 类型定义自身 查 schema、判断类型是否存在

label 表示「按名字查类型」,isa 表示「按类型查实例」。

  • 在 TypeDB 2.x 里,等价的写法是 $t type obj_vehicle2;;3.x 将关键字换成了 label。

重要语法:删除 database / schema / 数据

  • 先厘清:TypeDB 里没有独立的 "schema 对象"。 Schema 是附着在 database 上的,所以"删除 schema"分两个层级:
你想删的东西 指令 事务类型 影响范围
schema 中的某个类型 / 能力 / 注解 / 函数 undefine(TypeQL 查询) schema 事务 只改 schema,数据不受影响(但可能因数据不合法而失败)
schema 中的实例数据 delete(管线阶段,需配 match) write 事务 只删数据
整个数据库(schema + 全部数据) Console 服务器级命令 database delete <db> 不是事务,直接对服务器操作 库被整体移除,不可逆
  • 核心答案:删 schema 里的定义用 undefine。

undefine 的语法结构

undefine
  <类型标签>;                              # 删类型(连带其所有能力与注解)
  <接口定义> from <类型标签>;               # 删能力:owns / plays / relates / sub / value
  <@注解> from <类型标签或接口>;            # 删注解(只需注解名,参数可省)
  fun <函数名>;                            # 删函数

约束:schema 语句里不能出现变量和值;语句之间用 ; 分隔;执行后必须 commit 才生效。

具体示例

# 1) 删除整个 employee 类型(连带 sub person、owns employee-id 能力一起消失)
undefine
  employee;

# 2) 一次删多个类型
undefine
  employment;
  employee-id;

# 3) 只删 person 的一个能力,保留 person 类型本身
undefine
  owns email from person;

# 4) 删除角色扮演能力(不再允许 person 担任 employment 的 employee 角色)
undefine
  plays employment:employee from person;

# 5) 删除关系里定义的角色
undefine
  relates employee from employment;

# 6) 删除子类型关系(employee 不再是 person 的子类型)
undefine
  sub person from employee;

# 7) 删除注解(示例:将来若加了 @unique,只需写注解名,参数可省略)
undefine
  @unique from person owns email;

# 8) 删除函数
undefine
  fun some-function;

两条必须注意的限制

  1. 不能删"没有定义"的东西:undefine 一个不存在的定义会直接报错,"An error is returned (on execution or on commit), and no changes are preserved"。
  2. 不能让 schema 变得与数据冲突:如果数据库里还有 employee 实例,undefine employee; 会因为结果 schema 与现有数据不兼容而失败(执行时或提交时)。正确顺序是先删实例数据,再 undefine,或者干脆删库重建。
# 先清数据(write 事务),再 undefine 类型
match
  $p isa employee;
delete
  $p;

如果要连库一起删掉

在 Console 的服务器级(还没进事务的 >> 提示符下):

>> database create employee-sample    # 创建数据库
>> database list                     # 先确认库名,避免删错
>> database delete employee-sample    # 删除整个库:schema 与数据全部消失,不可逆
  • Type DB Studio 里对应的是顶部"数据库"菜单中的删除入口。若你的 Console 版本子命令有差异,在 >> 下输入 help 可查看当前版本 database 子命令的准确清单。

小结

  • 删 schema 的类型/能力/注解/函数 → undefine ...(schema 事务,需 commit)
  • 删 schema 里的数据 → match ... delete ...;(write 事务)
  • 删整个库(含 schema) → Console database delete <db>
  • 顺序铁律:先清数据,再 undefine,否则 schema 与数据不一致会导致失败且不保留任何改动

4 项目应用篇 By Java 客户端

0. 先澄清一个关键概念:TypeDB 没有 JDBC 驱动

TypeDB 官方不提供 JDBC(java.sql.*)驱动,标准接入方式是官方 Java Driver:

  • 传输协议:gRPC(不是 SQL,也不是 HTTP)
  • 查询语言:TypeQL(不是 SQL)
  • 驱动实现:JNI 封装 + gRPC 客户端,com.typedb:typedb-driver

所以「用 JDBC 连 TypeDB」在官方生态里没有现成落点。但心智模型完全可以对照:Driver ↔ Connection、Transaction ↔ Statement、QueryAnswer ↔ ResultSet,只是语法从 SQL 换成 TypeQL。

下面所有内容都按这个映射来组织,方便大家从 JDBC 迁移。

flowchart TD A[你的 Java 应用] --> B[Driver 单例<br/>TypeDB.driver] B --> C[Driver.transaction 开事务] C --> D[READ 只读查询] C --> E[WRITE 数据写<br/>insert/delete/update] C --> F[SCHEMA 结构写<br/>define/undefine] D & E & F --> G[tx.commit 提交] G --> H[tx.close 释放] B --> I[driver.databases 数据库管理] B --> J[driver.serverVersion 健康检查]

1. Maven 依赖与版本

  • 官方坐标:
<!-- TypeDB 官方 Java Driver(gRPC + JNI 原生层) -->
<dependency>
    <groupId>com.typedb</groupId>
    <artifactId>typedb-driver</artifactId>
    <version>3.14.0</version>
</dependency>
  • 3.x 版本驱动自带 JNI 原生层(typedb-driver-clib-<platform>)。若在 Windows 下启动报 UnsatisfiedLinkError,需在依赖里补对应平台的原生包,例如:

    <dependency>
        <groupId>com.typedb</groupId>
        <artifactId>typedb-driver-clib-windows-x86_64</artifactId>
        <version>3.14.0</version>
    </dependency>
    

2. 与 JDBC 的核心 API 对照

JDBC 概念 TypeDB Java Driver 对应 说明
DriverManager.getConnection(url, user, pwd) TypeDB.driver(address, credentials, options) 创建 Driver 单例(进程内复用,勿重复创建)
Connection Driver 连接管理,且管事务/数据库
Connection.createStatement() driver.transaction(database, type) 每次查询都要开事务
Statement.executeXxx(sql) tx.query(typeql)(异步 Promise) 执行一条 TypeQL
ResultSet QueryAnswer(ConceptRowIterator / ConceptDocumentIterator / OkQueryAnswer) 查询结果
conn.commit() / conn.close() tx.commit() / tx.close() 事务提交与释放
PreparedStatement 参数绑定 TypeQL ?name 命名占位符 3.x 支持查询串内参数
连接池 无内置;Driver 本身可复用,事务短开短关 每事务一开一关

最大差异:JDBC 是一条连接复用于多条语句;TypeDB 是每条语句开一个事务。TypeDB 的事务(Transaction)是数据访问的原子单位。


3. 事务类型(Transaction.Type)

对应 JDBC 里「自动提交 / 手动提交」+ DDL/DML 的划分,TypeDB 把事务分为三类:

Transaction.Type 用途 对应 TypeQL JDBC 类比
READ 只读查询 match / fetch / reduce SELECT(只读连接)
WRITE 数据增删改 insert / delete / update INSERT / UPDATE / DELETE(读写事务)
SCHEMA 结构定义/删除 define / undefine DDL(CREATE / DROP / ALTER)
// 读
Transaction readTx = driver.transaction("mydb", Transaction.Type.READ);
// 写
Transaction writeTx = driver.transaction("mydb", Transaction.Type.WRITE);
// 结构
Transaction schemaTx = driver.transaction("mydb", Transaction.Type.SCHEMA);

4. 配置与自动装配

4.1 配置项

配置(typedb.*) 默认 说明
enabled true 是否启用 TypeDB 客户端
address 必填 单节点 gRPC 地址,如 192.168.11.111:1729(不要带 http://)
addresses 空 集群多地址,英文逗号分隔;优先于 address
username / password 必填 认证凭据
tls.enabled false 生产建议 true
tls.root-ca-path 空 自定义根 CA(PEM);不填则用系统原生根证书
request-timeout-millis 60000 一元 RPC 超时(建库、开事务等),不影响事务内查询
transaction-timeout-millis 空 事务超时;被 schema 写锁阻塞时超过则放弃
primary-failover-retries 空 集群主节点故障转移重试次数
default-database 空 默认数据库名

对应 Java 类:com.xxx.common.typedb.config.TypeDbProperties(前缀 typedb)。

4.2 自动装配

xxx-common-typedb 通过 Spring Boot 自动装配,只要 classpath 里引入该模块并满足条件即自动注入 TypeDbClient Bean:

@AutoConfiguration
@ConditionalOnProperty(prefix = "typedb", name = "enabled", havingValue = "true", matchIfMissing = true)
@ConditionalOnProperty(prefix = "typedb", name = "address")   // 必须有 address 才装配
@EnableConfigurationProperties(TypeDbProperties.class)
public class TypeDbAutoConfiguration {
    @Bean(destroyMethod = "close")
    @ConditionalOnMissingBean(TypeDbClient.class)
    public TypeDbClient typeDbClient(TypeDbProperties properties) {
        return new TypeDbDriverClient(properties);
    }
}

注册文件:src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
内容:com.xxx.common.typedb.config.TypeDbAutoConfiguration

业务代码里直接注入即可用:

@Component
public class MyService {
    @Autowired(required = false)   // 未配置 TypeDB 时降级,不阻塞启动
    private TypeDbClient typeDbClient;
}

实际配置通常在 Nacos(application-common.yml 或 ${appName}.yml),本地 application.yml 只做 import。


5. 客户端封装接口(xxx-common-typedb 的 TypeDbClient)

xxx 把官方驱动封装成了面向业务的一组方法,这是你在项目里实际使用的主体:

分类 方法 说明
健康/服务 health() / getVersion() 连通性探测、取服务版本
数据库管理 listDatabases() / databaseExists(name) / createDatabase(name) / dropDatabase(name) 对应官方 driver.databases()
Schema defineSchema(db, typeql) / undefineSchema(db, typeql) 走 SCHEMA 事务
数据写 insert(db, typeql) / delete(db, typeql) / update(db, typeql) 走 WRITE 事务
数据查 match(db, typeql) / fetch(db, typeql) / matchWithParams(db, typeql, params) / execute(db, typeql) 查询
高级 rawDriver() 暴露官方 Driver,供 analyze 等高级操作(自行管事务)

关键实现(TypeDbDriverClient)几个值得记住的细节:

  • 每条语句:开事务 → 执行 → commit → finally close,写语句必须 commit()。
  • execute() 自动按语句头关键字路由:define/undefine → SCHEMA,insert/delete/update → WRITE,否则按查询处理。
  • 结果统一转成 QueryResult:Match 得到 rows(List<Map<String,Object>>),Fetch 得到 answers(JSON 文档)。
  • 对「类型不存在」类异常做幂等降级,避免全量重建时误报。

6. 数据库管理

TypeDB 一个 database(库) 即一个独立命名空间,schema 与数据都在库内。xxx 约定一个本体对应一个库(ont_xxx,见 TypeDbProjectResolver)。

// 判断/创建/删除
boolean exists = typeDbClient.databaseExists("ont_user");
typeDbClient.createDatabase("ont_user");
typeDbClient.dropDatabase("ont_user");

// 列出
List<TypeDbDatabase> dbs = typeDbClient.listDatabases();

7. TypeQL 速成(与 SQL 对照)

TypeDB 3.x 是「类型优先」的强类型图数据库:先 define 类型(entity/attribute/relation),再 insert 实例,用 match 查询。

7.1 Schema 定义:define(SCHEMA 事务)

define
    entity obj_user,
        owns obj_user-name @key,
        owns obj_user-age;
    attribute obj_user-name, value string;
    attribute obj_user-age, value long;
    relation obj_user-orders-obj_order,
        relates obj_user,
        relates obj_order;

要点:

  • 3.x 用 kind 关键字(entity X / attribute X / relation X),不再写 sub entity 这类旧语法。
  • owns ... @key 声明业务主键(唯一约束)。
  • attribute 在同一库内全局唯一,不同对象共用同名属性要加【对象前缀】避免冲突(xxx 用 对象码-属性码 命名,见下)。
  • relation 用 relates 角色 定义角色,entity 用 plays 关系:角色 声明参与关系。
SQL TypeQL
CREATE TABLE user(id INT PRIMARY KEY, name VARCHAR) define entity obj_user, owns obj_user-id @key, owns obj_user-name; attribute obj_user-id, value long; ...
ALTER TABLE ... ADD COLUMN define attribute obj_user-email, value string; define entity obj_user owns obj_user-email;
DROP TABLE user undefine obj_user;

7.2 写入:insert(WRITE 事务)

insert
  $u isa obj_user,
    has obj_user-id 1001,
    has obj_user-name "张三";

对应 SQL:INSERT INTO obj_user (id, name) VALUES (1001, '张三');

注意【字符串】字面量用双引号,内部反斜杠/双引号需转义(xxx 用 TypeDbNaming.escapeValue)。

7.3 查询:match / fetch(READ 事务)

# 行式结果(match + 绑定变量)
match $u isa obj_user, has obj_user-name $name; 

# JSON 文档结果(fetch)
match $u isa obj_user, has obj_user-id 1001; fetch { "user": $u };

# 聚合计数
match $u isa obj_user; reduce $c = count;

对应 SQL:SELECT ... FROM obj_user WHERE ...;、SELECT COUNT(*) FROM obj_user;

7.4 删除:delete(WRITE 事务)

match $u isa obj_user, has obj_user-id 1001; delete $u;

7.5 关系建立(图的核心)

match
  $s isa obj_user, has obj_user-id 1001;
  $t isa obj_order, has obj_order-id 9001;
insert
  (obj_user: $s, obj_order: $t) isa obj_user-orders-obj_order;

8. 常见坑与最佳实践(踩过坑后的总结)

# 坑 / 注意点 解法
1 每语句开事务,忘 commit 数据丢失 / 忘 close 连接泄漏 写语句必须 tx.commit();用 try/finally 保证 close()(参考 TypeDbDriverClient.closeQuietly)
2 Driver 必须单例复用 TypeDB.driver(...) 只创建一次,容器销毁时 close()(@Bean(destroyMethod="close"))
3 重复 define 报错 幂等处理:识别「already exists / redefinition」异常后跳过
4 undefine/删除不存在的类型报错 识别「not found / does not exist / unknown type」异常后跳过
5 有实例时无法 undefine 类型 先删实例(带 limit 分批),再 undefine 类型
6 字符串字面量注入 所有用户输入经 escapeValue 转义;标识符走 TypeDbNaming.normalize
7 attribute 全局唯一 跨对象共用属性名要加前缀(xxx:对象码-属性码)
8 保留字冲突(role、type 等) entity/role 名加 obj_ 前缀
9 TypeDB 3.x 语法 用 kind 声明(entity X),@key 主键;不要写旧 sub entity
10 Windows JNI 报错 启动报 UnsatisfiedLinkError 时补 typedb-driver-clib-windows-x86_64 依赖
11 查询结果类型 match→rows(行式)、fetch→answers(JSON 文档)、写入→ok;用 reduce ... count 做计数
12 未配置降级 客户端用 @Autowired(required=false),未配 TypeDB 时业务降级而非启动失败
13 事务超时 被 schema 写锁阻塞可设 transaction-timeout-millis 放弃,避免卡死
14 Server地址 gRPC 默认端口 1729,不要带 http:// 前缀

9. 总结

  • TypeDB 用官方 Java Driver(gRPC + TypeQL)接入,不是 JDBC。

  • 把「Driver 单例 → 每语句开事务(READ/WRITE/SCHEMA) → TypeQL → commit → close」这条链路吃透,再记住 3.x 的 kind 语法、@key 主键、match/fetch/reduce 查询,以及 xxx 的命名归一化与幂等清理套路,就能在自己的模块里快速落地。

Z FAQ for TypeDB 部署使用

Q: TypeDB 的默认账号密码?TypeDB Studio 如何连接?

image

  • TypeDB 3.x 的默认账号是 admin,默认密码是 password;但如果你用的是 TypeDB 2.x Core,默认根本不开认证,TypeDB Studio 里用户名/密码留空就能连。

下面按版本分清楚。

默认凭据(按版本区分)

版本 默认是否要求认证 Studio 用户名 密码
TypeDB 3.x 是(内置强制认证) admin password
TypeDB 2.x Core 否(默认关闭) 留空 留空
TypeDB Cloud / Enterprise(2.x) 是 你在云端控制台创建的用户 你设置的密码

默认凭据(按版本区分)

版本 默认是否要求认证 Studio 用户名 密码
TypeDB 3.x 是(内置强制认证) admin password
TypeDB 2.x Core 否(默认关闭) 留空 留空
TypeDB Cloud / Enterprise(2.x) 是 你在云端控制台创建的用户 你设置的密码

3.x 的 admin/password 是在服务器首次初始化时自动创建的,官方文档和各语言驱动示例(Python/Rust/Java/npm 的 typedb-driver)默认值都是这个。

一般在哪里设置 / 修改

分两层面说:

1. 连接时填写的位置(Studio 对话框)
Studio 的「New Connection」对话框里有 Hostname、Port、Username、Password、TLS 几个字段,凭据就在这里逐次输入,Studio 本身不会把这些凭据写进某个可编辑的【全局配置文件】,而是每次连接时填一次。

2. 账号密码的真正来源(服务端)

  • TypeDB 3.x:admin 用户是初始化时生成的,密码不以明文形式存在某个配置文件里(你没法靠改一个 .yml 来设密码),而是由服务端存成哈希、放在【服务端数据目录】中。

要修改密码/新建用户,需要用 TypeDB console 或驱动的 users 接口执行【用户管理命令】(如 user create、user password、user update)。

  • TypeDB 2.x Core:服务端没有内置用户体系,所以 Studio 那两个框留空即可;只有开了认证或连云端才需要填。

现在该怎么判断

先确认装的是哪个版本——这直接决定填不填、填什么:

  • 若是 2.x Core(最常见通过 Studio 连的本地版):用户名/密码留空,TLS 不勾,直接连。
  • 若是 3.x:填 admin / password。
  • 若填了 admin/password 仍报认证失败,多半是密码已被改过(别人改的,或初始化时自定义了),需要找当初设置的人或重设。

Q: typedb 中查询指定属性的 entity 是否存在。语法是怎样的?

查询方法x3

  • 方法1)判断是否存在(推荐,用 limit 1 最经济)
match
  $v isa obj_vehicle2, has vehicle2-vin "LSGKB52H0V2PRXEZW";
limit 1;

返回 0 行表示不存在,返回 1 行(如: iid 0x1e00060000000000000000)表示存在。

  • 方法2)一条语句直接给出计数(结果确定,不用看行数)
match
  $v isa obj_vehicle2, has vehicle2-vin "LSGKB52H0V2PRXEZW";
reduce $c = count;

$c = 0 表示不存在,$c = 1 表示存在(真实项目里 COUNT 查询就是这种写法)。

  • 方法3)把约束拆成两条语句(与第 1 种等价,便于拼接过滤条件)
match
  $v isa obj_vehicle;
  $v has vehicle-vin "LSGKB52HWFYEE0EJ2";
limit 1;

返回 0 行表示不存在,返回 1 行(如: iid 0x1e00060000000000000000)表示存在。

容易踩的坑

  • 字面量只用双引号:TypeQL 不支持单引号,'LSGK...' 是语法错误。
  • 【数值主键】不能加引号: 例如 vin 是 String,加引号正确;若换成 BIGINT 主键,has ... 123 才对,"123" 恒不命中。
  • 不加 limit 1 会把所有命中行拉回来,【单次读】还有结果条数上限;做存在性判断一律带 limit 1 更稳。

Y 推荐文献

X 参考文献

posted @ 2026-10-30 18:00  千千寰宇  阅读(2)  评论(0)    收藏  举报