2.3

执行加载作业

清除和初始化图存储

清除系统有两个动作：清除数据，以及清除目录中的图数据库Schema定义。 执行这两种操作有两个不同的命令。

清除图存储

只适用于超级用户

CLEAR GRAPH STORE命令清除图存储（图数据库）中的所有数据。 默认情况下，系统会要求用户确认删除动作。若要跳过确认直接强制执行清除操作，可使用-HARD选项，例：

CLEAR GRAPH STORE -HARD

该命令清除图存储中的数据但不会影响图数据库Schema。

1.请十分谨慎地使用-HARD选项。 该操作不可撤销。 -HARD必须全部大写。

2. CLEAR GRAPH STORE和终止所有的TigerGraph服务器（包括GPE，GSE，RESTPP，Kafka和Zookeeper）。

3.加载作业和查询会被丢弃。

全部丢弃

只适用于超级用户

DROP ALL语句清除图存储和目录中的所有定义：包括顶点类，边缘类，图类，作业和查询。

执行加载作业

执行加载作业即执行已经安装的加载作业。 作业从源数据读取每一行，将每行解析为数据token，并应用加载规则和条件，创建要存储在图形数据存储中的新顶点和边的实例。

TigerGraph 2.0版本引入了增强的数据加载功能，该改进对CREATE和RUN语句略有修改。 之前RUN JOB语法中用于v1.x在线加载和离线加载的部分仍然支持。 此外，还可以通过直接向REST ++服务器提交HTTP请求来执行加载作业。

执行加载作业的语法

不推荐使用v2.0版本之前的 RUN JOB语法

从v2.0开始，RUN LOADING JOB是所有执行加载作业的首选语法。 2.0版本以前的联机发布作业和脱机加载作业的语法现在仍然支持，但不建议使用。

并发加载作业的RUN LOADING JOB语法
RUN LOADING JOB [-noprint] [-dryrun] [-n [i],j] jobname [ USING filevar [="filepath_string"][, filevar [="filepath_string"]]* [, CONCURRENCY="cnum"][,BATCH_SIZE="bnum"]]

请注意，该函数名中包含关键字LOADING。 这样做可以让用户和GSQL更清楚该作业是一个加载作业而不是其他类型的作业（例如SCHEMA_CHANGE JOB）。

提交并发加载作业时，会为其分配一个作业ID编号，该编号显示在GSQL控制台上。 用户可以使用此作业ID来引用作业，更新其状态，中止作业或重新开始作业。 这些操作将在本节的后面介绍。

可选参数

-noprint

默认情况下，本命令会在加载运行时打印数行状态信息。

但如果包含了-noprint选项，则作业运行时的输出信息会省略进度和摘要的详情，但仍将显示作业ID和日志文件的位置。

例：使用-noprint参数后输出的简要信息
Kick off the following job:
 JobName: load_videoE, jobid: gsql_demo_m1.1525091090494
 Loading log: '/usr/local/tigergraph/logs/restpp/restpp_loader_logs/gsql_demo/gsql_demo_m1.1525091090494.log'

-dryrun

如果使用-dryrun参数，系统将读取数据文件并按作业指示处理数据，但不会将任何数据加载到图形中。 此选项常用作诊断工具。

-n [i], j

-n选项将加载作业限制为仅处理每个输入数据文件的一部分行。 -n的两种格式各包一个或两个参数。 例如，-n 50表示读取第1行至第50行。

-n 10, 50 表示读取第10行到第50行。符号$被解释为“最后一行”，因此-n 10,$ 表示从第10行读到结尾。

filevar list

