Skip to main content

数据迁移

备份恢复工具

arc_br 是 Fabarta 公司为 ArcGraph 图数据库用户提供的一款具有集群级数据备份与恢复(Backup & Restore,BR)功能的备份恢复工具。通过该工具可以将集群中的数据备份至系统指定的路径下,有效保障数据的安全性和可恢复性。当 ArcGraph 图数据库遭遇极端情况时,可使用 arc_br 工具迅速、准确地从备份目录中恢复数据至集群,从而确保业务的连续性和数据的完整性。

arc_br 获取

自 ArcGraph v2.1.2 版本起,arc_br 内置于 ArcGraph OLTP 引擎的 Docker 镜像中。用户成功安装 ArcGraph OLTP 引擎后,无需进行额外的下载与安装步骤,即可直接使用 arc_br 进行数据备份与恢复操作。

参数介绍

arc_br 支持的参数如下。

参数说明
-action指定 arc_br 的工作模式,包括 backuprestore 两种模式。
  • backup:备份模式,执行备份数据操作。
  • restore:恢复模式,执行恢复数据操作。
-name指定操作的备份目录名称。
  • 备份模式:在执行备份数据操作时,需自定义备份目录的名称且该名称在同一个 ArcGraph 集群中必须唯一。为了方便管理和识别,建议使用“arc_br+时间戳”的格式命名,如 arc_br_1716290038。
    备份数据操作完成后,生成的备份目录将存放在 ArcGraph 图数据库指定的路径中,默认为“/data/arcgraph/backup”,该路径可通过在 ArcGraph 图数据库中执行 SHOW CONFIGS LIKE "store_backup_path"; 语句查询获取,详情请参见 SHOW CONFIGS 章节。
  • 恢复模式:在执行恢复数据操作时,请准确指定待恢复的备份目录名称。
    执行恢复数据操作前请确认已将待恢复的备份目录放置在 ArcGraph 图数据库指定的恢复路径中,默认为“/data/arcgraph/restore”。该路径可通过在 ArcGraph 图数据库中执行 SHOW CONFIGS LIKE "store_restore_path"; 语句查询获取,详情请参见 SHOW CONFIGS 章节。
-user指定 ArcGraph 的用户名。
-password指定 ArcGraph 的密码。
-e      用于指定 ArcGraph 图数据集群中服务器的 IP 地址和端口号信息,格式为 -e <ip>:<port>

使用限制

在使用 arc_br 进行数据备份和恢复时,需要注意以下限制条件:

  • arc_br 目前仅支持集群级别的备份和恢复操作,暂不支持针对某个图或更细粒度的数据进行备份和恢复。
  • arc_br 目前仅支持全量备份与恢复,不支持基于特定时间点的数据恢复。即无法单独恢复某一特定时间点的数据,而只能恢复到之前进行全量备份时的数据状态。

数据备份

arc_br 备份恢复工具支持集群级数据备份功能,能够将 ArcGraph 图数据集群中的数据备份至系统指定的路径下,从而实现对数据安全性和可恢复性的双重保障。在备份过程中,arc_br 采用严谨的备份机制,确保备份数据的完整性和一致性。备份操作支持在集群中的任意服务器节点上进行,为优化集群性能,推荐在 Follow 服务器节点上执行备份操作,以减轻 Leader 服务器节点的负载压力,尽管这可能会带来轻微的数据延迟。若对数据即时性有较高要求,建议直接在 Leader 服务器节点上执行备份操作。

由于 arc_br 目前仅支持全量备份与恢复,建议用户定期执行全量备份并妥善管理备份文件,以便在需要时快速恢复到最近的备份状态。

前提条件

  • 操作前请确认您的系统中已部署并成功运行 ArcGraph OLTP 引擎,且 ArcGraph OLTP 引擎版本不低于 v2.1.2。
  • 操作前请确认当前登录用户是超级管理员用户。
  • 操作前请确认已获取 ArcGraph 图数据库集群中服务器的 IP 地址和端口号信息,通过在 ArcGraph 图数据库中执行 SHOW SERVERS; 语句可查看该信息,详情请参见 SHOW SERVERS 章节。

执行备份操作

在 ArcGraph 图数据库集群中任意服务器节点所运行的 Docker 容器中,通过 arc_br 工具执行备份命令,对整个集群中的数据进行全量备份。

在 Docker 容器中执行备份命令时,需遵循以下格式:

./arc_br --action backup --name <br_image_name> --user <user_name> --password <password> -e <ip>:<port>

示例
使用 arc_br 工具对 ArcGraph 图数据库集群执行数据备份操作,并将备份数据保存至名为“arc_br_1716290038”的备份目录中。具体操作步骤如下:

  1. 根据实际情况,从 ArcGraph 图数据库集群中选择一个合适的服务器节点,并进入该服务器节点所运行的 Docker 容器中。
    该服务器节点的 IP 地址为: 127.0.0.1, 端口为: 8182,用户名和密码为:arcgraph。

  2. 执行如下命令,备份数据。

    ./arc_br --action backup --name arc_br_1716290038 --user arcgraph --password arcgraph -e 127.0.0.1:8182
  3. 返回结果中有如下字段,表示数据已经备份成功。

    backup success, name: arc_br_1716290038

数据恢复

arc_br 提供了强大的集群级数据恢复功能,用户可以通过 arc_br 工具将其创建的备份文件中的数据恢复到集群中,确保在发生意外情况时能够迅速恢复数据,从而降低数据丢失的风险。在进行 ArcGraph 图数据库集群的数据恢复时,需分别在每个服务器节点对应的 Docker 容器内执行恢复命令,以确保集群中所有服务器节点的数据均得到完整恢复。在数据恢复过程中,请勿对 ArcGraph 图数据库集群进行数据写入或修改等操作,以免导致恢复失败。

数据恢复操作将直接覆盖 ArcGraph 图数据库中现有的数据。为防止数据丢失或误覆盖,建议用户在执行数据恢复操作前,备份 ArcGraph 图数据库的当前数据。

前提条件

  • 操作前请确认您的系统中已部署并成功运行 ArcGraph OLTP 引擎,且 ArcGraph OLTP 引擎版本不低于 v2.1.2。
  • 操作前请确认当前登录用户是超级管理员用户。
  • 操作前请确认已将待恢复的备份目录放置在 ArcGraph 图数据库指定的恢复路径中。
  • 操作前请确认已获取 ArcGraph 图数据库集群中所有服务器的 IP 地址和端口号信息。在 ArcGraph 图数据库中可通过 SHOW SERVERS 语句查看该信息,详情请参见 SHOW SERVERS 章节。

执行恢复操作

将备份目录放置在 ArcGraph 图数据库指定的恢复路径后,即可在 ArcGraph 图数据库集群的每个服务器节点所运行的 Docker 容器中,通过 arc_br 工具执行恢复命令,从而恢复备份数据。

在 Docker 容器中执行恢复命令时,需遵循以下格式:

./arc_br --action restore --name <br_image_name> --user <user_name> --password <password> -e <ip>:<port>

