CozoScript 之外

Cozo 数据库中的大多数功能都皆由 CozoScript API 使用。但由于 CozoScript API 必须返回固定的格式，一些功能并不适合这种表达方式。还有另一些功能虽然可以如此表达，但是其作用与一般的查询关系不大。这些功能都必须经由单独的 API 访问。

在不同的语言环境中，调用这些 API 的方式略有差异，具体请参考每个语言实现自己的文档。以下我们简述每个 API 的基本作用（下例中使用的是 Python API 的格式）。

export_relations(self, relations)

导出一个或多个存储表。数据统一性：一次性所有导出的表都仅含有同一快照中的数据。

参数:

relations – 含有需要导出的表的名称的数组。

返回:

一个字典，键为表名，值为表中所有数据。

import_relations(self, data)

导入数据。导入在一个事务中执行，所以要么所有的导入数据都成功写入，要么任何数据都不被写入。若导入时其他进程（导入或查询）造成了被导入的数据冲突，则报错，导入失败。

导入的存储表必须已经存在于数据库中，且导入的数据必须满足存储表声明的列结构。

这个 API 不但可以用来插入数据，也可以用来删除数据。删除数据时，在存储表的前面加负号，比如删除 "rel_a" 中的数据，则使用 "-rel_a" 作为表名。插入数据时不管当前表中有无当前键，都不报错，而执行覆盖。删除数据时，即使当前表中不含当前键，也不报错。删除数据时只需要给出键，不需要值。

警告

此 API 不会激活触发器。

参数:

data – 一个字典，键为表名，值与 export_relations 返回的表内容相同，例如： {"rel_a": {"headers": ["x", "y"], "rows": [[1, 2], [3, 4]]}, "rel_b": {"headers": ["z"], "rows": []}} 。

backup(self, path)

备份数据库至指定路径。备份的数据保证是满足一致性的数据快照。

这个 API 对所有数据进行备份：你无法选择性的备份指定的表。另外，这个 API 比 export_relations 效率高，同时用的资源也更少。

此 API 仅在编译时打开了 storage-sqlite 功能的情况下才可用。除了浏览器 WASM 之外的所有预编译发布都打开了此功能。备份文件实际上就是一个完整的 SQLite 存储引擎的文件，因此可以直接打开查询。若要长期储存，建议将此文件压缩。

参数:

path – 备份路径。若远程操作数据库，则此为远程机器上的路径。

restore(self, path)

从备份中恢复数据至当前空数据库。

此 API 恢复所有数据：你无法选择性的只恢复指定的表。

参数:

path – 备份路径。远程操作数据库时此 API 无法使用。

import_from_backup(self, path, relations)

从备份中抽取表中数据并写入当前数据库中的同名表。

从语义上来说，此 API 与 import_relations 类似，不同点在于数据来源于备份而不是直接传入，且此 API 无法删除数据。另外此 API 占用资源也比 import_relations 小。

警告

此 API 不会激活任何触发器。

参数:

• path – 备份路径。若远程操作数据库，则此为远程机器上的路径。

• relations – 存储表名称组成的数组。这些存储表必须预先存在于当前数据库中。

回调

Cozo 支持对指定的存储表设置回调函数以在表被更改时获取更新。目前此功能仅可在 Rust、Python 及 NodeJS 库，以及独立的可运行程序中使用。具体使用方法请参阅它们自己的安装使用文档。