Apache Arrow 投影

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

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

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

图投影功能已进行版本控制，以允许将来进行更改。有关版本控制命令的更多详细信息，请参阅 相应部分，该部分位于 配置 Apache Arrow 服务器 文档中。

客户端-服务器协议

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

Client-server protocol for Arrow import in GDS

  1. 初始化导入过程

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

    有关更多详细信息，请参阅 初始化导入过程。

  2. 通过 Arrow Flight 流发送节点记录

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

    有关更多详细信息，请参阅 通过 PUT 以 Flight 流的形式发送节点记录。

  3. 通过 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 流发送到服务器。每个流都需要针对服务器上的导入过程。该信息在 Flight 描述符主体中以 JSON 文档的形式进行编码

{
    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

整数

否

否

内存中图形的唯一 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)，并假设 a 的节点 ID 为 0，b 的节点 ID 为 1，则记录必须表示如下

sourceNodeId targetNodeId type at_level

0

1

"EVOLVES_TO"

16

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

名称 类型 可选 可空 描述

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 的 Flight 动作来初始化的，并使用以下动作主体

{
    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 流发送到服务器。每个流都需要针对服务器上的导入过程。该信息在 Flight 描述符主体中以 JSON 文档的形式进行编码

{
    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

整数

否

否

内存中图形的唯一 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
}

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

名称 类型 可选 默认值 描述

name

字符串

否

无

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

id_type

字符串

是

INTEGER

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

concurrency

整数

是

可用核心

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

id_property

字符串

是

originalId

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

record_format

字符串

是

dbms.record_format

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

db_format

字符串

是

db.db_format

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

force

布尔值

是

False

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

high_io

布尔值

是

False

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

use_bad_collector

布尔值

是

False

在导入期间收集错误的节点和关系记录，并将它们写入日志。

在发送操作以初始化导入过程后，后续协议与创建内存中图的协议相同。有关更多详细信息，请参阅通过 PUT 作为 Flight 流发送节点记录 和 通过 PUT 作为 Flight 流发送关系记录。

支持的节点标识符类型

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