示例 1
使用 arc_br 工具对单机版 ArcGraph 图数据库(即集群仅包含一个服务器节点)执行数据恢复操作,恢复备份目录“arc_br_1716290038”中的数据至 ArcGraph 图数据库集群中。具体操作步骤如下:

  1. 进入 ArcGraph 图数据库服务器节点所运行的 Docker 容器中。
    该服务器节点的 IP 地址为: 127.0.0.1, 端口为: 8182,用户名和密码为:arcgraph。

  2. 执行如下命令,恢复数据。

    ./arc_br --action restore --name arc_br_1716290038 --user arcgraph --password arcgraph -e 127.0.0.1:8182 
  3. 返回结果中有如下字段,表示数据已经恢复成功。

    restore success, name: arc_br_1716290038

示例 2
使用 arc_br 工具对敏捷版 ArcGraph 图数据库(即集群仅包含三个服务器节点)执行数据恢复操作,恢复备份目录“arc_br_1716290038”中的数据至 ArcGraph 图数据库集群中。具体操作步骤如下:

  1. 进入 ArcGraph 图数据库服务器节点所运行的 Docker 容器中。
    该服务器节点的 IP 地址为: 127.0.0.1, 端口为: 8182,用户名和密码为:arcgraph。

  2. 执行如下命令,恢复数据。

    ./arc_br --action restore --name arc_br_1716290038 --user arcgraph --password arcgraph -e 127.0.0.1:8182 
  3. 返回结果中有如下字段,表示该服务器节点的数据已经成功恢复。

    restore success, name: arc_br_1716290038
  4. 对集群中另外两个服务器节点执行步骤 1~3。

逻辑导入导出工具

arc_pump 是 Fabarta 公司为 ArcGraph 图数据库用户提供的一款高效、灵活的数据导入导出工具,它支持将 CSV 文件导入到图数据库中,也可以将图数据库中指定的图导出为 CSV 文件。它为专业图数据库用户提供了快速、高效的数据传输和处理能力。

arc_pump 下载

arc_pump 与 ArcGraph 图数据库的版本兼容性信息如下。请根据您的 ArcGraph 图数据库版本,选择并下载相应版本的 arc_pump。本章节将以 arc_pump v2.1.0_ha 版本为例,为您详细介绍其使用方法。

arc_pump 版本ArcGraph 图数据库版本
v2.1.2v2.1.2
v2.1.1v2.1.1
v2.1.0_hav2.1.0_ha
v2.1.0v2.1.0

arc_pump 参数介绍

arc_pump 命令行工具支持的参数如下:

参数说明
-a指定 ArcGraph 服务器的地址。
-u指定 ArcGraph 服务器的登录用户名。
-p指定 ArcGraph 服务器的密码。
-g指定操作的图名称。
-d指定操作的数据目录,即数据存放路径。
-m指定操作的类型,支持设置为 import(导入) 或 export(导出)。
-c指定操作的配置文件名。
说明:
当配置文件与 arc_pump 命令行参数中设置的参数值不同时,默认情况下,命令行参数具有更高的优先级。例如,如果在命令行参数中指定了 -p 123456,而在配置文件中将 password 设置为 arcgraph,则最终会认定用户密码为 123456
-b指定导入时批量处理 CSV 文件的数据条数,默认值为 1。例如,将该参数设置为“1000”,那么一条 insert(插入)或 upsert(更新)语句将会处理 1000 条 CSV 数据。
-op指定操作的默认行为,支持设置为 insertupsertmerge,默认设置为 insert
- insert:插入数据,用于向数据库中插入新数据,如果出现主键冲突,则导入会出错。
- upsert:更新已有数据,新的属性值将覆盖原有记录。例如,如果待导入对象包含属性 AB,而本次操作导入的属性是 BC,则最终结果将只包含属性 BC
- merge:合并数据,其中没有被指定写入的属性将会保持不变。例如,如果待导入对象包含属性 AB,而本次操作导入的属性是 BC,则最终结果将包含属性 ABC。请注意,仅 arc_pump >= v2.1.1 版本支持此参数。
-with_schema导入数据前,可以通过指定 -with_schema 参数来执行 Cypher 脚本,以定义图、点类型和边类型。如果此参数未设置参数值,arc_pump 将自动查找 -d 参数所指定目录下的 "schema/schema.cql" 文件并执行。例如,若“schema.cql”文件位于“test/data/schema/”目录中,则可以使用-d test/data -with_schema ""-d test -with_schema "test/data/schema/schema.cql" 语句来执行 Cypher 脚本。如果该文件不存在,程序将报错并退出。
说明:
- 如果命令行中已包含 -with_schema 参数,则无需在 ArcGraph 图数据库中手动创建对应的图、点类型和边类型,因为这些将在数据导入前通过 Cypher 脚本自动创建。
- 如果 ArcGraph 图数据库中已存在与待导入数据对应的图、点类型和边类型,使用 -with_schema 参数可能会产生冲突并导致程序报错退出。
-file当进行单个文件导入数据时,该参数用于指定导入的文件名称。请注意,当 -file 指定导入文件时,-d 参数值无效。
-vertex当进行单个文件导入点数据时,该参数用于指定导入的点类型的名称。
-srcVertex当进行单个文件导入边数据时,该参数用于指定导入边数据的起始点类型名称。
-dstVertex当进行单个文件导入边数据时,该参数用于指定导入边数据的目标点类型名称。
-edge当进行单个文件导入边数据时,该参数用于指定导入边数据的边类型名称。
-timeout用于指定请求的超时时长,即系统等待响应的最大时间限制,单位为秒(s),默认设置为 600 秒。若在该设定时间内未接收到任何响应,则请求将被判定为超时失败。
说明:
仅 arc_pump >= v2.1.1 版本支持此参数。
-direct用于指定通信地址,支持设置为 truefalse,默认设置为 false
- 当 -direct 设置为 true 时,arc_pump 直接使用用户提供的地址通信。
- 当 -direct 设置为 false 时,arc_pump 会通过用户提供的地址找到集群中的 LEADER 节点后再与该 LEADER 节点进行通信。
说明:
仅 arc_pump >= v2.1.1 版本支持此参数。

数据导入

在图数据库中,数据导入是至关重要的环节,特别是在处理大规模或复杂数据时。通过有效的数据导入,可以确保图数据库的完整性和准确性,从而为后续的数据分析和挖掘提供可靠的基础。arc_pump 提供了两种导入方式,以满足不同用户的需求:

  • 一键式导入
    用户只需在命令行工具中输入相应命令,并指定数据文件的路径,即可将 CSV 文件中的数据快速导入到目标图中。此方式无需复杂的配置步骤,操作简便,适用于基础的数据导入需求。

  • 高级导入
    通过配置文件与命令行语句相结合的方式导入数据,以满足不同数据导入的要求。用户通过创建自定义 .yaml 格式的配置文件,可以详细设置导入过程中的各种参数和条件,如数据属性、点边属性的映射关系等。然后在命令行工具中执行相应命令导入数据。这种方式提供了更大的灵活性和定制性,满足各种复杂的导入需求。用户可以设置多个导入条件,提高数据导入的准确性和效率。

