falkordb-bulk-loader

一个用于从 CSV 输入构建 FalkorDB 数据库的 Python 工具

需求

批量加载器工具需要 Python 3 解释器。

必须运行 FalkorDB 服务器，安装说明可在 FalkorDB 文档 中找到。

安装

可以使用 pip 安装批量加载器

pip install falkordb-bulk-loader

或者

pip install git+https://github.com/falkordb/falkordb-bulk-loader.git@master

用法

pip 安装将 falkordb-bulk-insert 作为调用此工具的命令暴露出来

falkordb-bulk-insert GRAPHNAME [OPTIONS]

通过克隆仓库安装允许脚本通过 Python 如下调用

python3 falkordb_bulk_loader/bulk_insert.py GRAPHNAME [OPTIONS]

唯一必需的参数是新创建图的名字（可以出现在任何地方）和至少一个节点CSV文件。节点和关系标志应该在每个输入文件中指定一次。

falkordb-bulk-insert GRAPH_DEMO -n example/Person.csv -n example/Country.csv -r example/KNOWS.csv -r example/VISITED.csv

标签（对于节点）或关系类型（对于关系）是从输入CSV文件的基准名派生的。在这个例子中，我们将构建两组节点，标签为Person和Country，以及两种类型的关系 - KNOWS和VISITED。

FalkorDB不对属性施加模式，因此相同的属性键可以具有不同类型的值，如字符串和整数。因此，批量加载器的默认行为是在每个值独立地推断每个字段的类型。当例如，一个期望始终具有字符串值的属性有一个可以转换为整数或双精度浮点数的字段时，这可能会导致意外的行为。为了避免这种情况，请使用—enforce-schema标志并按输入模式中所述更新CSV标题。

扩展参数描述

max-token-count、max-buffer-size和max-token-size的标志通常不是必需的。它们只在创建图时的内存开销太高，或服务器调用量太大时才应指定。批量加载器通过将二进制令牌（每个令牌包含多个节点或关系）分批发送到FalkorDB来构建大型图。

为向后兼容性维护—quote，并允许在默认模式下对Python的类型推断进行一些控制。首选—enforce-schema-type。

—enforce-schema-type表示输入CSV标题将遵循输入模式中描述的格式。

—nodes-with-label和—relations-with-type允许显式编写节点标签或关系类型，而不是从文件名中推断它们。例如，—relations-with-type HAS_TAG post_hasTag_tag.csv将添加指定CSV中描述的所有类型为HAS_TAG的关系。要指定多个标签，请用':'分隔它们。例如，—nodes-with-label Actor:Director actors.csv将添加指定CSV中描述的所有标签为Actor和Director的节点。

输入约束

节点标识符

• 如果正在创建节点和关系，则每个节点必须与一个唯一标识符关联。
• 如果不使用—enforce-schema，则标识符是每个标签CSV文件的第一列。如果该列的名称以下划线（_）开头，则标识符是批量加载器操作内部的，不会出现在结果图中。否则，它被视为节点属性。
• 每个标识符必须在所有标签文件中完全唯一。可以使用ID命名空间来写入更细粒度的标识符。
• 在关系CSV文件中引用源节点和目标节点时，应使用它们的标识符。
• 仅创建节点时，唯一性限制将被取消。

实体属性

• 不需要显式提供属性类型。
• 属性不需要仅由任何类型组成。
• 批量加载器目前支持的类型有
  • bool：可以是true或false（不区分大小写，不进行引号插值）。
  • integer：一个未引用的值，可以读取为整数类型。
  • double：一个未引用的值，可以读取为浮点类型。
  • string：任何既是引号插值又是无法转换为数字或布尔类型的字段。
  • array：一个括号插值的元素数组，这些元素可以是任何类型。数组中的字符串必须显式进行引号插值。数组属性需要使用非逗号分隔符进行CSV（-o）。
• Cypher不允许将NULL值分配给属性。
• 默认行为是推断属性类型，尝试按照整数、浮点、布尔或字符串的顺序将其转换为这些类型。
• 如果不希望进行类型推断，应使用--enforce-schema标志和输入模式。

标签文件格式

