Apache Arrow 投影

通过 Apache Arrow 投影图允许导入存储在 Neo4j 之外的图数据。Apache Arrow 是一种语言无关的内存列式数据结构规范。通过 Arrow Flight，它还包含用于序列化和通用数据传输的协议。

GDS 公开了一个 Arrow Flight 服务器，该服务器接受来自 Arrow Flight 客户端的图数据。发送的数据使用 Arrow 列式格式表示。通过 Arrow Flight 投影图遵循特定的客户端-服务器协议。在本章中，我们将解释该协议、消息格式和模式约束。

在本章中，我们假设 Flight 服务器已设置并配置。要了解有关安装的更多信息，请参阅安装章节。

图投影功能是版本化的，以允许未来的更改。有关版本化命令的更多详细信息，请参阅配置 Apache Arrow 服务器文档中的相应部分。

客户端-服务器协议

该协议描述了将单个内存图投影到 GDS 中。每个投影都表示为服务器端的导入过程。该协议将导入过程分为三个阶段。

初始化导入过程

要初始化导入过程，客户端需要在服务器上执行 Flight 操作。操作类型为 CREATE_GRAPH，操作体配置导入过程。服务器接收操作，创建导入过程并确认成功。

有关更多详细信息，请参阅初始化导入过程。
通过 Arrow Flight 流发送节点记录

在第二阶段，客户端通过 PUT 作为 Flight 流发送节点记录批次。一旦所有记录批次都已发送，客户端需要指示所有节点都已发送。这通过发送另一个类型为 NODE_LOAD_DONE 的 Flight 操作来完成。

有关更多详细信息，请参阅通过 PUT 作为 Flight 流发送节点记录。
通过 Arrow Flight 流发送关系记录

在第三阶段也是最后阶段，客户端通过 PUT 作为 Flight 流发送关系记录批次。一旦所有记录批次都已发送，客户端需要指示导入过程已完成。这通过发送另一个类型为 RELATIONSHIP_LOAD_DONE 的 Flight 操作来完成。服务器完成内存图的构建并将图存储在图目录中。

有关更多详细信息，请参阅通过 PUT 作为 Flight 流发送关系记录。

初始化导入过程

通过使用操作类型 v1/CREATE_GRAPH 发送 Flight 操作来初始化导入过程。操作类型包含服务器版本，当前版本为 1 (v1)。操作体是一个包含导入过程元数据的 JSON 文档

{
    name: "my_graph", (1)
    database_name: "neo4j", (2)
    concurrency: 4, (3)
    undirected_relationship_types: [] (4)
    inverse_indexed_relationship_types: [] (5)
    skip_dangling_relationships: false (6)
}

1	用于标识导入过程。它也是图目录中生成的内存图的名称。
2	投影图将可用的数据库名称。
3	（可选）在收到所有数据后，将在内存图中设置的并发级别。
4	（可选）必须作为无向导入的关系类型列表。可以使用通配符 (`*`) 来包含所有类型。
5	（可选）必须以反向索引的关系类型列表。可以使用通配符 (`*`) 来包含所有类型。
6	（可选）如果设置为 `true`，在导入过程中将跳过悬空关系。否则，如果检测到悬空关系，导入过程将失败。

声明为无向关系应只提供一次，即单向提供。

服务器通过发送包含导入过程名称的结果 JSON 文档来确认创建导入过程。如果发生错误，例如图已存在或服务器未启动，客户端将相应地收到通知。

通过 PUT 作为 Flight 流发送节点记录

节点需要转换为 Arrow 记录批次并通过 Flight 流发送到服务器。每个流都需要针对服务器上的导入过程。该信息以 JSON 文档形式编码在 Flight 描述符主体中

{
    name: "PUT_COMMAND",
    version: "v1",
    body: {
        name: "my_graph",
        entity_type: "node",
    }
}