在实际操作中,请根据实际情况选择适合的导入方式。关于 arc_pump 支持的命令行参数的信息,详情请参见 参数介绍 章节。

说明:

  • 在导入数据时,如果 ArcGraph 图数据库中已存在该数据或 CSV 文件中数据的属性名称和类型与图 Schema 不匹配时,arc_pump 默认会报错并退出,但如果您在命令中指定 -op 参数值为 upsertmerge,程序将执行对应操作,不会报错退出,详情请参见 参数介绍 章节。
  • 如果指定路径下存在多个 CSV 文件,但无与之对应的图 Schema,程序将报错并退出,可通过在命令中使用 -file 参数指定导入文件解决,详情请参见 参数介绍 章节。
  • 若在导入数据时,CSV 文件中的属性数量超过已创建的图 Schema 中的属性数量,使用一键式导入会导致程序报错并退出。若选择高级导入方式,您可以在配置文件中定义属性映射关系,以适应实际情况并正常导入数据。若无可以匹配的属性,程序同样会报错并退出。
  • 当 CSV 文件中的属性数量少于创建的图 Schema 中的属性数量且该属性可以为空时,可导入数据。
  • CSV 文件中,列索引位置从 0 开始计数。
  • CSV 和 .ymal 文件内容格式须符合对应标准的写作格式。只有符合标准格式的文件才能被正确读取和导入,否则可能会导致数据导入失败。

前提条件

  • 请确保已安装并运行 Java,Java 版本要求为 Java 8 及以上版本。
  • 在导入数据前,请确认已知待导入数据的 ArcGraph 图数据库服务器的 IP 地址、登录用户名和密码。
  • CSV 文件命名规则如下,请确保 CSV 文件的命名和格式符合此规则,否则可能会导致数据导入失败。
    • 点数据文件名必须符合“点类型名称_数字_数字.csv”的格式。例如,Person_1_1.csv。
    • 边数据文件名必须符合“起始点类型名称_边类型名称_目标点类型名称_数字_数字.csv”的格式。例如,Person_knows_Books_1_1.csv。
  • 导入边数据前,请确保已导入对应的点数据,并确保 CSV 格式正确。默认情况下,边数据的 CSV 文件中列索引位置“0”代表边的起始点属性,列索引位置“1”代表边的目标点属性。

一键式导入

一键式导入是 arc_pump 命令行工具中一种简便的数据导入方式。用户只需在命令行中输入相应的命令,即可快速将数据导入到目标图中。该方式允许用户在导入数据前,根据需求在 ArcGraph 图数据库中手动创建图 Schema,详情请参见 图、点/边类型、索引 等章节或提供图 Schema 的 CQL 文件通过执行 -with_schema 命令自动创建,详情请参见 参数介绍 章节。请注意,指定单文件导入时,不支持自动创建图 Schema 操作。

示例 1
通过命令行语句自动创建图 Schema,并将指定路径下的 CSV 文件导入到指定的图中。具体操作步骤如下:

  1. 准备创建图 Schema 的 CQL 文件,命名为“schema.cql”并存放在“testdata/schema”目录下,文件内容如下。

    CREATE GRAPH IF NOT EXISTS LDBC_SNB
    CHARSET = utf8
    COMMENT = '新图';

    USE GRAPH LDBC_SNB;

    CREATE VERTEX IF NOT EXISTS person
    (
    PRIMARY KEY id INT(64),
    name STRING COMMENT '姓名',
    age INT(32) NOT NULL DEFAULT '16' COMMENT '年龄',
    INDEX name_index(name) UNIQUE
    )
    COMMENT = '测试Vertex';

    CREATE EDGE like (
    name string NOT NULL COMMENT '喜欢',
    since INT(64) default '2020' COMMENT '开始时间',
    FROM person TO person,
    INDEX index_a(name)
    )
    COMMENT = '测试Edge';

    说明:

    • CQL 文件中请勿带注释。
    • CQL 文件的存放路径须为“schema/schema.cql”,命名须为:“schema.cql”。
  2. 准备数据的 CSV 文件。文件内容如下。

    • 点数据文件,命名为“person_1_1.csv”并存放在“testdata/data”目录下。
       id|name|age
      1|John|25
      2|Mary|24
      3|Jerry|23
      4|Lihua|22
      5|Xiaoli|21
    • 边数据文件,命名为“person_like_person_1_1.csv”并保存在“testdata/data”目录下。
      person.id|person.id|name|since
      1|5|'喜欢'|2020
      2|4|'喜欢'|2021
      3|5|'喜欢'|2022
  3. 打开命令行终端,执行如下命令,将目录“testdata”中的 CSV 文件导入到图“LDBC_SNB”中。命令行参数说明请参见 参数介绍 章节。

    java -jar ./arc_pump-2.1.0_ha-SNAPSHOT.jar -m import -a localhost:8182 -u arcgraph -p arcgraph -g LDBC_SNB -b 5000 -d testdata -with_schema "";
  4. 导入成功后,在 ArcGraph 图数据库中执行如下语句验证数据导入情况。

    • 查看图
      SHOW GRAPHS;
    • 在图中查询点数据
      MATCH (n) RETURN n;
    • 在图中查询边数据
      MATCH (n:person)-[r]->(person)
      RETURN r;

示例 2
已在 ArcGraph 图数据库中创建了对应的图 Schema,并且已准备好 CSV 文件,详情请参考“示例 1”。打开命令行终端,根据实际情况执行相应的命令,将指定路径下的 CSV 文件导入到指定的图中。命令行参数说明请参见 参数介绍 章节。

  • 批量导入数据
    将目录“testdata”中的 CSV 文件导入到图“LDBC_SNB”中,命令如下:

    java -jar ./arc_pump-2.1.0_ha-SNAPSHOT.jar -m import -a localhost:8182 -u arcgraph -p arcgraph -g LDBC_SNB -b 5000 -d testdata;
  • 导入指定文件数据

    # 将目录“testdata”中的“person_1_1.csv”点数据文件导入到图“LDBC_SNB”中
    java -jar ./arc_pump-2.1.0_ha-SNAPSHOT.jar -m import -a localhost:8182 -u arcgraph -p arcgraph -g LDBC_SNB -b 5000 -file testdata/data/person_1_1.csv -vertex person -d testdata;

    # 将目录“testdata”中的“person_like_person_1_1.csv”边数据文件导入到图“LDBC_SNB”中
    java -jar ./arc_pump-2.1.0_ha-SNAPSHOT.jar -m import -a localhost:8182 -u arcgraph -p arcgraph -g LDBC_SNB -b 5000 -file testdata/data/person_like_person_1_1.csv -srcVertex person -dstVertex person -edge like -d testdata;

高级导入

通过结合配置文件和命令行语句,用户可以在配置文件中灵活地设定导入过程中的各种参数和条件。这种高级导入方式为用户提供了更大的灵活性和定制性,从而满足各种复杂的导入需求。