可选的USING子句可以包含一个文件变量列表。用户可以选择为每个文件变量分配一个filepath_string，遵循与CREATE LOADING JOB相同的格式。 此文件变量列表定义了，执行加载作业的哪个部分，或使用哪些数据文件。

  1. 由于在编译加载作业时，每个filevar和filepath_string都生成了一个RESTPP终止点。由此，加载作业便可以按照不同部分单独执行。 执行RUN LOADING JOB时，仅使用USING子句中提到filevar或文件标识符（“__GSQL_FILENAME_n__”）的终止点。 但如果省略了USING子句，则系统将运行整个加载作业。

  2. 如果执行时给出了filepath_string，它将覆盖加载作业中定义的filepath_string。 如果在加载作业或RUN LOADING JOB语句中未为特定filevar分配filepath_string，则系统会报告错误并退出作业。

CONCURRENCY

CONCURRENCY参数定义了加载作业可以发送到GPE的最大并发请求数。 默认值为256。

BATCH_SIZE

BATCH_SIZE参数定义了发送到GPE的每个并发请求中包含的数据行数。 默认值为1024。

以REST请求方式执行加载作业

执行加载作业的另一种方法是向REST ++服务器的POST /ddl/<graph_name> 端点提交HTTP请求。 由于REST ++服务器可以更直接地访问图形处理引擎，因此比GSQL中的RUN LOADING JOB语句速度更快。

执行CREATE LOADING JOB语句块时，GSQL系统会为每个文件源创建一个REST端点。 因此，每个REST请求每次调用一个文件源。 运行整个加载作业可能需要多个REST请求。

Linux curl命令是发出HTTP请求的便捷方式。 如果数据量很小，可以直接在命令中写入数据字符串，并配合使用-d参数：

使用POST/dll终止点加载Curl/REST++的语法
curl -X POST -d "<data_string>" "http://<server_ip>:9000/ddl/<graph_name>?<parameters>?tag=<job_name>&filename=<filepath><&optional_parameters>

如果数据量比较大，则更好的办法是使用-data-binary参数应用数据文件名

使用POST/dll终止点加载Curl/REST++的语法
curl -X POST --data-binary @<data_filename> "http://<server_ip>:9000/ddl/<graph_name>?tag=<job_name>&filename=<filename_variable><&optional_parameters>

对于filepath_string，<filepath>应被替换为文件变量（来自DEFINE FILENAME语句）或基于位置的文件标识符（“__GSQL_FILENAME_n__”）。

有关发送REST ++请求的更多信息，请参阅RESTPP API用户指南RESTPP API User Guide 。

示例：下面的代码块显示了同一个加载作业的三个等效命令。 第一个使用gsql命令RUN JOB。 第二个使用Linux curl命令来支持HTTP请求，参数值放在URL的查询字符串中。 第三个通过curl命令的data payload -d选项给出参数值。

REST++ ddl 加载示例
# Case 1: Using GSQL
GSQL -g gsql_demo RUN LOADING JOB load_cf USING FILENAME="../cf/data/cf_data.csv"
 
# Case 2: Using REST++ Request with data in a file, where file1 is one of the filename variables defined in the loading job
curl -X POST --data-binary @data/cf_data.csv "http://localhost:9000/ddl/gsql_demo?&tag=load_cf&filename=file1&sep=,&eol=\n"
 
# Case 3: Using REST++ Request with data inline, where file1 is one of the filename variables defined in the loading job
curl -X POST -d
"id2,id1\nid2,id3\nid3,id1\nid3,id4\nid5,id1\nid5,id2\nid5,id4" "http://localhost:9000/ddl/gsql_demo?tag=load_cf&filename=file1&sep=,&eol=\n"

监控和管理加载作业

从v2.0开始，GSQL提供了命令用于监控加载作业状态，中止加载作业以及重新开始加载作业。

作业ID及其状态

当加载作业启动时，GSQL服务器会为其分配一个作业ID并显示给用户查看。 作业ID的格式通常是加载作业的名称加机器代号，后跟代码编号，例如gsql_demo_m1.1525091090494