服务器期望节点记录遵循特定模式。给定一个示例节点，例如 (:Pokemon { weight: 8.5, height: 0.6, hp: 39 })，其记录必须表示如下

nodeId	labels	weight	height	hp
0	"Pokemon"	8.5	0.6	39

nodeId

labels

weight

height

"Pokemon"

8.5

0.6

下表描述了具有保留名称的节点列。

名称类型可选可为空描述

名称	类型	可选	可为空	描述
`nodeId`	整数	否	否	内存图中唯一的 64 位节点标识符。必须是正值。
`labels`	字符串或整数或字符串列表	是	否	节点标签，可以是单个字符串节点标签、单个字典编码节点标签或节点标签字符串列表。

nodeId

整数

否

内存图中唯一的 64 位节点标识符。必须是正值。

labels

字符串或整数或字符串列表

是

否

节点标签，可以是单个字符串节点标签、单个字典编码节点标签或节点标签字符串列表。

任何附加列都被解释为节点属性。支持的数据类型等同于 GDS 节点属性类型，即 long、double、long[]、double[] 和 float[]。

对于浮点值，null 将转换为 NaN。

为了提高吞吐量，可以并行发送多个 Flight 流。服务器管理同一导入过程的多个传入流。除了并行流的数量，单个记录批次的大小也会影响整体吞吐量。客户端必须确保节点 ID 在所有流中都是唯一的。

发送重复的节点 ID 将导致未定义的行为。

一旦所有节点记录批次都发送到服务器，客户端需要指示节点加载已完成。这通过发送另一个操作类型为 v1/NODE_LOAD_DONE 的 Flight 操作和以下 JSON 文档作为操作体来实现

{
    name: "my_graph"
}

服务器通过返回一个 JSON 文档来确认操作，该文档包含导入过程的名称和已导入节点的数量

{
    name: "my_graph",
    node_count: 42
}

导入具有通用标签的节点

如果对 PUT 端点的单次调用中的所有节点都共享相同的标签，则可以通过 common_labels 属性将这些标签指定为导入过程元数据的一部分

{
    name: "PUT_COMMAND",
    version: "v1",
    body: {
        name: "my_graph",
        entity_type: "node",
        common_labels: ["Pokemon"]
    }
}

如果通用标签是流中唯一存在的标签，则可以从节点记录批次中省略 labels 列。如果存在具有比通用标签更多标签的节点，则仍然可以包含一个包含附加标签的 labels 列。

通过 PUT 作为 Flight 流发送关系记录

与节点类似，关系需要转换为记录批次才能通过 Flight 流发送到服务器。Flight 描述符是一个 JSON 文档，包含导入过程的名称和实体类型

{
    name: "PUT_COMMAND",
    version: "v1",
    body: {
        name: "my_graph",
        entity_type: "relationship",
    }
}

对于节点，服务器期望关系记录的特定模式。例如，给定关系 (a)-[:EVOLVES_TO { at_level: 16 }]→(b)，并假设节点 ID a 为 0，节点 ID b 为 1，记录必须表示如下

sourceNodeId	targetNodeId	type	at_level
0	1	"EVOLVES_TO"	16

sourceNodeId

targetNodeId

type

at_level

"EVOLVES_TO"

下表描述了具有保留名称的节点列。

名称类型可选可为空描述

名称	类型	可选	可为空	描述
`sourceNodeId`	整数	否	否	唯一的 64 位源节点标识符。必须是正值并存在于导入的节点中。
`targetNodeId`	整数	否	否	唯一的 64 位目标节点标识符。必须是正值并存在于导入的节点中。
`relationshipType`	字符串或整数	是	否	单一关系类型。可以是字符串字面量或字典编码的数字。

sourceNodeId

整数

否

唯一的 64 位源节点标识符。必须是正值并存在于导入的节点中。

targetNodeId

整数

否

唯一的 64 位目标节点标识符。必须是正值并存在于导入的节点中。

relationshipType

字符串或整数

是

否