示例

  1. 创建导入数据时的 .yaml 配置文件。自定义配置文件名称为“import_config.yaml”。文件具体内容示例如下:

    ########################################
    # Server Configuration
    ########################################

    # 设置ArcGraph服务器的IP地址及端口号
    serverAddress: "localhost:8182"
    # 设置ArcGraph服务器的登录用户名
    username: arcgraph
    # 设置ArcGraph服务器的密码
    password: arcgraph

    ########################################
    # Action Type configuration
    ########################################
    # 设置操作类型为“import”(导入)
    method: "import"
    # 设置请求的超时时长,单位为秒(s)
    timeout:600
    ########################################
    # Import configuration
    ########################################
    # 设置导入CSV文件的存放路径
    dataFolder: "./testdata/"
    # 设置将要导入数据的图名称,需与ArcGraph中的名称保持一致
    graphName: "LDBC_SNB"
    # 设置导入数据时批量处理的CSV条数
    batchSize: 1
    # 设置导入数据时的错误日志存放路径,arc_pump会将未导入成功的数据重新生成CSV文件并存放在此路径下,导入时会自动创建该路径
    importErrorFolder: "./test_export_error/"
  2. (可选)在配置文件中设置导入规则,即设置导入数据的属性或点边属性的映射关系。如未设置规则,默认导入全部数据。

    • 设置点数据的导入规则
    # 此处设置需要导入的点类型及属性,可以设置多个
    vertexImportMapping:
    - filePath: "./testdata/data/person_1_1.csv" #点类型CSV文件的存放路径
    vertexName: 'person' # 点类型的名称,需与ArcGraph中的名称保持一致
    primaryKeyColumnIdx: 0 # 该点类型的主键在CSV文件中的列索引位置
    propertyMapping:
    - name: "name" # 需要导入的属性名称,需与ArcGraph中的名称保持一致
    idx: 1 # 该属性在CSV文件中的列索引位置
    • 设置边数据的导入规则
    # 此处设置需要导入的边类型的点边映射关系及属性,可以设置多个
    edgeImportMapping:
    - filePath: "./testdata/data/person_like_person_1_1.csv" #边类型CSV文件的存放路径
    sourceVertexName: 'person' # 边的起始点类型名称,需与ArcGraph中的名称保持一致
    sourceVertexColumnIdx: 0 # 该点类型的主键在CSV文件中的列索引位置
    targetVertexName: 'person' # 边的目标点类型名称,需与ArcGraph中的名称保持一致
    targetVertexColumnIdx: 1 # 该点类型的主键在CSV文件中的列索引位置
    edgeName: 'like' # 边类型的名称,需与ArcGraph中的名称保持一致
    # 边的_ts属性在CSV文件中的列索引位置。如果边不带_ts属性,此处设置将无效并被忽略。
    rankColumn: -1
    propertyMapping: # 边的属性映射
    - name: "since" # 边的属性名称,需与ArcGraph中的名称保持一致
    idx: 3 # 该属性在CSV文件中的列索引
  3. 在终端中执行如下语句,导入数据。

    • 执行下列命令行语句自动创建图 Schema 并导入数据。
      java -jar ./arc_pump-2.1.0_ha-SNAPSHOT.jar -c import_config.yaml -d testdata -with_schema "";
    • 已在 ArcGraph 图数据库中创建了对应的图 Schema,执行下列命令行语句导入数据。
      java -jar ./arc_pump-2.1.0_ha-SNAPSHOT.jar -c import_config.yaml;

数据导出

在图数据库中,数据导出同样是一个关键环节,尤其在需要共享数据或迁移数据时。通过有效的数据导出,用户可以确保数据的完整性和准确性,同时为其他应用或系统提供可靠的数据源。arc_pump 提供了两种导出方式,以满足不同用户的需求:

  • 一键式导出
    用户只需在命令行工具中输入相应命令,即可快速将数据从目标图导出为 CSV 文件。此方式无需复杂的配置步骤,操作简便,适用于基础的数据导出需求。

  • 高级导出
    通过配置文件与命令行语句相结合的方式导出数据,以满足不同数据导出的要求。用户可以创建自定义的 .yaml 格式配置文件,设置导出的数据范围、过滤条件等,以确保导出的数据符合预期。然后,在命令行工具中执行相应命令完成数据导出。这种方式提供了更大的灵活性和定制性,满足各种复杂的数据导出需求。

在实际操作中,请根据实际情况选择适合的导出方式。关于 arc_pump 支持的命令行参数的信息,详情请参见 参数介绍 章节。

前提条件

  • 请确保已安装并运行 Java,Java 版本要求为 Java 8 及以上版本。
  • 在导出数据前,请确认已知待导出数据的 ArcGraph 图数据库服务器的 IP 地址、登录用户名和密码。
  • .ymal 文件内容格式须符合标准的写作格式。只有符合标准格式的文件才能被正确读取,否则可能会导致数据导出失败。

一键式导出

在 arc_pump 中,通过执行简单的命令行语句,即可将指定图中的数据快速导出为 CSV 格式,并保存在指定的路径下,极大地提高了数据导出的效率和便利性。

示例
通过命令行将图“LDBC_SNB”中的所有数据导出为 CSV 文件并存放到目录“export_ldbc_folder”中,包括 Schema 创建的语句以及相关数据,命令如下:

java -jar ./arc_pump-2.1.0_ha-SNAPSHOT.jar -m export -a localhost:8182 -u arcgraph -p arcgraph -g LDBC_SNB -d export_ldbc_folder -b 2000;

高级导出

通过配置文件与命令行语句相结合的方式导出数据。这种方式的优点在于,它为用户提供了配置具体导出规则的灵活性,允许选择要导出的点类型/边类型以及其属性列表,并应用过滤规则,使用户可以更加精确地控制导出的数据内容,以满足不同的需求和场景。

示例

  1. 创建导出数据时的配置文件。自定义配置文件名称为“export_config.yaml”。文件具体内容示例如下:

    ########################################
    # Server Configuration
    ########################################

    # 设置ArcGraph服务器的IP地址及端口号
    serverAddress: "localhost:8182"
    # 设置ArcGraph服务器的登录用户名
    username: arcgraph
    # 设置ArcGraph服务器的密码
    password: arcgraph

    ########################################
    # Action Type configuration
    ########################################
    # 设置操作类型为“export”(导出)
    method: "export"
    # 设置请求的超时时长,单位为秒(s)
    timeout:600
    ########################################
    # Export configuration
    ########################################
    # 设置导出CSV文件的存放路径,导出时会自动创建该路径
    dataFolder: "./test_export/"
    # 设置将要导出数据的图名称,需与ArcGraph中的名称保持一致
    graphName: "LDBC_SNB"
  2. (可选)在配置文件中设置导出规则,即设置导出数据时的过滤条件。如未设置规则,默认导出全部数据。

    • 设置点数据的导出规则
      # 设置图中将要导出的点类型
      vertexes:
      - name: "person" # 设置点类型的名称,需与ArcGraph中的名称保持一致
      properties: # 设置该点类型需要导出的属性,属性名称需与ArcGraph中的名称保持一致
      - id
      - name
      filters: # 设置点类型的导出过滤条件,条件将按AND逻辑合并。如未涉及请删除此部分内容。
      - "#name.id <> 0"
      - "#name.name != \"abc\""
    • 设置边数据的导出规则
      # 设置图中将要导出的边类型
      edges:
      - name: "like" # 设置边类型的名称,需与ArcGraph中的名称保持一致
      properties: # 设置该边类型需要导出的属性,属性名称需与ArcGraph中的名称保持一致
      - since
      filters: # 设置边类型的导出过滤条件,条件将按AND逻辑合并。如未涉及请删除此部分内容。
      - "#name.since > 2020"
      - "#srcVertex.id <> 0"
  3. 在终端中执行如下语句,导出数据。

    java -jar ./arc_pump-2.1.0_ha-SNAPSHOT.jar -c export_config.yaml

