系统预制函数(Endpoints)
系统工具
GET /echo 和 POST /echo
这两个端点是基础诊断工具,它们的消息回复如下:
POST /echo的消息回复和GET /echo相同。
GET /endpoints 端点
本端点用于列出所有已经安装了的端点以及它们的参数。所有端点的类型分为三种类型:
类型 | 说明 |
内建端点 | 预装于TigerGraph系统内的端点 |
动态端点 | 在编译GSQL查询时生成的端点 |
静态端点 | 用户安装的端点 |
如果只想列出某一种或几种类型的端点,可以在命令中添加TypeName =true参数。例如,用户可以通过在命令中添加"builtin=true&static=true"参数来仅仅列出内建端点和静态端点。若未输入该参数,则系统默认输出所有类型的端点。
内建端点的数量有很多,其中的某些端点还包含多个参数。所以,如果通过添加builtin=true参数输出所有内建端点,JSON格式的输出结果在格式整理之后会长达300多行。此处我们只贴出了一部分GET /echo 和 GET /endpoints 的输出结果以演示对应的输出格式。你可以在附录A中找到输出的全文。
GET /statistics端点
本端点用于在指定时间段内输出实时的查询性能指标,该时间段由seconds参数定义。seconds的值必须为一个不大于60的正整数。REST++服务器会保留一份精简的查询日志,该日志从当前时间点开始计时,直到计时时间满足log_interval值为止。性能统计报告内包含两类数值:一类是已经完成的查询,另一类是在统计的seconds区间内超时的查询,且这两类查询必须都位于log_interval规定的时间间隔内。
性能报告为JSON格式。对于每一个包含统计数据的端点,我们输出以下内容:
CompletedRequests - 已经完成的请求数
QPS - 每秒查询数
TimeoutRequests - 由于超时而失败的请求数。该数字不计算在QPS中。
AverageLatency - 已完成请求的平均时延。
MaxLatency - 已完成请求的最大时延。
MinLatency - 已完成请求的最小时延。
LatencyPercentile - 时延分布,即结果展示时的分组单位,由segments参数定义,默认值为10。举个例子:假定该分组单位为10,则一个0~100%的数据分布会被等分为10组:0%~10%,10%~20%...等等,以此类推;参数segments必须在0到100之间取值。
注意:若性能日志的采集时间段内没有查询,则输出的JSON值为空。
GET /version端点
该端点返回所有系统组件的研发版本。在获取TigerGraph技术支持服务时,我们会用到该端点。
访问及修改图数据
为了支持多图数据库功能,我们修改了REST端点的URL规范,在URL中增加了图名(graph name)参数。
GET /graph/{graph_name}/vertices
该端点会输出所有 graph_name 图中的符合 vertex_type 点类的点。如果该数据库中只有一个图,则图名参数可以省略,而在多图环境中则必须声明 graph_name 。与此同时,用户如果想要选择某个特定的点,也可以通过指定 vertex_id 字段来声明该点的primary_id。
/graph/{graph_name}/vertices 包含一个可选参数 count_only,默认值为 false 。如果将它修改为 true ,则输出的结果只是统计符合条件的点的总数。
GET /graph/{graph_name}/edges
该端点会列出所有在 graph_name 图中指向某个指定的点的边。如果该数据库中只有一个图,则图名参数可以省略,而在多图环境中则必须声明 graph_name 。出发点的ID必须声明,但边类,目标点类和目标点ID则是可选的。URL的格式如下:
edge_type - 边类的名称。可通过在URL中使用"_"表示所有边类,也可通过省略该edge_type字段表示所有边类。但是,跳过edge_type 字段的同时也意味着 target_vertex_type 和 target_vertex_id 也必须跳过。
target_vertex_type - 目标点的点类
target_vertex_id - 目标点的ID
对于/graph/ endpoints的GET或DELETE请求来说,还有数个可选参数。具体细节详见“高级参数”章节。
GET /graph/ 端点最多可以输出10240个结果项。
实际案例:
/graph/{graph_name}/edges有两个可选参数:即"count_only" 和 "not_wildcard":
count_only : 该参数的值默认值为false。如果改为true,则输出的结果只是统计符合条件的边的总个数。
not_wildcard : 本参数规定了边类"_"的解释方法。如果保留默认值false,则"_"表示所有的边类。但如果该参数为true,则系统会按照字面意思将该字符解释为一条下划线,即系统只筛选出类名为"_"的边。
DELETE /graph/{graph_name}/vertices
本端点会在graph_name图中删除指定的点。如果该数据库中只有一个图,则图名参数可以省略,而在多图环境中则必须声明graph_name。本端点URL的语法和语义均类似于之前的GET /graph/{graph_name}/vertices,但本端点比后者多一个参数:“permanent”。该参数的默认值为false,如果将其设定为true,则表示已经被删除的点的ID不会再次重复使用,除非整个图数据库都被彻底删除。
DELETE /graph/{/graph_name}/edges
本端点用于删除指定的边。如果该数据库中只有一个图,则图名参数可以省略,而在多图环境中则必须声明 graph_name 。本端点URL的语法和语义均类似于之前的 GET /graph/{graph_name}/edges。
/graph/{graph_name}/edges 的高级参数
上面介绍的四个端点(即GET /graph/{graph_name}/vertices, GET /graph/{graph_name}/edges, DELETE /graph/{graph_name}/vertices 和 DELETE /graph/{graph_name}/edges)均包含以下可选 URL 参数:
Select : 只输出某个特定的属性(只适用于GET方法)
Filter : 根据属性值筛选出所需的点和边。
Limit : 点或边的总数限制
Sort : 数据排序 (对于DELETE方法来说,Sort必须和Limit一起使用)
Timeout : 超时时间(单位为秒)。若为零,则表示使用全局超时参数
Limit参数可以减小搜索范围从而降低查询时间。但如果将Limit和Sort一起使用,则查询动作仍然会遍历所有可能的点/边,这会增加查询的时间,尤其在大图中会更加明显。
Select 参数
默认情况下,GET /graph/{graph_name}/vertices 和 /graph/{graph_name}/edges 端点会返回搜寻范围内的点/边的所有属性。但是,若要筛选出(或剔除)某些属性,则可以使用select参数。select参数的语法为:select=attribute_list,其中attribute_list为一组属性名,用逗号分隔。如果在select中包含了某个属性,则意味着输出的结果中包含了该属性。而如果在该属性前加一个减号,则表示在输出的结果中剔除该属性。如果是一条下划线则表示包含所有属性。
http://server_ip:9000/graph/{graph_name}/vertices?select=attr1,attr2
只返回属性 attr1 和 attr2http://server_ip:9000/graph/{graph_name}/vertices?select=-attr1,-attr2
返回除了 attr1 和 attr2 之外的所有属性http://server_ip:9000/graph/{graph_name}/vertices?select=-_
不返回任何属性
不能在同一个请求中同时声明想要筛选出的和想要剔除掉的属性名。
例: 在socialNet图中,输出所有 product 点的 date_time 属性值。
Filter 参数
Filter参数用于在查询中添加条件,功能类似于通用SQL语言中的WHERE条件语句。该参数的格式为:filter=filter_list,其中filter_list表示一组条件,每个条件由一个属性,一个运算符和一个值组成,不能包含空格。条件之间通过逗号分隔。 下面列出了会使用到的六个运算符:
=
等于!=
不等于>
大于>=
大于或等于>
小于<=
小于或等于
例: 下面的请求命令会返回年龄(即age)不小于30的所有User点。
文本字符串需要用引号引用。例如filter=name="GSQL"
。 然而,如果通过curl指令提交REST请求,则URL自身也被包含在引号内。这种情况下,文本字符串的引号需要使用URL编码%22来表示。
Limit 参数
Limit参数规定了查询返回的点/边的数量限制。但请注意,即便没有指定Limit参数,系统仍规定了最大的上限为10240。所以,用户指定的上限不能超过该系统上限。
例: 下面的请求只返回socialNet图上的三个User点。
Sort 参数
Sort参数会对输出结果按照给出的属性排序。语法为:sort=list_of_index_attributes。排序方法为先按第一个属性值排序,如果第一个属性值相同,则再按照第二个属性值排序,以此类推。 例:
http://server_ip:9000/graph/{graph_name}/vertices?sort=attr1
按照attr1的值升序排序http://server_ip:9000/graph/{graph_name}/vertices?sort=-attr1
按照attr1的值降序排序http://server_ip:9000/graph/{graph_name}/vertices?sort=attr1,-attr2
首先按照attr1的值升序排序,相同的部分再按照attr2的值降序排序
DELETE /graph/{graph_name}/delete_by_type/vertices
本端点会在 graph_name 图中删除所有符合指定点类的点。如果该数据库中只有一个图,则图名参数可以省略,而在多图环境中则必须声明 graph_name 。该端点包含两个参数:“permanent” 和 “ack“。“permanent” 参数的含义与 DELETE /graph/{graph_name}/vertices 中的 permanent 参数含义相同。 “ack”参数规定了RESTPP返回结果前是否需要等待GPE的应答。如果“ack”为“none”,则意味着RESTPP不需要得到GPE的应答。但如果设定为“all”(默认值),则表示RESTPP在返回结果前必须获得所有GPE的应答。
POST /builtins/{graph_name}
本端点用于统计 graph_name 图中的数据。如果该数据库中只有一个图,则图名参数可以省略,而在多图环境中则必须声明 graph_name 。用户必须指定一个JSON对象作为数据输入源,用于定义函数和参数。在该JSON对象中,关键字 “function” 用于指定函数。 函数的具体说明如下:
stat_vertex_attr 函数
本函数会返回某个边类的属性值的最大值、最小值和平均值,该值可以是整数,长整数,浮点数或双浮点数。同时它还能返回布尔类属性值中true和false的计数总数。该函数只有一个参数:
type: 点类的名称。如果使用"*"则表示所有的点类。
下面的例子中演示了在图socialNet上所做的统计查询以及输出结果。其中Person点类拥有一个长整数属性名为age。
stat_edge_attr 函数
与stat_vertex_attr类似,本函数返回指定边类的属性值的最大,最小和平均值。属性值可以是整数、长整数、浮点数和双浮点数,并同时可以返回布尔类型属性值中true或false的计数总数。请注意:每条非有向边会被计算两次。该函数包含三个参数:
type: 边类的名称。如果使用"*"则表示所有边类。
from_type: 指定出发点的点类。 如包含该参数,则系统只统计所有从该点类的点上出发的边。如果使用"*"则表示所有边类。默认值为所有边类。 如果已制定了某个边类,则同时提供准确的点类会提高查询速度。
to_type: 指定目标点的点类。 如包含该参数,则系统只统计所有目标点为该点类的边。如果使用"*"则表示所有边类。默认值为所有边类。
stat_vertex_number 函数
本函数用于统计某个点类下点的总数。它只有一个参数:
type: 点类的名称。若使用"*"则表示所有的点类。
stat_edge_number 函数
本函数会统计所有某个边类包含的边的总数。它有三个参数:
type: 边类的名称。若使用"*"则表示所有的边类。
from_type: 指定出发点的点类。 如包含该参数,则系统只统计所有从该点类的点上出发的边。如果使用"*"则表示所有边类。默认值为所有边类。 如果已制定了某个边类,则同时提供准确的点类会提高查询速度。
to_type: 指定目标点的点类。 如包含该参数,则系统只统计所有目标点为该点类的边。如果使用"*"则表示所有边类。默认值为所有边类。
POST /ddl/{graph_name} 端点
本端点用于向 graph_name 图中导入数据。如果该数据库中只有一个图,则图名参数可以省略,而在多图环境中则必须声明 graph_name 。详见GSQL语言开发指南 第一部分 数据定义及加载
本端点会将数据内嵌在HTTP请求中提交给服务器,并通过 DDL Loader 组件将数据导入(加载)到图中。需要导入的数据可以使用通用的CSV格式或JSON格式。该端点有五个参数:
名称 | 数据类型 | 默认值 | 说明 |
tag | 字符串 | 无 | 在DDL加载作业中定义的作业名(必须指定) |
filename | 字符串 | 无 | 文件变量名或包含数据文件的文件地址(必须指定) |
sep | 一个字符 | , | CSV数据文件中的分隔符。使用JSON格式时,不需要声明该参数。 |
eol | one or two character string 一个或两个字符 | \n | 行末标识符。除了"\r\n"之外,只能定义为一个字符 |
ack | 字符串, 且内容只能为 "all" 或 "none" | "all" | "all": 只有当所有GPE都应答了POST之后才返回结果。 "none": 在RESTPP执行完POST指令后立刻返回结果 |
timeout | UINT32 | 0 | 超时时间(单位秒)。如果为零,则表示使用系统超时设置。 |
请注意: 如果参数值中包含某些特殊的字符,这些字符需要用URL标准进行编码。例如: 如果 eol 的值为 '\n',则需要将其重写为 %0A。用户可以通过互联网查询标准的URL编码表,例如:https://www.w3schools.com/tags/ref_urlencode.asp 。 为了避免用户因为使用一个还是两个反斜杠而造成困扰,我们在 eol 和 sep 两个参数上禁用了反斜杠转义功能。
POST /graph/{graph_name} 端点
本端点会在 graph_name 图中更新/插入点或边。如果该数据库中只有一个图,则图名参数可以省略,而在多图环境中则必须声明 graph_name 。由于检查已有的边/点会耗费大量资源,我们的标准API不支持单独的更新(update)或插入(insert)操作。取而代之的是,我们将这两种操作合二为一,称为“更新/插入”操作(upsert)。如果需要对应的点或边早已存在,则我们将需要修改的值修改为新的值。如果它们不存在,则具体的操作则基于用户指定的运算符。某些运算符会直接建立一个新的点或边,并赋予新值。
该端点会返回被修改过数值的边/点的总数。API使用JSON格式记录所有需要被更新/插入的点或边。该JSON格式的数据可以是一个单独的文本文件,也可以直接内嵌在命令中。 POST提交的数据量有一个上限(详见Size Limits部分)。 用于描述点集或边集的参数格式如下所示。 加粗的标识符表示关键字。而斜体的部分需要替换成用户实际需要的值。另外,斜体部分可能包含多个实例。 具体请参考示例:
对于每个 attribute 而言,我们需要指定 value 和 op 。运算符 op 决定了在新值和可能已经存在的旧值之间如何运算。系统支持以下操作符:
类型 | 运算方法 | 说明 |
1 | "overwrite" 或 "=" | 如果现有值存在,则用新的值覆盖旧的值。如果现有值不存在,则用新的值创建一个点/边。本运算方法在没有指定 op 参数的时候为默认操作。 |
2 | "ignore_if_exists`" 或 "~" | 如果对应的点/边不存在,则使用输入的新值生成一个属性。但如果对应的点/边已经存在(即意味着所有属性均已赋值),则不改变现有的对应属性值。 |
3 | "add" 或 "+" | 将新的值与已有值相加 |
4 | "and" 或 "&" | 将新的值与已有值进行AND逻辑运算 |
5 | "or" 或 "|" | 将新的值与已有值进行OR逻辑运算 |
6 | "max" 或 "" | 将新的值与已有值进行比较,并写入最大值 |
7 | "min" 或 "" | 将新的值与已有值进行比较,并写入最小值 |
第3类到第7类只能在对应边或点存在的情况下使用。如果将它们使用在不存在的点或边上,整条请求命令都会被系统拒绝。
如果提交的命令中缺少了某些属性的值,处理方法如下:如果对应的点/边已经存在,则相关未声明的属性会保留原值;而若对应的点/边不存在,则在创建新的点/边后,那些缺失的属性会以默认值填充。对于整数和长整数来说,默认值为0。 而对于浮点数和双浮点数来说,默认值为0.0。
RESTPP服务器在修改数据之前会首先验证请求内容。下面这些错误的示范会导致整个请求被系统拒接且没有数据会被修改。
对于点的更新/插入:
无效点类
无效的属性数据类型
对于边的更新/插入:
无效的出发点点类
无效的边类
无效的目标点点类
无效的属性数据类型
无效的属性名会被系统忽略。
下面的示例中,文件 add_id6 . json 会更新/插入一个 id 为 id6 的 User 点,一条 Liked 边和一条 Liked_By 边。 Liked 边从点 id1 出发,到达点 id6 。 Liked_By 边从则是从点 id6 出发,到达点 id1 。
下面的示例中演示了如何通过数据文件add_id6.json提交数据更新/插入操作。
动态生成的端点
每当一个新的TigerGraph系统安装完成后,计算机遍会自动生成一个动态端点并保存在installation_directory/config/endpoints_dynamic目录中。该新生成的端点能够帮助用户在TigerGraph系统中使用curl命令提交查询请求,并配合合适的参数以及数据输入。详见"GSQL Language Specification, Part 2: Queries"文档的"Running a Query"章节。例: 下面的TigerGraph查询会在installation_directory/config/endpoints_dynamic目录下生成对应的端点:
“payload” 对象允许查询中包含数据文件。“parameter” 对象包含了查询的参数。
要执行该查询操作,且参数p=0,则正确的curl命令如下:
日志文件
REST服务器的日志文件储存在installation_directory/logs文件夹下。
Last updated