单一关系类型。可以是字符串字面量或字典编码的数字。

任何附加列都被解释为关系属性。GDS 仅支持 double 类型的关系属性。

类似于发送节点，整体吞吐量取决于并行 Flight 流的数量和记录批次的大小。

一旦所有关系记录批次都发送到服务器，客户端需要指示导入过程已完成。这通过发送最后一个操作类型为 v1/RELATIONSHIP_LOAD_DONE 的 Flight 操作和以下 JSON 文档作为操作体来实现

{
    name: "my_graph"
}

服务器完成图投影并将内存图存储在图目录中。完成后，服务器通过返回一个 JSON 文档来确认操作，该文档包含导入过程的名称和已导入关系的数量

{
    name: "my_graph",
    relationship_count: 1337
}

中止导入过程

可以通过使用操作类型 v1/ABORT 发送 Flight 操作来中止已启动的导入过程。这将立即取消正在运行的图或数据库导入过程并删除所有临时数据。

操作体是一个 JSON 文档，包含正在导入的图或数据库的名称

{
    name: "my_graph",
}

如果在可配置的超时时间内未收到数据或指令，Arrow 导入过程将自动中止。超时可以通过 gds.arrow.abortion_timeout 设置进行配置，更多信息请参阅安装章节。

向现有图追加新数据

一旦创建了图，就可以向现有图追加额外数据。这避免了删除图并重新导入所有数据。该过程与初始导入过程类似，但有一些不同之处。

追加新节点属性

一旦创建了图，就可以向现有图追加额外的节点属性。为此，客户端需要发送与现有节点具有相同节点 ID 的节点记录。服务器将使用新属性更新现有节点，可能仅限于一组节点标签。节点记录由 nodeId 列标识，该列在所有节点记录中必须唯一，并且必须与现有节点的节点 ID 匹配。

无需为现有图中的所有节点发送节点属性值。如果新数据中未表示节点记录，则该记录将接收属性类型的默认值。

如果属性已存在或提供的节点 ID 之一与现有节点不匹配，则该过程将失败。

导入过程通过使用操作类型 v1/PUT_NODE_PROPERTIES 并使用以下 JSON 文档作为操作体来初始化

{
    name: "my_graph", (1)
    database_name: "neo4j", (2)
    concurrency: 4, (3)
    node_labels: ["*"], (4)
    consecutive_ids: false (5)
}

1	现有内存图的名称。它也用于标识导入过程。
2	投影图可用的数据库名称。
3	（可选）用于在服务器上构建属性数据结构的并发级别。
4	（可选）将使用新属性更新的节点标签集。可以使用通配符 (`*`) 来包含所有标签。
5	（可选）如果数据与已使用连续节点 ID 导出的图关联，则将其设置为 `true`。

节点属性需要转换为 Arrow 记录批次并通过 Flight 流发送到服务器。每个流都需要针对服务器上的导入过程。该信息以 JSON 文档形式编码在 Flight 描述符主体中

{
    name: "PUT_COMMAND",
    version: "v1",
    body: {
        name: "my_graph",
        entity_type: "node_properties",
    }
}

与发送节点和关系类似，整体吞吐量取决于并行 Flight 流的数量和记录批次的大小。

与节点导入类似，服务器期望节点记录遵循特定模式。给定一个示例节点，例如 ({ yob: 1984, magic: 1.8, rank: 42 })，其记录必须表示如下

nodeId	yob	magic	rank
0	1984	1.8	42

nodeId

yob

magic

rank

1984

1.8

下表描述了具有保留名称的节点列。

名称类型可选可为空描述

名称	类型	可选	可为空	描述
`nodeId`	整数	否	否	内存图中唯一的 64 位节点标识符。必须是正值。

nodeId

整数

否

内存图中唯一的 64 位节点标识符。必须是正值。

除 nodeId 以外的任何附加列都被解释为要追加的新节点属性。支持的数据类型等同于 GDS 节点属性类型，即 long、double、long[]、double[] 和 float[]。