API

arc_pump 不仅可作为独立工具使用,还支持作为库集成到第三方应用中。

库引用指南

  • 环境要求:
    请确保已安装并运行 Java,Java 版本要求为 Java 8 及以上版本。

  • 依赖配置:
    在您的 Java 项目中添加以下 Maven 依赖,以便正常使用。

    <dependency>
    <groupId>com.fabarta.arcgraph</groupId>
    <artifactId>arc_pump</artifactId>
    <version>2.1.0-SNAPSHOT</version>
    </dependency>

应用示例

目前,arc_pump 主要应用于数据导入场景。

  • 导入点数据
    package com.fabarta.arcgraph.data.tools;

    import ch.qos.logback.classic.Level;
    import ch.qos.logback.classic.Logger;
    import com.fabarta.arcgraph.data.config.CSVConfig;
    import com.fabarta.arcgraph.data.config.LoadConfig;
    import com.fabarta.arcgraph.data.config.ServerConfig;
    import org.slf4j.LoggerFactory;

    import java.util.HashMap;
    import java.util.Map;

    public class DemoLoadVertex {
    public static void main(String[] args) {
    Logger root = (Logger) LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME);
    root.setLevel(Level.INFO);
    // 配置Server链接地址
    ServerConfig serverConfig = new ServerConfig(
    "dockersrvip:8182",
    "arcgraph",
    "arcgraph"
    );
    // 配置CSV文件分割符
    CSVConfig csvConfig = new CSVConfig('|');
    // 配置导入时需要将csv的第几列导入到目标Vertex的哪一个属性上
    Map<Integer, String> map = new HashMap<>();
    map.put(0, "id"); // 将CSV文件的第0列数据导入到目标Vertex的id属性上
    map.put(1, "name");// 将CSV文件的第1列数据导入到目标Vertex的name属性上
    LoadConfig loadConfig = LoadConfig.createVertexLoadConfig(
    "g1", // 图名称
    "person", // 点类型名称
    // CSV文件路径
    "/Users/qingweiren/code/work/curr/infrapackage_macm1/sf0.1-raw/social_network/dynamic/person_0_0.csv",
    false, // 发生错误时是否终止
    true, // CSV文件中是否包含头部信息
    map, // 映射关系
    "errorFilePath.csv" // 未能导入的CSV数据
    );
    // 创建导入任务
    Task task = TaskManager.createImportTask(
    serverConfig,
    csvConfig,
    loadConfig
    );
    // 创建导入任务线程
    Thread t = new Thread(task);
    t.start();
    int progress = 0;
    // 观测执行进度并打印
    while (!task.isFinished()) {
    try {
    Thread.sleep(100);
    int newProgress = task.getProgress();
    if (progress != newProgress) {
    System.out.println(newProgress);
    progress = newProgress;
    }
    } catch (InterruptedException e) {
    e.printStackTrace();
    }
    }
    // 等待任务结束
    try {
    t.join();
    } catch (InterruptedException e) {
    e.printStackTrace();
    }

    }
    }
  • 导入边数据
    package com.fabarta.arcgraph.data.tools;

    import ch.qos.logback.classic.Level;
    import ch.qos.logback.classic.Logger;
    import com.fabarta.arcgraph.data.config.CSVConfig;
    import com.fabarta.arcgraph.data.config.LoadConfig;
    import com.fabarta.arcgraph.data.config.ServerConfig;
    import org.slf4j.LoggerFactory;

    import java.util.HashMap;
    import java.util.Map;

    public class DemoLoadEdge {
    public static void main(String[] args) {
    Logger root = (Logger) LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME);
    root.setLevel(Level.INFO);
    ServerConfig serverConfig = new ServerConfig(
    "dockersrvip:8182",
    "arcgraph",
    "arcgraph"
    );
    CSVConfig csvConfig = new CSVConfig('|');


    Map<Integer, String> map = new HashMap<>();
    map.put(2, "creationDate");
    LoadConfig loadConfig = LoadConfig.createEdgeLoadConfig(
    "g1", // 图名称
    "person", // 起点点类型名称
    "person", // 终点点类型名称
    "knows", // 边类型名称
    "/Users/qingweiren/code/work/curr/infrapackage_macm1/sf0.1-raw/social_network/dynamic/person_knows_person_0_0.csv",
    false, // 发生错误时是否终止
    true, // CSV文件是否包含头部信息
    map,
    "errorFilePath.csv"
    );
    loadConfig.setBatchSize(1000); // 设置自定义batchSize

    Task task = TaskManager.createImportTask(
    serverConfig,
    csvConfig,
    loadConfig
    );
    Thread t = new Thread(task);
    t.start();
    int progress = 0;
    while (!task.isFinished()) {
    try {
    Thread.sleep(100);
    int newProgress = task.getProgress();
    if (progress != newProgress) {
    System.out.println(newProgress);
    progress = newProgress;
    }
    } catch (InterruptedException e) {
    e.printStackTrace();
    }
    }
    try {
    t.join();
    } catch (InterruptedException e) {
    e.printStackTrace();
    }

    }
    }

物理导入工具

arc_direct_load 是 Fabarta 公司为 ArcGraph 图数据库用户打造的一款高效的物理导入工具,用于快速地将 CSV 文件中的数据批量导入到图数据库中。该工具采用先进的物理导入方式,相较于逻辑导入,其数据加载过程更为迅速、高效。因此,arc_direct_load 成为处理大规模数据的理想选择,极大地提升了数据导入的速度与效率,为用户带来前所未有的便捷体验。

下载与安装

arc_direct_load 物理导入工具支持本地安装和 Docker 环境安装两种方式,以满足不同用户的需求。

前提条件

为了顺利下载、安装以及稳定运行 arc_direct_load 工具,请在开始操作前,确保您的环境满足以下要求:

  • 操作系统及架构要求
    • 操作系统:Linux
    • 架构:ARM64 或 X86_64
  • 硬件要求
    • 内存和 CPU:推荐使用 32 核以上的 CPU 以及 64GiB 以上的内存配置,以获得更好的性能。
    • Spark 环境:至少可以启动单机版 Spark。关于 Spark 的硬件配置,请参考 Apache Spark 官方文档。
    • 存储空间:建议为 sorted_csv_dirtmp_dir 分别预留至少原数据大小 1.5 倍的存储空间,甚至更多,以确保数据处理的顺畅进行。
  • 网络要求
    • 建议使用 10 Gbps 以太网卡,以确保数据传输的高效性。
  • 版本要求
    • arc_direct_load v2.1.1 及以上版本
    • ArcGraph v2.1.1 及以上版本