例：SHOW LOADING STATUS的输出
Kick off the following job, i.e.
 JobName: load_test1, jobid: poc_graph_m1.1523663024967
 Loading log: '/home/tigergraph/tigergraph/logs/restpp/restpp_loader_logs/demo_graph/demo_graph_m1.1523663024967.log'
 
Job "demo_graph_m1.1523663024967" loading status
 
[RUNNING] m1 ( Finished: 3 / Total: 4 )
 [LOADING] /data/output/company.data
 [=============                        ]  20%, 200 kl/s
 [LOADED]
 +-------------------------------------------------------------------+
 |               FILENAME |   LOADED LINES |   AVG SPEED |   DURATION|
 | /data/output/movie.dat |            100 |     100 l/s |     1.00 s|
 |/data/output/person.dat |            100 |     100 l/s |     1.00 s|
 | /data/output/roles.dat |            200 |     200 l/s |     1.00 s|
 +-------------------------------------------------------------------+
[RUNNING] m2 ( Finished: 1 / Total: 2 )
 [LOADING] /data/output/company.data
 [==========================           ]  60%, 200 kl/s
 [LOADED]
 +-------------------------------------------------------------------+
 |               FILENAME |   LOADED LINES |   AVG SPEED |   DURATION|
 | /data/output/movie.dat |            100 |     100 l/s |     1.00 s|
 +-------------------------------------------------------------------+

默认情况下，活动加载作业将显示并定期更新其进度。 有两种方法可以禁止这些输出自动显示：

  1. 使用-noprint选项执行加载作业。

  2. 加载作业开始后键入CTRL + C，将停止继续显示进度的状态信息，但加载作业仍将继续。

SHOW LOADING JOB 的语法

命令SHOW LOADING JOB显示指定加载作业或所有当前作业的当前状态：

SHOW LOADING JOB 的语法
SHOW LOADING STATUS job_id|ALL

显示格式与RUN LOADING JOB命令的格式相同。 如果你不知道作业ID，但是知道作业名称或计算机名，则可以使用ALL选项查看活动的作业ID。

终止加载作业

命令ABORT LOADING JOB将中止指定的加载作业或所有活动的加载作业：

ABORT LOADING JOB 的语法
ABORT LOADING JOB job_id|ALL

输出中会显示已中止的加载作业。

ABORT LOADING JOB 的例子
gsql -g demo_graph "abort loading job all"
 
Job "demo_graph_m1.1519111662589" loading status
[ABORT_SUCCESS] m1
[SUMMARY] Finished: 0 / Total: 2
  +--------------------------------------------------------------------------------------+
  |                  FILENAME |   LOADED LINES |   AVG SPEED  |   DURATION |   PERCENTAGE|
  | /home/tigergraph/data.csv |       23901701 |     174 kl/s |   136.83 s |         65 %|
  |/home/tigergraph/data1.csv |              0 |        0 l/s |     0.00 s |          0 %|
  +--------------------------------------------------------------------------------------+
 
Job "demo_graph_m2.1519111662615" loading status
[ABORT_SUCCESS] m2
[SUMMARY] Finished: 0 / Total: 2
  +--------------------------------------------------------------------------------------+
  |                  FILENAME |   LOADED LINES |   AVG  SPEED |   DURATION |   PERCENTAGE|
  | /home/tigergraph/data.csv |       23860559 |     175 kl/s |   136.23 s |         65 %|
  |/home/tigergraph/data1.csv |              0 |        0 l/s |     0.00 s |          0 %|
  +--------------------------------------------------------------------------------------+

重新开始加载作业

命令RESUME LOADING JOB将重新开始先前由于某种原因未完成的作业。

RESUME LOADING JOB的语法
RESUME LOADING JOB job_id

如果要重启的作业已经完成，则此命令将不执行任何操作。 RESUME命令在上一次命令运行停止的地方继续开始， 也就是说，它不会把相同的数据加载两次。

