AWS S3加载器用户手册

简介

亚马逊简单存储服务（AWS S3）是一项非常流行的云数据存储服务，已经被广泛使用在许多企业用户的应用场景中。S3是一种运行在亚马逊云上的对象存储服务，可以由互联网接口直接访问。

TigerGraph的S3加载器（S3 Loader）可以帮助你非常便捷地从S3存储桶中导入数据；数据导入的方式既可以采取 实时导入 的方法，也可以 一次性将所有数据 都导入到数据库中；目标TigerGraph数据库本身既可以本地部署，也允许云端部署；

架构介绍

整体而言，加载动作分为两个阶段：用户首先通过GSQL向TigerGraph系统发出请求，然后随后系统再将保存在外部S3上的数据加载到TigerGraph的RESTPP服务器中。下图简要地说明了S3加载器的数据结构；

加载前的配置

首先，确保需要加载的数据已经上传到S3存储桶中。

当存储桶准备完毕，你需要准备两个配置文件并将它们放置在正确的目录中：

1. S3数据源配置文件：该文件保存了连接S3服务的账号信息，即一组 access key 和 secret key 信息；TigerGraph系统凭借该文件获得S3存储桶的访问权限；详见此例：第一步：配置数据源地址。
2. S3内容配置文件：该文件定义了读取S3数据的方式；详见此例：第二步：创建数据加载作业。

配置和使用S3加载器

使用步骤分为三步:

1. 定义数据源
2. 创建加载作业
3. 执行加载作业

GSQL的S3加载器语法与现有的GSQL加载语法保持一致。

1. 定义数据源

CREATE DATA_SOURCE

在加载S3中的数据之前，你首先需要配置账户信息。使用CREATE DATA_SOURCE语句，并添加S3参数可将数据源定义为AWS S3存储桶：

CREATE DATA_SOURCE S3 data_source_name

S3数据源配置文件

在数据源创建后，使用SET命令可以为该数据源创建一条配置文件的路径：

SET data_source_name = "/path/to/s3.config";

该SET命令会读取、验证并部署该配置文件，并将其配置信息导入到TigerGraph字典中。数据源配置文件的内容必须为JSON对象格式，并包含了 access key 和 secret key 等账户信息；

s3.config

{
    "file.reader.settings.fs.s3a.access.key": "AKIAJ****4YGHQ",
    "file.reader.settings.fs.s3a.secret.key": "R8bli****p+dT4"
}

你也可以将CREATE DATA_SOURCE语句和SET语句合并成一行：

CREATE DATA_SOURCE S3 data_source_name = "/path/to/s3.config"

1. 如果你的TigerGraph是集群部署，则配置文件必须位于m1（即与GSQL server和GSQL client位于同一主机）且格式必须为JSON；如果配置文件使用了相对路径，则该路径必须能够关联到GSQL client的工作目录；

2. 每次更新配置文件后，你必须再次执行"SET data_source_name" 命令来更新字典中的数据源配置信息；

进阶操作: 多图模式下的数据源配置

S3加载器支持TigerGraph的多图模式；多图模式下，数据源既可以只适用于某一个图，也可以适用于所有的图；

1. 全局数据源只能被超级用户创建，该用户可以将该数据源赋予任何一个图；

2. 普通管理员只能创建他所管理的图的数据源，该数据源无法被其他不受他管理的图所访问。

下列有关数据源的操作均为合法操作：

1. 超级管理员创建一个全局数据源，并不将它赋予任何一张图：

CREATE DATA_SOURCE S3 s1 = "/path/to/config"

2. 超级管理员赋予或收回某个（些）图上的数据源：

GRANT DATA_SOURCE s1 TO GRAPH graph1, graph2
REVOKE DATA_SOURCE s1 FROM GRAPH graph1, graph2

3. 普通管理员在某个由他管理的本地图上创建数据源：

CREATE DATA_SOURCE S3 s1 = "/path/to/config" FOR GRAPH test_graph

在上面的介绍中，本地数据源s1只能被图test_graph访问；超级管理员不能将其赋予另一张图；

删除数据源

拥有权限的用户可以将一个数据源变量删除（drop）。全局数据源只能被超级管理员删除；本地数据源只能被拥有该图管理权限的普通管理员或是超级管理员删除。DROP命令的语法格式如下：

DROP DATA_SOURCE <source1>[<source2>...] | * | ALL

下面的所有CREATE和DROP命令均为合法操作：下面的所有CREATE和DROP命令均为合法操作：