Docker 安装(推荐)

在进行相关操作前,请确保您的系统中已安装并成功运行 Docker。以下是下载 arc_direct_load 工具所需的 Docker 镜像信息,安装前请联系 我们 获取专业的技术支持和指导。

Docker 镜像

  • X86_64 架构
    docker pull docker-reg.infra.fabarta.com:5000/fabarta-ga/arc_direct_load:v2.1.0-x86_64
  • ARM64 架构
    docker pull docker-reg.infra.fabarta.com:5000/fabarta-ga/arc_direct_load:v2.1.0-arm64

运行容器,启动工具

# X86_64 架构
docker run -d --name direct-load \
--net=host \
-v /data:/data \
docker-reg.infra.fabarta.com:5000/fabarta-ga/arc_direct_load:v2.1.0-x86_64

# ARM64 架构
docker run -d --name direct-load \
--net=host \
-v /data:/data \
docker-reg.infra.fabarta.com:5000/fabarta-ga/arc_direct_load:v2.1.0-arm64

本地安装

在操作前,请确保您已安装并运行以下组件:

  • Java 11 及以上版本
  • Python 3.8 及以上版本

获取安装包
单击 链接 下载 arc_direct_load 物理导入工具的安装包。

解压安装包
在终端中运行以下命令,解压安装包。

tar -zxvf arc_direct_load.tar.gz

安装
打开终端,在已创建并激活的 Python 3.8(或以上版本)虚拟环境中,运行以下命令安装 arc_direct_load 及其依赖项。

pip3 install --no-cache-dir -r arc_direct_load/spark/requirements.txt

使用 arc_direct_load

使用限制

在使用 arc_direct_load 进行数据导入时,为确保导入过程的稳定性和数据的完整性,需要遵循以下限制条件。

  • 数据导入要求:仅支持对空图进行首次数据导入操作,需一次性完成,不支持分多次导入,后续如有需要,可使用 逻辑导入导出工具 增量导入数据。导入边数据时,边数据需与其对应的起始点、目标点数据同时导入。仅支持导入与图 Schema 相匹配的 CSV 文件,多余文件将被忽略。
  • 属性限制:不支持通过 default 值填充缺失数据。
  • 不支持 DDL 和 DML 操作:在数据导入过程中,不支持对目标图进行 DDL(Data Definition Language,数据定义语言)和 DML(Data Manipulation Language,数据操作语言)操作,否则可能会导致导入操作停止或失败。
  • 避免 DQL 操作:在数据导入过程中,不建议对目标图进行 DQL(Data Query Language,数据查询语言)操作。因为数据可能不稳定,返回结果可能不准确。
  • 导入进程与状态说明:arc_direct_load 工具正常结束即表明数据已成功传输并导入至集群所有机器。若工具报错失败,则整个导入过程视为失败,即使部分机器导入成功,数据亦不可用。请检查错误原因并重新导入。
  • 及时备份:使用 arc_direct_load 工具导入的数据不支持通过增量恢复方式恢复数据,所以请在数据导入完成后执行完整的数据备份操作。
  • _ts 属性限制:若数据中含有 _ts 属性且该属性值为时间戳类型,则该时间戳的精度仅支持精确到毫秒级别。

参数介绍

arc_direct_load 工具支持的参数如下。

参数说明
-c用于指定操作所需的配置文件的存放路径及文件名。

配置文件介绍

用户可以从下载包中获取 tools_config.toml 配置文件模板,并根据实际情况,自定义 arc_direct_load 工具在数据导入过程中的各项参数配置,以满足个性化的需求。

示例
tools_config.toml 配置文件各参数的介绍如下:

[server]
# 设置ArcGraph用户名,若有多个用户名,则各用户名之间需使用“;”分隔
user = "arcgraph"
# 设置ArcGraph用户密码,若有多个密码,则各密码之间需使用“;”分隔
password = "arcgraph"
# 设置ArcGraph服务器的IP地址,若有多个服务器地址,则各服务器地址之间需使用“;”分隔
endpoints = "127.0.0.1:8182"


[performance]
# 设置线程池线程数,该值也用作Spark的分区数
# 建议将其设置为与CPU核心数相当或略小的值
pool_size = 20
# 设置分配给Spark每个executor进程的内存大小
# 请注意,增大该参数将有助于提升性能表现,请确保为其分配足够内存,避免产生溢出错误
spark_executor_memory = "5g"

[import]
# 设置运行模式,“local”模式适合单机版ArcGraph,且需要arc_direct_load工具与ArcGraph服务器在相同服务器上
# “remote”模式适合敏捷版ArcGraph,生成的sst文件会通过scp发送到ArcGraph服务器上
backend = "local" # or "remote"
# 设置将要导入数据的图名称,需与ArcGraph中的名称保持一致
graph_name = "LDBC_SNB_0_1"
# 设置待导入CSV文件的存放路径
# 注意:arc_direct_load不会递归搜索该路径下其他文件夹
client_data_dir = "/tmp/sf0.1"
# 设置ArcGraph的数据导入目录,需要与ArcGraph的配置相同
server_import_path = "/tmp/import"
# 设置排序后CSV文件输出的存放路径
# 注意:请预留足够的磁盘空间
sorted_csv_dir = "/tmp/sorted_csv"
# 设置热点文件的存放路径
# 提供热点文件可以提高查询效率
hotspot_dir = "/tmp/hotspot"
# 临时文件存放路径,用于存放数据导入过程中生成的临时文件。
# 注意:临时生成的sst文件将占用大量空间,请预留足够磁盘空间
tmp_dir = "/tmp/load_tmp"
# 设置异常数据存放路径
error_dir = "/tmp/load_error"
# 重复数据检查开关,设置为“true”则开启重复数据检测,检测待导入的CSV文件中是否有重复数据
# 注意:如果关闭,用户必须保证无重复数据,否则可能会导致导入失败
check_duplicate = true
# 开启重复数据检测后,遇到重复数据的处理办法:支持“error”和“ignore”两种模式。若“check_duplicate = true”,则此参数无效
# “error”模式下将在发现重复数据时报错终止导入;“ignore”模式下将保留第一次出现的数据,其它重复数据则输出到异常数据目录中,供后续处理
on_duplicate = "error"
# 反向边选项,设置为true则生成和导入反向边数据
reverse_edge = true
# _ts列数据类型。
# 注意:用户需要提供一个json格式的参数。
# 例如'{"edge1" : "timestamp", "edge2": "timestamp", "edge3": "int64"}'
# 注意:目前仅支持int64和timestamp类型的_ts值。
# 注意:用户使用timestamp类型的_ts值时,需要给出其时间格式。
rank_type = '{"knows": "timestamp"}'
# unix时间戳类型_ts列的格式。
# 注意:用户需要提供一个json格式的参数,如果该参数值设定为时间戳类型,则时间戳的精度仅支持精确到毫秒级别。
# 例如'{"edge1" : "yyyy-MM-dd", "edge2" : "MM-dd-yyyy HH:mm:ss.SSS"}'
# 可参考Spark官方文档
rank_timestamp_format = '{"knows" : "yyyy-MM-dd HH:mm:ss.SSS"}'
# 设置python脚本路径
python_path = "/app/spark"
# 修改生成sst文件的owner信息
chown_owner = ""
# 设置Spark临时文件的存放路径,请确保为该路径分配充足的磁盘空间,否则在运行中可能会出现磁盘空间不足的错误
spark_dir = "/tmp/spark"