一旦所有节点记录批次都发送到服务器，客户端需要指示节点追加已完成。这通过发送另一个操作类型为 v1/PUT_NODE_PROPERTIES_DONE 的 Flight 操作和以下 JSON 文档作为操作体来实现

{
    name: "my_graph"
}

服务器通过返回一个 JSON 文档来确认操作，该文档包含导入过程的名称和已更新节点的数量

{
    name: "my_graph",
    node_count: 1
}

创建 Neo4j 数据库

AuraDS 不提供此功能。

客户端-服务器协议也可用于创建新的 Neo4j 数据库而不是内存图。要初始化数据库导入过程，我们需要将初始操作类型更改为 v1/CREATE_DATABASE。操作体是一个 JSON 文档，包含导入过程的配置

{
    name: "my_database",
    concurrency: 4
}

下表包含数据库导入的所有设置。

名称类型可选默认值描述

名称	类型	可选	默认值	描述
`名称`	字符串	否	无	导入过程和生成数据库的名称。
`ID 类型`	字符串	是	INTEGER	设置输入数据中使用的节点 ID 类型。可以是 `INTEGER` 或 `STRING`。
`并发`	整数	是	可用核心	用于数据库创建过程的线程数。
`ID 属性`	字符串	是	`originalId`	存储输入数据的节点 ID 的节点属性键。
`记录格式`	字符串	是	`dbms.record_format`	已弃用：请改用 `db_format`。数据库记录格式。有效值为空白（无值，默认）、`standard`、`aligned`、`high_limit` 或 `block`。
`数据库格式`	字符串	是	`db.db_format`	数据库格式。有效值为空白（无值，默认）、`standard`、`aligned`、`high_limit` 或 `block`。
`强制`	布尔	是	假	在导入之前强制删除任何现有数据库文件。
`高 I/O`	布尔	是	假	忽略基于环境的启发式，并指定目标存储子系统是否可以支持高吞吐量的并行 I/O。
`使用不良收集器`	布尔	是	假	在导入期间收集不良节点和关系记录并将它们写入日志。

名称

字符串

否

无

导入过程和生成数据库的名称。

ID 类型

字符串

是

INTEGER

设置输入数据中使用的节点 ID 类型。可以是 INTEGER 或 STRING。

并发

整数

是

可用核心

用于数据库创建过程的线程数。

ID 属性

字符串

是

originalId

存储输入数据的节点 ID 的节点属性键。

记录格式

字符串

是

dbms.record_format

已弃用：请改用 db_format。数据库记录格式。有效值为空白（无值，默认）、standard、aligned、high_limit 或 block。

数据库格式

字符串

是

db.db_format

数据库格式。有效值为空白（无值，默认）、standard、aligned、high_limit 或 block。

强制

布尔

是

假

在导入之前强制删除任何现有数据库文件。

高 I/O

布尔

是

假

忽略基于环境的启发式，并指定目标存储子系统是否可以支持高吞吐量的并行 I/O。

使用不良收集器

布尔

是

假

在导入期间收集不良节点和关系记录并将它们写入日志。

发送初始化导入过程的动作后，后续协议与创建内存图的协议相同。更多详情请参见通过 PUT 作为 Flight 流发送节点记录和通过 PUT 作为 Flight 流发送关系记录。

支持的节点标识符类型

对于 CREATE_DATABASE 操作，可以设置 id_type 配置参数。两个可能的选项是 INTEGER 和 STRING，其中 INTEGER 是默认值。如果设置为 INTEGER，则节点（nodeId）和关系记录（sourceNodeId 和 targetNodeId）的节点 ID 列预计表示为 BigIntVector。对于 STRING ID 类型，服务器期望标识符表示为 VarCharVector。在这两种情况下，原始 ID 都作为属性存储在导入的节点上。属性键可以通过 id_property 配置选项更改。