CREATE DATA_SOURCE S3 s1 = "/home/tigergraph/s3.config"
CREATE DATA_SOURCE S3 s2 = "/home/tigergraph/s3_2.config"
 
DROP DATA_SOURCE s1, s2
DROP DATA_SOURCE *
DROP DATA_SOURCE ALL

查询数据源详情

拥有权限的用户可以使用SHOW DATA_SOURCE命令列出所有现有的数据源信息：

$ GSQL SHOW DATA_SOURCE *
 
# The sample output:
Data Source:
  - S3 s1 ("file.reader.settings.fs.s3a.access.key": "AKIAJ****4YGHQ", "file.reader.settings.fs.s3a.secret.key": "R8bli****p+dT4")
# The global data source will be shown in global scope.
# The graph scope will only show the data source it has access to.

2. 创建加载作业

S3加载器使用与标准GSQL数据加载作业一样的语法。我们需要使用DEFINE FILENAME语句定义文件名信息，从而使系统能够通过文件名和路径找到正确的配置文件。

此外，文件名也可以在内嵌有“USING子句”的执行加载作业语句中定义；执行语句中定义的数据源值会覆盖创建作业中预设的值。

下面是定义文件名语句的语法规则。其中＄DATA_SOURCE_NAME是S3数据源文件名，路径则指向 包含S3账号的配置文件。 S3配置文件必须是JSON格式；

DEFINE FILENAME filevar "=" [filepath_string | data_source_string]; 
data_source_string = $DATA_SOURCE_NAME":"<path_to_configfile>

例: S3数据源为s1，配置文件路径为：”~/files.conf":

DEFINE FILENAME f1 = "$s1:~/files.config";

S3内容配置文件

S3内容配置文件用于告诉TigerGraph系统具体读取哪个S3文件以及如何来读取；与S3数据源配置文件类似，该内容配置文件也必须是JSON格式；具体例子如下：

files.config

{
    "file.uris": "s3://my-bucket/data.csv"
}

此处，名叫”file.uris”的键是必须的；它定义了需要读取的S3目标文件（或目录）的一系列地址；每个地址可能是一个单独的文件，也可能是一个目录；如果为目录，则表示系统会读取所有直接保存在该目录下的文件；你可以使用逗号作为分隔符分隔多个地址；下面的例子演示了如何一次提供多个地址：

files.config

{
    "file.uris": "s3://my-bucket1/data1.csv,s3://my-bucket1/data2.csv,s3://my-bucket2/data3.csv"
}

除了在配置文件中定义文件地址，你也可以通过一个字符串参数来直接提供地址信息：

DEFINE FILENAME f1 = "$s1:~/files.config";
DEFINE FILENAME f1 = "$s1:{\"file.uris\":\"s3://my-bucket/data.csv\"}";

进阶操作: 调整S3配置文件的读取方法

除了通过定义”file.uris”的键值以外，系统也允许一些针对加载器的高级配置方法；下面列出了所有可以配置的参数名称：

files.config

{
    "tasks.max": 1,
    "file.uris": "s3://my-bucket/data.csv",
    "file.regexp": ".*",
    "file.recursive": false,
    "file.scan.interval.ms": 60000,
    "file.reader.type": "text",
    "file.reader.batch.size": 10000,
    "file.reader.text.archive.type": "auto",
    "file.reader.text.archive.extensions.tar": "tar",
    "file.reader.text.archive.extensions.zip": "zip",
    "file.reader.text.archive.extensions.gzip": "tar.gz,tgz"
}

每个选项的解释如下：

• "tasks.max" (默认值为1): 定义了任务并发数的上限。例如，有两个文件两个任务，则每个任务只读取一个文件；如果有两个文件一个任务，则该任务会读取全部两个文件；如果只有一个文件但是有两个任务，则只会有某一个任务来读取该文件。

• "file.uris": 定义了S3上的数据文件地址。该地址可以是动态路径，即可以使用通用表达式来定义地址。其表达式的格式为${XX} ，其中的 XX 代表DateTimeFormatter Java类中的某个样式。

如果你想将动态命名的地址（例如每天会生成的文件或目录）更好地整合入配置文件，而又不希望每次都手动更改地址信息，则可以使用通用表达式来实现自动化。例如，对于URL s3://my-bucket/${yyyy}来说，加载器在工作的时候会自动识别为 s3://my-bucket/2019。你可以根据你的需要编辑动态地址应对实际问题，例如s3://my-bucket/${yyyy}/${MM}/${DD}/${HH}-${mm}。

