数据迁移
备份恢复工具
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 的工作模式，包括 backup 和 restore 两种模式。
|
-name | 指定操作的备份目录名称。
|
-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”的备份目录中。 具体操作步骤如下：
-
根据实际情况，从 ArcGraph 图数据库集群中选择一个合适的服务器节点，并进入该服务器节点所运行的 Docker 容器中。
该服务器节点的 IP 地址为: 127.0.0.1, 端口为: 8182，用户名和密码为：arcgraph。 -
执行如下命令，备份数据。
./arc_br --action backup --name arc_br_1716290038 --user arcgraph --password arcgraph -e 127.0.0.1:8182 -
返回结果中有如下字段，表示数据已经备份成功。
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 图数据库集群中。具体操作步骤如下：
-
进入 ArcGraph 图数据库服务器节点所运行的 Docker 容器中。
该服务器节点的 IP 地址为: 127.0.0.1, 端口为: 8182，用户名和密码为：arcgraph。 -
执行如下命令，恢复数据。
./arc_br --action restore --name arc_br_1716290038 --user arcgraph --password arcgraph -e 127.0.0.1:8182 -
返回结果中有如下字段，表示数据已经恢复成功。
restore success, name: arc_br_1716290038
示例 2
使用 arc_br 工具对敏捷版 ArcGraph 图数据库（即集群仅包含三个服务器节点）执行数据恢复操作，恢复备份目录“arc_br_1716290038”中的数据至 ArcGraph 图数据库集群中。具体操作步骤如下：
-
进入 ArcGraph 图数据库服务器节点所运行的 Docker 容器中。
该服务器节点的 IP 地址为: 127.0.0.1, 端口为: 8182，用户名和密码为：arcgraph。 -
执行如下命令，恢复数据。
./arc_br --action restore --name arc_br_1716290038 --user arcgraph --password arcgraph -e 127.0.0.1:8182 -
返回结果中有如下字段，表示该服务器节点的数据已经成功恢复。
restore success, name: arc_br_1716290038 -
对集群中另外两个服务器节点执行步骤 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.3 | v2.1.3 |
| v2.1.2 | v2.1.2 |
| v2.1.1 | v2.1.1 |
| v2.1.0_ha | v2.1.0_ha |
| v2.1.0 | v2.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 | 指定操作的默认行为，支持设置为 insert、upsert 和 merge，默认设置为 insert。- insert：插入数据，用于向数据库中插入新数据，如果出现主键冲突，则导入会出错。 - upsert：更新已有数据，新的属性值将覆盖原有记录。例如，如果待导入对象包含属性 A 和 B，而本次操作导入的属性是 B 和 C，则最终结果将只包含属性 B 和 C。 - merge：合并数据，其中没有被指定写入的属性将会保持不变。例如，如 果待导入对象包含属性 A 和 B，而本次操作导入的属性是 B 和 C，则最终结果将包含属性 A、B 和 C。请注意，仅 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 | 用于指定通信地址，支持设置为 true 和 false，默认设置为 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参数值为upsert或merge，程序将执行对应操作，不会报错退出，详情请参见 参数介绍 章节。 - 如果指定路径下存在多个 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 文件导入到指定的图中。具体操作步骤如下：
-
准备创建图 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”。
-
准备数据的 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
- 点数据文件，命名为“person_1_1.csv”并存放在“testdata/data”目录下。
-
打开命令行终端，执行如下命令，将目录“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 ""; -
导入成功后，在 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;
高级导入
通过结合配置文件和命令行语句，用户可以在配置文件中灵活地设定导入过程中的各种参数和条件。这种高级导入方式为用户提供了更大的灵活性和定制性，从而满足各种复杂的导入需求。
示例
-
创建导入数据时的 .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/" -
（可选）在配置文件中设置导入规则，即设置导入数据的属性或点边属性的映射关系。如未设置规则，默认导入全部数据。
- 设置点数据的导入规则
# 此处设置需要导入的点类型及属性，可以设置多个
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文件中的列索引 -
在终端中执行如下语句，导入数据。
- 执行下列命令行语句自动创建图 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;
- 执行下列命令行语句自动创建图 Schema 并导入数据。
数据导出
在图数据库中，数据导出同样是一个关键环节，尤其在需要共享数据或迁移数据时。通过有效的数据导出，用户可以确保数据的完整性和准确性，同时为其他应用或系统提供可靠的数据源。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;
高级导出
通过配置文件与命令行语句相结合的方式导出数据。这种方式的优点在于，它为用户提供了配置具体导出规则的灵活性，允许选择要导出的点类型/边类型以及其属性列表，并应用过滤规则，使用户可以更加精确地控制导出的数据内容，以满足不同的需求和场景。
示例
-
创建导出数据时的配置文件。自定义配置文件名称为“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" -
（可选）在配置文件中设置导出规则，即设置导出数据时的过滤条件。如未设置规则，默认导出全部数据。
- 设置点数据的导出规则
# 设置图中将要导出的点类型
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"
- 设置点数据的导出规则
-
在终端中执行如下语句，导出数据。
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 工具能够顺利安装并高效运行，请确保您的环境满足以下要求：
- 操作系统及架构要求
- 操作系统：Linux
- 架构：ARM64 或 X86_64
- 硬件要求
- 推荐配置：32 核以上 CPU， 64GiB 以上内存
- 存储空间：建议为
sorted_csv_dir和tmp_dir分别预留至少原数据大小 1.5 倍的存储空间
- 网络要求
- 建议使用 10 Gbps 以太网卡
- 软件依赖
若您选择本地安装 arc_direct_load，还需确保系统中已安装以下软件依赖：- Python 3.12
- Java 11 及以上版本
- Pyspark 3.5.1
- Spark/scala 3.5.1/2.13
不同版本对安装环境的要求可能略有不同，请以实际情况为准。其中：
sorted_csv_dir仅 arc_direct_load < v2.1.2 版本涉及。- Spark/scala 3.5.1/2.13 仅 arc_direct_load >= v2.1.2 版本涉及。
安装 arc_direct_load
arc_direct_load 支持 Docker 和本地两种安装方式，以满足不同用户的安装需求。本章节将以 arc_direct_load v2.1.2 版本在 X86_64 架构上的安装为例介绍 arc_direct_load 的安装流程。关于 arc_direct_load 各版本的 Docker 镜像信息、安装包下载链接及兼容性说明，请参考 版本信息与兼容性 章节。
Docker 安装（推荐）
在进行 Docker 安装之前，请确保您的系统中已安装并成功运行 Docker。
-
在终端中运行容器并执行以下命令拉取 arc_direct_load 的 Docker 镜像。
docker pull docker-reg.infra.fabarta.com:5000/fabarta/arc_direct_load:v2.1.2-x86_64操作前请联系 我们 获取 Docker 镜像的拉取权限及具体信息。
-
运行 Docker 容器，执行以下命令安装并启动 arc_direct_load 工具。
为便于数据访问，在启动 arc_direct_load 工具时，建议将本地数据目录挂载到容器中。docker run -d --name direct-load \
--net=host \
-v /data:/data \
docker-reg.infra.fabarta.com:5000/fabarta/arc_direct_load:v2.1.2-x86_64
本地安装
-
请参考 版本 信息与兼容性 章节，获取 arc_direct_load v2.1.2 安装包。
-
在终端中运行以下命令，解压安装包。
tar -zxvf arc_direct_load.tar.gz -
打开终端，在 Python 3.12 环境中，运行以下命令安装 arc_direct_load v2.1.2 及其依赖项。
pip3 install --no-cache-dir -r arc_direct_load/spark/requirements.txt
参数列表
arc_direct_load 支持的参数如下：
| 参数 | 说明 |
|---|---|
-c | 用于指定操作所需的配置文件的存放路径及文件名。 |
使用 arc_direct_load
前提条件
- 在导入数据前，请确认已知 ArcGraph 图数据库服务器的 IP 地址、登录用户名、密码以及数据导入目录等相关信息。
- 在导入数据前，请确认 ArcGraph 图数据库中已创建了相应的图 Schema 且该图内无对应的图数据。
使用限制
在使用 arc_direct_load 工具进行数据导入时，请遵循以下限制与规范，以确保数据导入过程的顺利进行和数据的准确性。
- 不支持 DDL 和 DML 操作
在数据导入过程中，不支持对目标图进行 DDL 和 DML 操作，否则可能会导致导入操作停止或失败。 - 避免 DQL 操作
在数据导入过程中，不建议对目标图进行 DQL 操作。因为数据可能不稳定，返回结果可能不准确。 - 数据导入要求
- 仅支持对空图进行首次数据导入操作，需一次性完成，不支持分多次导入，后续如有需要，可使用 逻辑导入导出工具 增量导入数据。
- 导入边数据时，边数据需与其对应的起始点、目标点数据同时导入。
- 仅支持导入与图 Schema 相匹配的 CSV 文件，多余文件将被忽略。
- 目前暂不支持直接导入边的索引数据和包含换行符的跨行数据。若数据中包含换行符，arc_direct_load 将视为格式错误并予以剔除，请确保数据格式的正确性。
- arc_direct_load 在 v2.1.0 和 v2.1.1 版本中不支持通过
default值填充缺失数据，但从 v2.1.2 版本开始，此限制已解除。 - 若数据中含有
_ts属性且该属性值为时间戳类型，则该时间戳的精度仅支持精确到毫秒级别。
- 及时备份
使用 arc_direct_load 工具导入的数据不支持通过增量恢复方式恢复数据，所以建议在数据导入完成后执行一次完整的数据备份操作。 - CSV 格式要求
- CSV 文件的命名需与配置文件中
csv_name_format参数的设置相匹配，请注意命名大小写敏感。 - 请确保 CSV 格式正确，不包含多余空格，且列名与图 Schema 属性精确匹配，顺序不作强制要求。其中，点数据 CSV 文件的首列须为
PRIMARY KEY属性，边数据 CSV 文件的前两列依次为起始点与目标点的PRIMARY KEY属性。
- CSV 文件的命名需与配置文件中
配置参数
用户可以从安装包或 Docker 镜像中获取 arc_direct_load 工具的配置文件 tools_config.toml。通过灵活设置此配置文件中的各项参数，满足不同场景下的数据导入需求。配置文件中的主要配置参数如下，对于其他非关键性参数，若无特别需求，建议使用默认值以简化配置流程。请注意，不同版本的配置参数可能略有不同，请以实际为准。
主要参数
| 参数 | 说明 |
|---|---|
user | 设置 ArcGraph 图数据库的用户名。 |
password | 设置 ArcGraph 图数据库的密码。 |
endpoints | 设置 ArcGraph 图数据库服务器的 IP 地址，需要列出集群中所有服务器的 IP 地址。多个地址之间，请根据 arc_direct_load 的版本（v2.1.2 及以上版本使用英文逗号“,”分隔，否则使用英文分号“;”分隔）进行规范分隔。 |
graph_name | 设置待导入数据的目标图名称，需与 ArcGraph 图数据库中的图名称一致。 |
csv_name_format | 设置 CSV 文件的命名格式，支持以下两种模式。
|
csv_delimiter | 设置 CSV 文件分隔符，仅支持使用单个字符作为分隔符，可选取任意单个字符设置。 |
backend | 设置 ArcGraph 图数据库的运行模式。支持以下两种运行模式。
|
client_data_dir | 设置待导入 CSV 文件的存放路径。 说明： arc_direct_load 不 会递归搜索该路径下其他文件夹。 |
server_addresses | 设置待导入数据的 ArcGraph 图数据库服务器的 IP 地址，需要列出集群中所有服务器的 IP 地址。多个地址之间，请根据 arc_direct_load 的版本（v2.1.2 及以上版本使用英文逗号“,”分隔，否则使用英文分号“;”分隔）进行规范分隔。 |
server_usernames | 设置待导入数据的 ArcGraph 图数据库服务器的用户名，需要列出集群中所有服务器的用户名。多个用户名之间，请根据 arc_direct_load 的版本（v2.1.2 及以上版本使用英文逗号“,”分隔，否则使用英文分号“;”分隔）进行规范分隔。 |
server_passwords | 设置待导入数据的 ArcGraph 图数据库服务器的密码，需要列出集群中所有服务器的登录密码。多个密码之间，请根据 arc_direct_load 的版本（v2.1.2 及以上版本使用英文逗号“,”分隔，否则使用英文分号“;”分隔）进行规范分隔。 |
数据验证参数
arc_direct_load 提供多种数据验证参数，以确保数据的准确性和完整性。请根据实际情况设置这些参数，以便 arc_direct_load 在导入数据的过程中检测每条数据并根据预设的处理策略有效处理异常数据。参数及其支持的处理策略说明如下：
| 参数 | 说明 | 处理策略 |
|---|---|---|
on_duplicate | 用于设置检测到重复数据时的处理策略。arc_direct_load 基于点数据主键、边数据的起始点和目标点主键以及 _ts 属性来判断该数据是否为重复数据。说明： 在 arc_direct_load < v2.1.2 的版本中，请确认已启用重复数据检测（即 check_duplicate = true），否则该设置不生效。 | 支持设置如下处理策略：
|
on_dangling | 用于设置检测到悬挂边数据（即没有有效起始点或目标点的边数据）时的处理策略。 说明： 使用 arc_direct_load < v2.1.2 版本导入数据时可能会偶现悬挂边问题，推荐升级至 arc_direct_load >= v2.1.2 版本以避免此问题。 | |
on_corrupt | 用于设置检测到数据格式错误（即数据字段数量与图 Schema 定义不匹配）时的处理策略。 说明： 仅 arc_direct_load >= v2.1.2 版本支持该参数。 | |
on_missing | 用于设置检测到不符合图 Schema 要求的非法空值数据时的处理策略。当数据验证过程中发现某属性按图 Schema 要求不应为空，但实际为空时，若图 Schema 中设置了 default 值，则将其填充到数据中，否则 将数据记录为非法空值数据。说明：
|
性能调优相关参数
要显著提升物理导入性能，最直接有效的办法是升级其所在服务器节点的性能，特别是对 CPU、内存和存储设备的性能优化。同时，结合当前服务器节点硬件配置情况，合理设置配置文件中性能调优相关的参数，以确保资源得到充分利用，从而实现性能的最大化提升。
| 参数 | 说明 |
|---|---|
pool_size | 该参数决定了排序与编码过程的并发执行能力，建议根据逻辑 CPU 核心数来设置，以达到最佳性能。 |
spark_driver_memory | 设置分配给 Spark Driver 进程的内存大小。若该参数设置过小，则可能导致 Spark Driver 进程在执行过程中因内存溢出而失败。因此，建议统计边文件及其起始点、目标点文件的大小总和，确定其中的最大值，设置的参数值应高于这个最大值，以确保分配的内存充足，从而避免内存溢出的问题。 说明： 自 arc_direct_load v2.1.2 版本起，该参数已更名为 driver_memory。 |
spark_executor_memory | 设置分配给 Spark Executor 进 程的内存大小。 说明： 自 arc_direct_load v2.1.2 版本起，该参数已更名为 executor_memory。 |
num_executors | 设置 Spark Executor 进程的数目。 说明： 仅 arc_direct_load >=v2.1.2 版本支持此参数。 |
导入数据
在终端中执行以下命令以启动工具并完成数据导入，命令如下：
./arc_direct_load
arc_direct_load 工具正常结束即表明数据已成功传输并导入至集群所有机器。若工具报错失败，则整个导入过程视为失败，即使部分机器导入成功，数据亦不可用。请检查错误原因后重新导入。
加载数据
数据导入完成后，为了将数据加载到图中，需要手动执行 LOAD GRAPH 操作。请在 ArcGraph 客户端中执行如下命令，将数据加载到指定图中，命令如下：
ALTER SYSTEM LOAD GRAPH <graph_name>;
示例
-
请确认在 ArcGraph 中已创建所需的图 Schema，创建语句示例如下。通过
SHOW CREATE语句可查看创建语句，详情请参见 SHOW CREATE 章节。CREATE GRAPH IF NOT EXISTS LDBC_SNB_0_1
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'; -
准备数据的 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
- 点数据文件，命名为“person_0_0.csv”并存放在“./tmp/sf0.1”目录下。
-
根据实际情况，在
tools_config.toml配置文件中配置相关参数。-
配置基本参数。
user = "arcgraph"
password = "arcgraph"
endpoints = "127.0.0.1:8182"
graph_name = "LDBC_SNB_0_1"
csv_name_format = "ldbc"
csv_delimiter = "|"
backend = "local"
client_data_dir = "/tmp/sf0.1"
server_addresses = "127.0.0.1:8182"
server_usernames = "arcgraph"
server_passwords = "arcgraph" -
（可选）配置数据验证参数。
on_corrupt = "ignore"
on_missing = "ignore"
on_duplicate = "ignore"
on_dangling = "ignore" -
（可选）配置性能调优参数。
pool_size = 20
driver_memory = "20g"
executor_memory = "2g"
num_executors = "20"
-
-
在终端中执行如下命令，导入数据。
- 若将配置文件直接放置在 arc_direct_load 工具的安装包路径下，您可以直接在终端中执行以下命令进行数据导入：
./arc_direct_load - 若将配置文件放置在其他指定路径下，您需要使用
-c参数来指定配置文件的路径，并在终端中执行以下命令：./arc_direct_load -c ./arc_direct_load/tools_config.toml
- 若将配置文件直接放置在 arc_direct_load 工具的安装包路径下，您可以直接在终端中执行以下命令进行数据导入：
-
在 ArcGraph 客户端中执行如下命令，加载导入的数据。
ALTER SYSTEM LOAD GRAPH LDBC_SNB_0_1; -
加载数据成功后，在 ArcGraph 图数据库中执行如下语句验证数据导入情况。
-
查看图
SHOW GRAPHS; -
在图中查询点数据
MATCH (n) RETURN n; -
在图中查询边数据
MATCH (n:person)-[r]->(person)
RETURN r;
-
版本信息与兼容性
版本信息
arc_direct_load 各版本的 Docker 镜像信息和安装包下载链接如下：
| 版本号 | Docker 镜像 | 安装包 |
|---|---|---|
| v2.1.3 |
| 下载链接 |
| v2.1.2 |
| 下载链接 |
| v2.1.1 |
| 下载链接 |
| v2.1.0 |
| 下载链接 |
版本兼容性
为确保用户能够正确选择和配置与 ArcGraph 图数据库兼容的 arc_direct_load 工具，以下提供了 ArcGraph 图数据库与 arc_direct_load 不同版本之间的兼容性列表。
| ArcGraph 图数据库 | arc_direct_load |
|---|---|
| v2.1.3 | v2.1.3 |
| v2.1.2 | v2.1.2 |
| v2.1.1 | v2.1.1 |
| 2.1.0_ha | v2.1.0 |
| v2.1.0 | 不支持 |