执行加载作业

清除和初始化图存储

清除系统有两个动作:清除数据,以及清除目录中的图数据库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子句。

Last updated