RESUME LOADING JOB的例子
gsql -g demo_graph "RESUME LOADING JOB demo_graph_m1.1519111662589"
[RESUME_SUCCESS] m1
[MESSAGE] The current job got resummed

对加载作业进行检查和排错

每个加载作业都会创建一个日志文件。作业启动时会显示日志文件的位置。 通常，日志文件位于

<TigerGraph.root.dir>/logs/restpp/restpp_loader_logs/<graph_name>/<job_id>.log 处。

此文件包含以下信息，它们对大多数用户都是有价值的：

  • 加载作业的所有参数和选项设置

  • 实时输出状态信息的拷贝

  • 包含成功读取和解析的行数的统计报告

统计报告中包括了每种类型对象的创建数量，以及由于不同原因而无效的行的数目。 此报告还显示了是哪些行导致了错误。以下列表列出了报告中显示的统计信息。 统计数据有两种类型： 一个是文件层（行数），另一个是数据对象层（对象数量）。 如果错误发生在文件层，例如，某一行没有足够的列，则此加载作业中的所有LOAD语句都会跳过此行数据。 如果发生对象级错误或触发了失败条件，则只有相应报错的对象不被创建。即，该加载作业中的所有其他的对象仍然会被创建，只要它们没有发生对象级错误或没有触发相关失败条件。

文件级统计数

解释

Valid lines

源数据文件中合规的行数

Reject lines

被reject_line_rules拒绝的行数

Invalid Json format

不合规的JSON格式的行数

Not enough token

包含不完整列的行数

Oversize token

包含Token的行数。请上调tigergraph/dev/gdk/gsql/config文件的"OutputTokenBufferSize"参数

对象级统计数

解释

Valid Object

成功载入的对象数

No ID found

PRIMARY_ID为空的对象数

Invalid Attributes

由于属性的数据格式错误导致的不合规对象数

Invalid primary id

由于PRIMARY_ID的数据格式错误导致的不合规对象数

Incorrect fixed

binary length

由于数据长度与图数据库Schema中定义的长度不一致导致的不合规对象数

请注意，WHERE子句的失败不一定是个坏结果。 如果用户使用WHERE子句的意图仅是为了筛选出某些行，则必然会有一些行通过而另一些行报错。

例:

CREATE VERTEX movie (PRIMARY_ID id UINT, title STRING, country STRING COMPRESS, year UINT)
CREATE DIRECTED EDGE sequel_of (FROM movie, TO movie)
CREATE GRAPH movie_graph(*)
CREATE LOADING JOB load_movie FOR GRAPH movie_graph{
 DEFINE FILENAME f
 LOAD f TO VERTEX movie VALUES ($0, $1, $2, $3) WHERE to_int($3) < 2000;
}
RUN LOADING JOB load_movie USING f="movie.dat"
movie.dat
0,abc,USA,-1990
1,abc,CHN,1990
2,abc,CHN,1990
3,abc,FRA,2015
4,abc,FRA,2005
5,abc,USA,1990
6,abc,1990

上述加载作业会生成下面的报告：

load_output.log (tail)
--------------------Statistics------------------------------
Valid lines:             6
Reject lines:            0
Invalid Json format:     0
Not enough token:        1 [ERROR] (e.g. 7)
Oversize token:          0
 
Vertex:                  movie
Valid Object:            3
No ID found:             0
Invalid Attributes:      1 [ERROR] (e.g. 1:year)
Invalid primary id:      0
Incorrect fixed
binary length:           0
Passed condition lines:  4
Failed condition lines:  2 (e.g. 4,5)

共有7行数据。 报告显示：

  • 其中六行是合规的数据行

  • 一行（第7行）没有足够的token。

在6条合规的数据行中，

  • 6行中的3行生成了合规的movie顶点。

  • 一行具有无效属性（第1行：年）

  • 两行（第4行和第5行）不传递WHERE子句。

Previous创建数据加载任务Next附录

Last updated