企业官网建设流程全解析

• 图数据库
• 数据库
• 后端

导读

Linked Data（关联数据）存在多种序列化表示，JSON-LD、N-Quads、P-Quads 等格式各有适用场景。Cayley 的 CLI 内置了convert（别名conv）子命令，用于在各类四元组（quad）文件格式之间进行转换。本文基于 docs/tools/convert-linked-data-files.md 展开，结合仓库源码讲解-i/-o参数的用法、基于扩展名的自动格式检测、--load_format与--dump_format的显式指定方式，以及 P-Quads 二进制格式在导入加速和数据库迁移中的实战价值。读完本文，你将掌握用一条命令完成任意受支持格式之间转换的能力。

为什么需要转换 Linked Data 文件

Cayley 的核心数据模型是四元组（quad）：subject – predicate – object – label。同样的语义可以用不同语法表示：

• JSON-LD：基于 JSON 的 RDF 序列化格式，适合 Web 场景与 JavaScript 生态；
• N-Quads：每行一条四元组的纯文本行式格式，便于 grep、diff 与流式处理；
• P-Quads：Cayley 内部使用的二进制格式，解析开销小、压缩率更好。

从源码看，当前版本通过 cmd/cayley/cayley.go 的匿名导入注册了以下格式支持：

也就是说，convert子命令实际可用的格式集合由这些注册的读写器决定（详见下文"支持的格式"一节）。

基本用法：从一个格式转换到另一个格式

最简单的转换命令如下：

$ cayley convert -i data.jsonld -o data.nquads

• -i指定要转换的输入文件。本例中是一个名为data.jsonld的 JSON-LD 文件。
• -o指定要创建的目标文件及其目标格式。本例中是名为data.nquads的 N-Quads 文件。

命令执行成功后，会在终端输出类似writing quads to file "data.nquads"与N entries were written的进度信息（来自 cmd/cayley/command/dump.go），其中N为写入的四元组条数。

别名conv

在 cmd/cayley/command/convert.go 中，convert命令声明了别名conv：

Use: "convert", Aliases: []string{"conv"},

因此下面两条命令完全等价，日常使用中后者更省事：

$ cayley conv -i data.jsonld -o data.nquads $ cayley convert -i data.jsonld -o data.nquads

位置参数形式

convert也支持把输入文件作为位置参数传入。从 convert.go 的实现看，若未提供-o，命令会把最后一个位置参数当作输出文件，其余参数视为输入文件；若输入、输出任一缺失，会报错both input and output files must be specified。例如：

$ cayley convert data.jsonld data.nquads

等价于-i data.jsonld -o data.nquads的效果。

自动格式检测与显式指定格式

基于文件扩展名的自动检测

输入与输出文件的格式默认根据文件扩展名自动检测：

• 输入侧：读取文件时先剥离.gz/.bz2压缩后缀，再用剩余扩展名匹配格式（见 internal/load.go）；
• 输出侧：根据输出路径的扩展名匹配格式（见 cmd/cayley/command/dump.go）。

因此把目标文件名后缀改为.nquads、.jsonld、.pq等，即可控制输出格式，无需额外参数。

使用--load_format与--dump_format显式指定

在扩展名无法表达（例如输出文件没有扩展名）或需要强制使用某种格式时，可用以下两个参数：

• --load_format：指定输入格式，替代自动检测；
• --dump_format：指定输出格式，替代自动检测。

原文档给出的示例（注意原文中convet是笔误，正确命令为convert）：

$ cayley convert -i data.jsonld -o data --dump_format pquads

这里-o data的输出文件没有扩展名，因此必须用--dump_format pquads显式告知输出格式为P-Quads——一种 Cayley 内部使用的二进制格式。

两个 flag 的实际定义位于 cmd/cayley/command/database.go：registerLoadFlags注册--load_format（列出所有带 Reader 的格式名），registerDumpFlags注册--dump_format（列出所有带 Writer 的格式名），而-i与-o分别是--load与--dump的短参数。convert命令通过registerLoadFlags(cmd)与registerDumpFlags(cmd)复用了同一套 flag 定义（见 convert.go），所以这些参数的行为与load、dump子命令完全一致。

源码视角：一次转换的完整调用链

多输入文件合并读取

convert的实现（cmd/cayley/command/convert.go）值得注意的一个特性是：它支持一次转换多个输入文件，内部用multiReader将多个惰性打开的 reader 串成单个 quad 流，按顺序读取完毕后自动关闭：

var multi multiReader for _, path := range files { multi.rc = append(multi.rc, newLazyReader(func() (quad.ReadCloser, error) { return internal.QuadReaderFor(path, loadf) })) } return writerQuadsTo(dump, dumpf, &multi)

例如把多个分片数据合并输出为一个文件：