# CSV文件命名格式,“normal”格式下,文件使用点、边名称命名,例如
# vertexName.csv 或者 srcVertexName_edgeName_dstVertexName.csv
# “ldbc”格式下,在名称后增加_0_0后缀,例如
# vertexName_0_0.csv 或者 srcVertexName_edgeName_dstVertexName_0_0.csv
# 注意:大小写敏感
csv_name_format = "ldbc" # or "normal"
# 设置CSV文件分隔符,仅支持单个字符
csv_delimiter = "|"
# 设置CSV文件包裹符,仅支持单个字符
csv_quote = '"'
# 设置CSV文件转义符,仅支持单个字符
csv_escape = "\\"
# 设置CSV文件是否含有列名,目前还不支持mapping功能,请为CSV文件添加正确的列名
csv_has_headers = true

# 完成导入的各步骤,true表示执行。
do_sort_csv = true
do_encode_kv = true
do_gen_index = true
do_upload_and_bulkload = true
# 设置是否回收临时文件,若设置为“true”则导入过程中产生的临时文件都会被清理
remove_tmp_dir = true

[upload]
# 设置待导入数据的ArcGraph服务器的IP地址,需列出集群中所有机器的IP,多个地址之间需使用“;”分隔
server_addresses = ""
# 设置待导入数据的ArcGraph的用户名,若有多个用户名,则各用户名之间需使用“;”分隔
server_usernames = ""
# 设置待导入数据的ArcGraph的密码,若有多个密码,则各密码之间需使用“;”分隔
server_passwords = ""

[log]
# 设置是否将日志输出到控制台
enable_console = true
# 设置是否将日志输出到文件
enable_file = false
# 设置日志文件输出路径
file_path = "./tools_log"
# 设置日志文件名
file_name = "tool.log"
# 设置日志是否开启Ansi
enable_ansi = true
# 设置日志级别
env = """\
info,\
tools=info\
"""

导入数据

前提条件
  • 在导入数据前,请确认已知待导入数据的 ArcGraph 图数据库服务器的 IP 地址、登录用户名、密码以及数据导入目录。
  • 在导入数据前,请确认 ArcGraph 图数据库中已创建了与待导入数据相匹配的图 Schema,并确保该图内无对应的图数据。
  • CSV 文件命名规则如下,请确保 CSV 文件的命名和格式符合此规则且注意大小写敏感,否则可能会导致数据导入失败。
    • 点数据文件名
      • csv_name_format 设置为 ldbc 时,文件命名应遵循“点类型名称_0_0.csv”的格式,例如,Person_0_0.csv。
      • csv_name_format 设置为 normal 时,命名必须符合“点类型名称.csv”的格式。例如,Person.csv。
    • 边数据文件名
      • csv_name_format 设置为 ldbc 时,文件命名应遵循“起始点类型名称_边类型名称_目标点类型名称_0_0.csv”的格式,例如,Person_knows_Books_0_0.csv。
      • csv_name_format 设置为 normal 时,文件命名应遵循“起始点类型名称_边类型名称_目标点类型名称.csv”的格式。例如,Person_knows_Books.csv。
  • 请确保 CSV 格式正确,不包含多余空格,且列名与图 Schema 属性精确匹配,顺序不作强制要求。其中,点数据 CSV 文件的首列须为 PRIMARY KEY 属性,边数据 CSV 文件的前两列依次为起始点与目标点的 PRIMARY KEY 属性。
导入数据

在终端中执行以下命令以启动工具并完成数据导入,命令如下:

./arc_direct_load

数据导入完成后,为了将数据加载到图中,需要手动执行 LOAD GRAPH 操作。请在 ArcGraph 客户端中执行如下命令,将数据加载到指定图中,命令如下:

ALTER SYSTEM LOAD GRAPH <graph_name>;

示例

  1. 请确认在 ArcGraph 中已创建所需的图 Schema,创建语句示例如下。通过 SHOW CREATE 语句可查看创建语句,详情请参见 SHOW CREATE 章节。
CREATE GRAPH IF NOT EXISTS data_test
CHARSET = utf8
COMMENT = '新图';

CREATE VERTEX IF NOT EXISTS person
(
PRIMARY KEY id INT(64),
name STRING COMMENT '姓名',
age INT(32) NOT NULL DEFAULT '16' COMMENT '年龄',
INDEX name_index(name) UNIQUE
)
COMMENT = '测试Vertex';