• "file.regexp" (默认值为.* ，即默认匹配所有文件): 使用通用的表达式，筛选出需要读取的文件。

• "file.recursive" (默认值为false): 是否读取该目录下的所有文件（包含子文件夹）。

• "file.scan.interval.ms" (默认值为60000): 两次扫描目录下文件的时间间隔，单位为毫秒（ms）；只适用于stream模式。

• "file.reader.type" (默认值为text): 读取文件的方法。如果配置为text, 则系统将以纯文本方式逐行读取该文件；如果配置为parquet, 则系统将以列式模式（即parquet格式）读取文件。

• "file.reader.batch.size" (默认值为1000): 每个批量操作中支持的行数量的上限。

• "file.reader.text.archive.type" (默认值为auto): 选择读取文件的打包压缩格式；如果配置为auto, 则系统将自动选择文件格式；如果配置为tar, 则系统只读取tar格式的文件包；如果配置为zip, 则系统只读取zip格式的数据包；如果配置为gzip, 则系统只读取gzip格式的数据包；如果配置为none, 则系统正常读取文件。

• "file.reader.text.archive.extensions.tar" (默认值为tar): 需要读取的tar格式文件列表。

• "file.reader.text.archive.extensions.zip" (默认值为zip): 需要读取的zip格式文件列表。

• "file.reader.text.archive.extensions.gzip" (默认值为gzip): 需要读取的gzip格式文件列表。

设定的压缩包格式会在加载作业时自动应用到"file.uris”中的所有文件中。如果你同时还要读取另一种格式的压缩包文件，请将"file.reader.text.archive.type”参数值设定为auto，然后通过提交扩展名列表来声明你要读取的每种文件的类型。目前版本中，我们仅支持tar，zip和gzip 三种格式的文件类型。

3. 执行加载作业

S3加载器的执行作业语法与GSQL的执行加载作业语法相同。 每个文件名变量均可以赋予一个"DATA_SOURCE Var:file configure”值，用于覆盖加载作业中预设的值。在下面的例子中，f2和f3的配置文件是由执行作业命令设定的，而f1使用的则是在创建作业时声明的配置信息：

RUN LOADING JOB job1 USING f1, f2="$s1:~/files1.config", f3="$s2:~/files2.config", EOF="true";

每个执行作业操作只能使用一种数据源。 也就是说，你不可以在一次加载作业中同时加载S3上的数据和本地数据。

每个加载作业中的所有FILENAME变量必须指向同一个数据源。

S3加载器的工作模式有两种：Streaming模式和EOF模式。

如果需要进入EOF模式，则你需要在RUN LOADING JOB命令中添加一个额外参数：

RUN LOADING JOB [-noprint] [-dryrun] [-n [i],j] jobname
   [ USING filevar [="filepath_string"][, filevar [="filepath_string"]]*
   [, CONCURRENCY="cnum"][,BATCH_SIZE="bnum"]][, EOF="true"]

管理加载作业

S3加载器的作业管理方法与普通GSQL加载器相同。主要的命令有三个：

• SHOW LOADING STATUS

• ABORT LOADING JOB

• RESUME LOADING JOB

举例来说，SHOW LOADING STATUS的命令格式如下：

SHOW LOADING STATUS job_id|ALL

如果只想看到某一个特定作业的详细信息，你需要在命令中指定job_id。该job_id可以在作业执行完成后得到。对于任一加载作业来说，上述命令均可以得到下面这些信息：

1. 当前加载的行的数目

2. 平均加载速度

3. 加载数据占用的空间的大小

4. 加载耗时

具体内容详见检查与管理加载作业章节。

S3加载器应用实例

此处为一段使用S3加载器加载S3数据的实例代码：

USE GRAPH test_graph
DROP JOB load_person
DROP DATA_SOURCE s1
 
# Create data_source s3 s1 = "s3_config.json" for graph test_graph.
CREATE DATA_SOURCE S3 s1 FOR GRAPH test_graph
SET s1 = "s3_config.json"
 
# Define the loading jobs.
CREATE LOADING JOB load_person FOR GRAPH test_graph {
  DEFINE FILENAME f1 = "$s1:s3_file_config.json";
  LOAD f1
      TO VERTEX Person VALUES ($2, $0, $1),
      TO EDGE Person2Comp VALUES ($2, $2, $1)
      USING SEPARATOR=",";
}
 
# load the data
RUN LOADING JOB load_person