$ cayley convert part1.nq part2.nq all.nquads

输入读取：QuadReaderFor

每个输入文件都会交给 internal/load.go 的QuadReaderFor，它依次处理：

1. 路径形态：-表示标准输入（stdin）；file://或普通路径打开本地文件；其他带 scheme 的 URL 则通过http.Get拉取远程资源；
2. 压缩解压：经decompressor.New处理.gz/.bz2压缩流；
3. 格式选择：未指定--load_format时按扩展名探测；扩展名未知时回退为nquads；cquad/nquad作为 legacy 名称映射到 nquads 读取器；若该格式没有 Reader，则报decoding of "<格式>" is not supported。

这意味着你可以直接转换远程文件或压缩文件，例如：

$ cayley convert -i https://example.com/data.jsonld -o data.nquads $ cayley convert -i data.nq.gz -o data.jsonld

输出写入：writerQuadsTo

输出侧由 cmd/cayley/command/dump.go 的writerQuadsTo负责：

1. 输出路径为-时写入stdout（便于管道接力）；
2. 输出路径以.gz结尾时自动套用 gzip 压缩（先剥离一层扩展名再探测格式）；
3. 未指定--dump_format时按扩展名探测；扩展名未知时回退为nquads；指定了格式但该格式没有 Writer 时，报encoding in <格式> format is not supported；
4. 通过quad.Copy逐条搬运四元组，最后打印写入的条目总数。

因此将压缩文件转为另一种格式、或将结果直接通过管道输出，都是受支持的用法：

$ cayley convert -i data.jsonld -o data.nq.gz $ cayley convert -i data.nquads -o - | head

实战场景：把转换用在数据导入与迁移中

场景一：转换为 P-Quads 加速批量导入

对于打算反复导入多个后端的大型数据集，官方建议先转换为 Cayley 专用二进制格式。这一点在 docs/usage/advanced-use.md 中有明确说明：

./cayley conv -i dataset.nq.gz -o dataset.pq.gz

该做法"将最小化后续导入时的解析开销，并使数据集的压缩效果更好"——P-Quads 正是前文提到的--dump_format pquads对应的二进制格式。

场景二：数据库迁移与后端切换

在跨版本或跨后端迁移时，同样依赖 pquads 中间文件。参考 docs/migration.md，先 dump 再 load：

./cayley dump -d <backend> -a <address> -o ./data.pq.gz ./cayley load --init -d <new-backend> -a <new-address> -i ./data.pq.gz

若希望中间文件是标准文本格式，也可以改用 nquads（注意.nq扩展名）：

./cayley dump -c <config> -o ./data.nq.gz ./cayley load --init -c <new-config> -i ./data.nq.gz

场景三：HTTP 服务上的格式转换

如果 Cayley 服务已通过 HTTP 启动，还可以使用两个独立小工具完成与convert互补的转换：cayleyimport（读取本地文件或 stdin，POST 到/api/v2/write）与cayleyexport（GET/api/v2/read并落盘），二者默认格式均为 JSON-LD，扩展名未知时回退到 JSON-LD，可通过--format显式指定。实现见 cmd/cayleyimport/cayleyimport.go 与 cmd/cayleyexport/cayleyexport.go。与convert的纯文件转换不同，这两个工具走 HTTP API，适合已有运行中实例的场景。

支持的格式与常见问题

常见问题一：输出扩展名无法识别

当输出文件扩展名不在已注册格式之列时，writerQuadsTo会静默回退为nquads文本格式（见 dump.go）。因此若想输出非默认格式，务必使用规范的扩展名（如.pq、.jsonld）或显式--dump_format。

常见问题二：输入格式不受支持

输入侧同理，QuadReaderFor在扩展名未知时回退 nquads；若显式指定的格式没有对应 Reader，则直接报错终止。可用的格式名可以通过cayley convert --help查看--load_format/--dump_format的候选项（源码中会按字母序列出所有具备 Reader/Writer 的格式名，见 database.go）。

常见问题三：输入输出必须同时存在

正如前文所述，convert要求输入文件与输出文件都非空，否则报错both input and output files must be specified。这与load（导入数据库）和dump（导出数据库）不同——后者面向的是数据库实例而非文件对。

总结

Cayley 的convert（conv）子命令以四元组流为核心，串联起输入读取（本地文件 / stdin / URL、自动解压、扩展名探测）、格式转换与输出写入（文件 / stdout、自动 gzip、格式回退）三个环节。日常使用记住两条即可：默认按扩展名自动判断格式，特殊场景用--load_format/--dump_format显式指定。把大型数据集先转成.pq.gz再导入，是官方推荐的提速手段；而在跨后端迁移时，dump+load配合 pquads 中间文件则是最稳妥的数据搬运路径。

• 图数据库
• 数据库
• 后端