CREATE EDGE knows (
name string NOT NULL COMMENT '知道',
since INT(64) default '2020' COMMENT '开始时间',
FROM person TO person,
INDEX index_a(name)
)
COMMENT = '测试Edge';
  1. 准备数据的 CSV 文件。文件内容如下。
    • 点数据文件,命名为“person_0_0.csv”并存放在“./tmp/sf0.1”目录下。
       id|name|age
      1|John|25
      2|Mary|24
      3|Jerry|23
      4|Lihua|22
      5|Xiaoli|21
    • 边数据文件,命名为“person_knows_person_0_0.csv”并保存在“./tmp/sf0.1”目录下。
      person.id|person.id|name|since
      1|5|'知道'|2020
      2|4|'知道'|2021
      3|5|'知道'|2022
  2. 创建导入数据时的 .toml 配置文件并命名为“tools_config.toml”。文件具体内容示例如下:
    [server]
    # ArcGraph user name.
    user = "arcgraph"
    # ArcGraph user password.
    password = "arcgraph"
    # ArcGraph server ip addresses, split by ';'.
    endpoints = "127.0.0.1:8182"

    [performance]
    # Thread pool size, also the number of spark tasks.
    # Usually equal to the number of CPU cores.
    pool_size = 20
    # Amount of memory to use for driver process.
    # Note: not enough driver memory will leads to OOM.
    spark_driver_memory = "5g"

    [import]
    # Running mode, 'local' mode means arc_direct_load and the only server are running
    # on same file system.
    # 'remote' mode means arc_direct_load and other servers are running on different file
    # systems thus generated sst files need to be scp to servers.
    backend = "local" # or "remote"
    # Graph name.
    graph_name = "data_test"
    # CSV root directory, which should be on the same file system with tool.
    # NOTE: directories under this root directory will be ignored.
    client_data_dir = "./tmp/sf0.1"
    # Servers' import path that is configered in servers' config.
    server_import_path = "/tmp/import"
    # Directory to save sorted csv files produced by spark.
    # Make sure to leave enough disk space.
    sorted_csv_dir = "/tmp/sorted_csv"
    # Directory to save hotspot vertexes.
    # Note: providing hotspot files helps to increase query performance.
    hotspot_dir = "/tmp/hotspot"
    # Directory to save temporary files.
    # If exists, tool will remove it and create a new one.
    # It will be removed in the end.
    # Temporary files like sst files will take up a lot of disk space.
    # Make sure to leave enough disk space.
    tmp_dir = "/tmp/load_tmp"
    # Directory to keep error rows: duplicate rows and dangling edges.
    error_dir = "/tmp/load_error"
    # If true, spark will check pk duplicate and response according to
    # on_duplicate config.
    # Note: if false, it is users' responsibility to ensure the uniqueness
    # of primary key.
    check_duplicate = true
    # The method to resolve the conflicting data, "error" or "ignore".
    # "error" method will stop importing job immediately when duplicate
    # rows appear, while "ignore" will always keep the first row appearing
    # in data files and record removed rows at error directory for later processing.
    on_duplicate = "error"
    # If true, import reverse edge data.
    reverse_edge = true
    # Datatype of given rank value.
    # Note: user should provide json format string.
    # E.g. '{"edge1" : "timestamp", "edge2": "timestamp", "edge3": "int64"}'
    # Note: only support "int64" and "timestamp" currently.
    # Note: user must provide format for edges using timestamp type rank.
    rank_type = '{"knows": "timestamp"}'
    # Time format of timestamp type rank.
    # Note: user should provide json format string.
    # E.g. '{"edge1" : "yyyy-MM-dd", "edge2" : "MM-dd-yyyy HH:mm:ss.SSS"}'
    # Please check datetime patterns at
    # Please refer to the official Spark documentation
    rank_timestamp_format = '{"knows" : "yyyy-MM-dd HH:mm:ss.SSS"}'
    # Path to python scripts directory.
    python_path = "./spark"
    # Change owner of upload path.
    chown_owner = ""
    # Directory to use for "scratch" space in Spark,
    # including map output files and RDDs that get stored on disk.
    # This should be on a fast, local disk in your system.
    spark_dir = "/tmp/spark"

    # File name format, for example:
    # 'normal' vertex file name: vertexName.csv
    # 'normal' edge file name: srcVertexName_edgeName_dstVertexName.csv
    # NOTE: CASE SENSITIVE!
    # For 'ldbc' format, a '_0_0' suffix is added to file name, like
    # vertexName_0_0.csv and srcVertexName_edgeName_dstVertexName_0_0.csv
    csv_name_format = "ldbc" # or "normal"
    # The filed delimiter to use when parsing CSV. An empty string means using default ","
    # Multiple character combinations are NOT supported.
    csv_delimiter = "|"
    # The quote character to use when parsing CSV. An empty string means use default b'"'.
    # Multiple character combinations are NOT supported.
    csv_quote = '"'
    # The escape character to use when parsing CSV. No default value.
    # Drop this line if you don't want this config.
    csv_escape = "\\"
    # True means CSV has headers. Schema mapping will be supported in the future.
    csv_has_headers = true

    # True means doing.
    # The subsequent steps can be executed independently
    # only if the previous steps are completed with the same configuration and schema.
    do_sort_csv = true
    do_encode_kv = true
    do_gen_index = true
    do_upload_and_bulkload = true
    # Garbage collect temperoray files in the end.
    remove_tmp_dir = true

    [upload]
    # Target server addresses which are split by ';'.
    server_addresses = "127.0.0.1:8182"
    # Target server user names which are split by ';'.
    server_usernames = "arcgraph"
    # Target server passwords which are split by ';'.
    server_passwords = "arcgraph"

    [log]
    # Write log to stdout if true.
    enable_console = true
    # Write log to file if true.
    enable_file = false
    # Log file directory.
    file_path = "./tools_log"
    # Log file name.
    file_name = "tool.log"
    # Enable ansi escape code.
    enable_ansi = true
    # Env is used to config particular package's log level.
    env = """\
    info,\
    tools=info\
    """
  3. 在终端中执行如下命令,导入数据。
    • 若将配置文件直接放置在 arc_direct_load 工具的安装包路径下,您可以直接在终端中执行以下命令进行数据导入:
      ./arc_direct_load
    • 若将配置文件放置在其他指定路径下,您需要使用 -c 参数来指定配置文件的路径,并在终端中执行以下命令:
      ./arc_direct_load -c ./arc_direct_load/tools_config.toml
  4. 在 ArcGraph 客户端中执行如下命令,加载导入的数据。
    ALTER SYSTEM LOAD GRAPH data_test;
  5. 加载数据成功后,在 ArcGraph 图数据库中执行如下语句验证数据导入情况。
    • 查看图

      SHOW GRAPHS;
    • 在图中查询点数据

      MATCH (n) RETURN n;
    • 在图中查询边数据

      MATCH (n:person)-[r]->(person)
      RETURN r;

数据验证

在使用 arc_direct_load 物理导入工具导入数据的过程中,为了确保数据的准确性和完整性,我们的工具提供了多种异常数据检测机制。以下是详细的检测内容。

重复数据检测
在配置文件中设置 check_duplicate = true ,开启重复数据检测功能,开启后工具会自动根据点数据的主键以及边数据的起始点和目标点主键进行重复数据的检测。根据设定的重复处理参数,工具会对应执行以下操作:

  • on_duplicate = "error" 时,在检测到重复数据时,立即停止整个导入过程。
  • on_duplicate = "ignore" 时,仅导入首次出现的数据记录,并将后续出现的重复数据记录汇总到异常数据目录中,以便后续处理和分析。

悬挂边检测

工具会自动执行悬挂边的检测。悬挂边,即没有有效起始点或目标点的边数据,会被自动识别并输出到异常数据目录下。请注意,当前版本在导入过程中仍可能存在导入悬挂边的情况,我们正在持续优化此功能,以完全避免悬挂边的导入。

类型错误检测

在导入过程中,工具会检查每条数据记录的类型,确保其与 ArcGraph 图数据库中的图 Schema 定义相符。若发现数据类型与 Schema 不一致导致编码失败,工具会记录详细的错误日志,并跳过该条数据,以确保其他数据能够正常导入。

性能调优

要显著提升物理导入性能,首要且高效的途径是提升服务器节点性能,特别是针对 CPU、内存以及 sorted_csv_dir 所在存储设备的性能优化。同时,结合当前服务器节点硬件配置情况,合理设置配置文件 performance 模块中的参数,以确保资源得到充分利用,从而实现性能的最大化提升。

示例

[performance]
# Thread pool size, also the number of spark tasks.
# Usually equal to the number of CPU cores.
pool_size = 20
# Amount of memory to use for driver process.
# Note: not enough driver memory will leads to OOM.
spark_driver_memory = "5g"

详细说明

  • pool_size:该参数决定了排序与编码过程的并发执行能力,建议根据逻辑 CPU 核心数来设置,以达到最佳性能。
  • spark_driver_memory:若该参数设置过小,则可能导致 Spark Driver 进程在执行过程中因内存溢出而失败。因此,建议统计每个边文件及其起始点、目标点文件的大小之和,并确定其中的最大值,设置的参数值应高于这个最大值,以避免内存不足。