• 每行必须具有相同数量的字段。
• 忽略前导和尾随空格。
• 如果不使用输入模式，则标签文件的第一列将是节点标识符，如节点标识符中所述。
• 所有字段都是与每个节点关联的属性键。

关系文件

• 每行必须具有相同数量的字段。
• 忽略前导和尾随空格。
• 如果不使用输入模式，则每行的前两个字段是源节点标识符和目标节点标识符。这些字段的名称在标题中并不重要。
• 如果文件有超过两个字段，则所有后续字段都是关系属性，这些属性遵循与节点属性相同的规则。
• 描述的关系始终被视为有向（源→目标）。

输入CSV示例

Store.csv

storeNum | Location | daysOpen |
118 | 123 Main St | ['Mon', 'Wed', 'Fri']
136 | 55 Elm St | ['Sat', 'Sun']

此CSV将使用以下命令插入：falkordb-bulk-insert StoreGraph --separator \| --nodes Store.csv

（由于管道字符在终端中有意义，因此必须使用反斜杠转义。）

所有storeNum属性将作为整数插入，Location将作为字符串插入，而daysOpen将作为字符串数组插入。

输入模式

如果指定了--enforce-schema标志，则所有输入CSV都应预期在标题中指定每列的数据类型。

此格式取消了一些默认CSV格式的约束，例如ID字段必须是第一列。

大多数标题字段应该是属性名和其数据类型之间的冒号分隔对，例如Name:STRING。某些数据类型不需要名称字符串，如下所示。

接受的数据类型包括

如果 ID 列有一个名称字符串，则该值将被添加到每个节点作为属性。默认情况下，该属性将是字符串类型，但可以使用 --id-type 参数将其更改为整数。如果没有提供名称字符串，则 ID 是批量加载操作内部的，不会出现在图中。START_ID 和 END_ID 列永远不会作为属性添加。

ID 命名空间

通常，节点标识符需要在所有输入 CSV 中是唯一的。当使用输入模式时，可以选择创建 ID 命名空间，标识符只需在其命名空间内是唯一的。当每个输入 CSV 都有与其他重叠的主键时，这特别有用。

要引入一个命名空间，在 :ID 类型字符串后跟一个括号内插的命名空间字符串，例如 :ID(User)。在关系文件的 :START_ID 或 :END_ID 字段中应指定相同的命名空间，如 :START_ID(User)。

输入模式 CSV 示例

User.csv

:ID(User), name:STRING, rank:INT
0, "Jeffrey", 5
1, "Filipe", 8

FOLLOWS.csv

:START_ID(User), :END_ID(User), reaction_count:INT
0, 1, 25
1, 0, 10

使用以下命令插入这些 CSV 文件： falkordb-bulk-insert SocialGraph --enforce-schema --nodes User.csv --relations FOLLOWS.csv

将生成一个名为 SocialGraph 的图，其中有 2 个用户，Jeffrey 和 Filipe。Jeffrey 关注 Filipe，并且这个关系有一个 reaction_count 为 25。Filipe 也关注 Jeffrey，reaction_count 为 10。

执行批量更新

Pip 安装还公开了 falkordb-bulk-update 命令

falkordb-bulk-update GRAPHNAME [OPTIONS]

通过克隆存储库安装允许通过 Python 调用批量更新器

python3 falkordb_bulk_loader/bulk_update.py GRAPHNAME [OPTIONS]

批量更新器允许以批量的方式读取 CSV 文件，并根据提供的查询将其提交给 falkordb。

例如，给定 输入模式 CSV 示例 中描述的 CSV 文件，批量加载器可以使用以下命令创建相同的节点和关系

falkordb-bulk-update SocialGraph --csv User.csv --query "MERGE (:User {id: row[0], name: row[1], rank: row[2]})"
falkordb-bulk-update SocialGraph --csv FOLLOWS.csv --query "MATCH (start {id: row[0]}), (end {id: row[1]}) MERGE (start)-[f:FOLLOWS]->(end) SET f.reaction_count = row[2]"

当使用批量更新器时，必须事先清理 CSV 输入，因为 falkordb 将增量提交更改到图中。因此，格式错误的输入可能会导致图处于部分更新的状态。