创建、安装、执行查询
GSQL查询是一种经过编译后的数据检索和计算任务。 用户可以通过编写查询来探索任何他们喜欢的数据图形。整个过程分三步:读取并计算图数据,更新图形以及输出结果。 GSQL查询非常类似于用户自定义过程或函数:它可以有一个或多个输入参数。同时GSQL查询可以通过两种方式输出:要么返回一个值,要么将结果打印出来。整个查询过程分三步:
创建查询:定义查询的功能
安装查询:编译查询
运行查询:输入参数并执行查询
查询操作的权限
只有查询编写者(querywriter)或更高级别身份的用户(如架构师(architect),管理员(admin)和超级用户(superuser))可以进行创建,安装和删除查询。
而对于某个给定的图形,只有查询编写者或更高身份的用户才可以在该图形上执行查询操作。
如何对哪些用户组可以执行哪些查询进行更精确地控制:
1.将查询分组,并关联到对应的的权限组中。
2.把图形和每个权限组挂钩。 如果您愿意,这些图形拥有相同的域。
3.创建查询,将每个查询分配给适当的权限组。
创建查询的语法格式
创建查询(CREATE QUERY)是指在一个给定的图形数据库Schema上定义的所需要的查询功能。
一个查询包含其名称,参数列表,要查询的图的名称,返回值的类型(可选)(详见“返回结果的语法”一节),输出api的说明符(可选),以及查询的正文主体。正文主体又由一个typedef序列(可选),一个声明序列(可选)以及一个或多个语句组成。查询的具体动作由正文定义。
DISTRIBUTED选项仅适用于已跨群集分布图的安装。 如果指定,查询将使用不同的执行模型运行,这可以为遍历集群的大部分的查询提供更好的性能。 并非所有GSQL查询语言功能都在DISTRIBUTED模式下受支持。 有关详细信息,请参阅单独的文档:分布式查询模式。
OR REPLACE is deprecated
如果包含可选关键字OR REPLACE,则该查询将覆盖之前旧的同名的查询。除非新的查询中有错误,则老的查询还会保留。如果未使用OR REPLACE选项,则GSQL将拒绝执行与现有查询重名的CREATE QUERY指令。
Typedef允许程序员在查询内使用自定义类。该声明支持累加器(详见“累加器”一章)和全局/局部变量。所有累加器和全局变量都必须在使用前声明。正文中可以使用各种类型的语句。通常,一个查询的核心语句是一个或多个SELECT,UPDATE,INSERT,DELETE语句。本语言支持条件句法,即IF语句或循环语句(如WHILE和FOREACH)。同时,它还支持调用函数,变量赋值,打印和修改图形数据的功能。
查询正文主体也可以包括对其他查询的调用,即把其他的查询作为该查询的子查询。详见“将查询作为函数”一节。
查询参数以及返回值类型
下表列出了系统支持的输入数据类型和返回值类型:
输入数据类型 | 返回值类型 |
参数类型 | • 所有基础数据类型(除了边类以外) :INT, UINT, FLOAT, DOUBLE, STRING, BOOL, STRING, VERTEX,JSONOBJECT, JSONARRAY • SET <baseType>, BAG<baseType> • 例外: 不支持边类, 无论是将其作为一个基本参数,还是作为复杂类都不支持 |
返回值类型 | • 所有基础数据类型(包含边类) :INT, UINT, FLOAT, DOUBLE, STRING, BOOL, STRING, VERTEX, EDGE,JSONOBJECT, JSONARRAY • 任何累加器类,除之GroupByAccum外 |
语句类型(Statement Types)
每条语句就是一条独立指令,描述需要执行的操作。最常见的语句是数据操作语言语句(即DML语句), 它包括了SELECT,UPDATE,INSERT INTO,DELETE FROM和DELETE语句。
GSQL查询有两个级别的语句。上层语句类型称为“查询主体层”语句(query-body-level statement 或 query-body statement )。此类语句是顶层语句块或查询主体控制流语句块的一部分。例如,每个位于最上层的,直接隶属于CREATE QUERY语句块之下的语句,都是一个查询主体层语句。如果其中的一个是含有多个THEN语句块的CASE语句块,则THEN语句块中的每个语句也是一个查询主体层语句。每个查询主体层语句都以分号结尾。
较低级别的语句类型称为“DML-下层”语句(DML-sub-level statement)或简称DML子句。此语句类型用于某些查询主体的DML语句中,以定义特定的数据操作行为。 DML子句以逗号分隔,但语句块中的最后一个DML子句后没有逗号或分号。例如,若一个顶层的语句是SELECT语句,则其ACCUM子句中的每个语句都是DML子句。如果其中一个DML子句是CASE语句,则THEN语句块中的每个语句都是DML子句。
两种语句中的使用有一部分是重合的。例如,assignStmt可以在查询主体层语句中使用,也可以在DML子句中使用。
如何理解语句类型层次结构:
最上层语句是查询主体层语句(每个语句以分号结尾)。
DML中的语句是DML子句(由逗号分隔)。
控制流语句中的语句块与整个控制流语句本身具有相同的类型。
以下是查询主体层语句的说明:
EBNF范式 | 通用名称 | 描述 |
assignStmt | 赋值语句 | 详见章节 6: "声明和赋值" |
vSetVarDeclStmt | 顶点集变量声明语句 | |
gAccumAssignStmt | 全局累加器赋值语句 | |
gAccumAccumStmt | 全局累加器累加语句 | |
funcCallStmt | 调用函数或查询语句 | |
selectStmt | 选择语句 | 详见章节 7: "选择" |
queryBodyCaseStmt | 查询主体层 CASE 语句 | 详见章节 8: "控制流" |
queryBodyIfStmt | 查询主体层 IF 语句 | |
queryBodyWhileStmt | 查询主体层 WHILE 语句 | |
queryBodyForEachStmt | 查询主体层 FOREACH 语句 | |
updateStmt | UPDATE 语句 | 详见章节 9: "修改数据" |
insertStmt | INSERT INTO 语句 | |
queryBodyDeleteStmt | 查询主体层 DELETE 语句 | |
printStmt | PRINT 语句 | 详见章节 10: "输出" |
logStmt | LOG 语句 | |
returnStmt | RETURN 语句 | |
raiseStmt | RASISE语句 | 详见章节 11: "例外" |
tryStmt | TRY 语句 |
以下是DML子句中的说明:
EBNF范式 | 通用名称 | 描述 |
assignStmt | 赋值语句 | 详见章节 6: "声明与赋值" |
funcCallStmt | 函数调用语句 | |
gAccumAccumStmt | 全局累加器累加语句 | |
vAccumFuncCall | 调用附属于顶点的累加器函数语句 | |
localVarDeclStmt | 局部变量声明语句 | 详见章节 7: "选择" |
insertStmt | INSERT INTO 语句 | 详见章节 8: "控制流" |
DMLSubDeleteStmt | DML子句层DELETE 语句 | 详见章节 9: "修改数据" |
DMLSubcaseStmt | DML子句层CASE 语句 | |
DMLSubIfStmt | DML子句层IF 语句 | |
DMLSubForEachStmt | DML子句层FOREACH 语句 | |
DMLSubWhileStmt | DML子句层WHILE 语句 | |
logStmt | LOG 语句 | 详见章节 10: "输出" |
安装一个查询
执行一个查询之前必须先将其安装。 INSTALL QUERY命令会安装该命令中涉及到的每一个查询,格式为:
它还可以使用以下任何一个命令安装所有已卸载的查询:
以下为该命令的两个可选参数:
- force 参数
即使系统提示该查询已安装,也会重新安装该查询。 通过使用这个参数,用户在安装新查询时无需删除之前的旧查询,这对于覆盖已损坏或过时的查询非常有用。 如果未使用此选项,GSQL shell将拒绝重新安装已安装的查询。
- OPTIMIZE 参数
在一个标准的安装过程中,用户自定义查询会动态链接到GSQL语言代码。 每次执行完安装查询命令后,用户可以执行一个INSTALL QUERY –OPTIMIZE命令。 这条命令不需要输入查询的名称。 它会优化所有先前安装的查询,将执行时间缩短约20%。 如果查询执行时间比查询安装的时间对你更重要,则请运行该优化指令。
合规语法:
不合规语法:
- DISTRIBUTED 参数
如果您具有分布式数据库部署,则以DISTRIBUTED模式安装查询可以提高单个查询的性能 - 使用每个可用计算机中的单个工作程序来生成结果。 某些案例可能会比其他案例从此选项中获益更多 - 更多详细信息可在下一页获得:
执行一条查询
安装一条查询会创建一个REST ++访问端点。查询安装后,有两种执行查询的方法。 一种方法是通过GSQL shell: RUN QUERY query_name( parameterValues ) .
查询输出的大小限制
SELECT语句的结果输出不能超过2GB。 SELECT语句从图中搜索并返回数据,是一个查询最主要部分。 如果SELECT语句的结果大于2GB,则系统将不返回任何数据。 也不会生成任何错误消息。
想要减少查询响应的时间,可以直接向REST ++服务器提交HTTP请求:即向“http://server_ip:9000/query/graphname/queryname
”发送GET请求。 如果REST ++服务器是本地的,则server_ip是localhost
。 查询参数值可以直接包含在HTTP请求的链接地址中的查询字符串中,也可以使用data payload方式提供。
从TigerGraph v1.2开始,图形名称现在是GET /query URL的一部分。
以下两个curl命令各自等效于上面的RUN QUERY命令。其中,第一个给出了链接地址的查询字符串中的参数值。 此示例展示了原始数据类型的简单格式,例如INT,DOUBLE和STRING等类型。 第二个则通过curl命令的data payload -d选项给出了参数值。
其中RunQueryExPara.dat具有与第一个链接地址中的查询字符串完全相同的字符串。
要查看用户已经安装了的GSQL查询的参数名称和类型列表,请运行以下REST ++请求:
curl -X GET "http://localhost:9000/endpoints?dynamic=true"
通过使用data payload选项,用户可以避免使用长而复杂的链接地址。 实际上,若想调用相同的查询但使用不同的参数,则只需要更改data payload文件内容即可; HTTP请求可以是相同的。 文件加载器加载整个文件,将多行内容整合到一个文件中,并使用生成的字符串作为链接地址的查询字符串。 如果同时给出了查询字符串和data payload(非常不建议这样使用),则查询字符串中的参数值将覆盖data payload中的值。
复杂类型参数的传递
本小节介绍在通过RUN QUERY或curl命令执行查询时,如何格式化复杂类型的参数值。 有关所有参数类型的更多详细信息,请参见“查询参数类型”一节。
参数类型 | RUN QUERY方式 | GET /query HTTP请求的查询字符串 |
包含基本元素的SET或BAG | 方括号包含一系列值. 例:一个整数集合p1: [1,5,10] | 将不同的值赋予同一个参数名. 例: 一个整数集合p1: p1=1&p1=5&p1=10 |
VERTEX<type> | 如果在查询中指定了顶点类型,那么顶点参数就是vertex_id 例: 一个顶点的顶点类是person,希望改成id为person2,则 "person2" | parameterName=vertex_id 例: 顶点类是 person ,想要改成的id 是person2. vp=person2 |
VERTEX (事先未定义类型) | 如果在查询中没有指定顶点类型,那么id和type这两个参数都要提供,用括号括起来: (vertex_id, vertex_type) 例: 一个顶点的id为"person1" ,类型为"person: ("person1","person") | parameterName=vertex_id¶meterName.type=vertex_type 例:一个顶点的id为"person1" ,类型为"person" : va=person1&va.type=person |
包含带有顶点类的顶点的SET 或BAG | 与包含基本元素的SET和BAG一致,只不过元素基本类型为vertex_id 例: [ "person3", "person4" ] | 与包含基本元素的SET和BAG一致,只不过元素基本类型为vertex_id 例: vp=person3&vp=person4 |
包含顶点的SET或BAG (事先未定义类型) | 与包含定义过类型的顶点的SET或BAG一致,只是此处为声明过顶点类型。需要用用方括号把顶点的id和类型成对括起来,并用逗号分隔。支持混合类型 例: [ ("person1","person"), ("11","post")] | SET或BAG必须当做数组处理,并用[0],[1]这样的形式指定第一个,第二个元素。下面的例子等效于左边的示例 vp[0]=person1&vp[0].type=person&vp[1]=11&vp[1].type=post |
在curl 格式的地址链接中使用方括号时,必须采用-g选项或转义符。 如果参数由data payload(通过文件或payload字符串)给出,则不需要-g选项,并且不需要使用转义符。
下面是一些例子。
Data Payload文件的大小限制
默认情况下,data payload选项支持的文件最大为128MB。若要提高该大小限制,则可以运行以下命令:
此设置的上限为1024 MB。 增加payload缓冲区的大小限制,会减少可用于其他操作的内存空间,因此提高此限制时请谨慎。
有关REST ++访问端点的更多详细信息,请参阅“RESTPP API用户指南”。
运行查询时,以下选项可用:
所有顶点模式 (-av 选项)
某些查询会让SELECT语句中在所有顶点或几乎所有顶点上执行,例如 PageRank命令。 在这种情况下,图形处理引擎可以在全顶点模式下更有效地运行。 在全顶点模式中,系统始终选择所有顶点,同时以下操作无效:
按照指定的顶点或顶点类进行过滤。 源顶点集必须是所有顶点。
使用WHERE子句进行过滤。
使用HAVING子句进行过滤。
对特定的顶点或顶点类赋值。 例如:
X = { vertex_type .*}
要以全顶点模式运行查询,请在shell模式下使用-av选项,或在HTTP请求的查询字符串中包含__GQUERY__USING_ALL_ACTIVE_MODE=true
参数。
诊断(-d选项)
用户可以打开诊断选项以生成诊断监视日志,该日志包含每个SELECT语句的处理时间。 要打开监视日志,请在shell模式下使用-d选项,或在HTTP请求的查询字符串中使用__GQUERY__monitor = true参数。
生成日志文件的地址会作为输出消息的一部分。下面的例子展示了输出的样式:
GSQL查询的输出格式
GSQL查询的输出遵循业界标准的JSON格式。JSON对象是一个无序的键值对集合,并用大括号括起来。JSON值接受的数据类型为数组或对象。JASON数组是一个有序的值列表,用方括号括起来。由于值可以是对象或数组,所以JSON是可以嵌套的。字符串用双引号括起来。同时,我们用字段(field)一词来表示某个指定对象的键(或键值对)。
在JSON结构的最上层是三个必填字段:错误(error), 消息(message)和结果(results)。如果查询成功,则错误值将为false,消息值为空,结果值为查询的预期输出。如果在查询执行期间发生错误或异常,则错误值为true,消息值将是描述消息,而结果值为空。
在v2版的标准的输出规范中,增加了一个额外的最上层字段:版本(version)。 版本值也是一个对象,包含以下内容:
"version" 字段 | 值 |
api | 一个字符串,指定了输出API的版本,具体如下: • “v1”:TigerGraph平台v0.8到v1.0中使用的输出API。 如果输出结果没 有“version”字段,则假定JSON格式为v1。 • “v2”:TigerGraph平台从v1.1开始使用的输出API。 这是最新的API。 (注意:为了便于向后兼容,可以将支持v2的TigerGraph版本配置为生成v1或v2输出。) |
schema | 一个整数,表示当前正在使用的用户图形数据库Schema的版本。 当执行创建图形语句时,版本被初始化为0.每次运行SCHEMA_CHANGE JOB语句Schema值(schema value)都会递增(例如,1,2等)。 |
在某些情况下,可能会出现其他一些最上层的对象,例如“代码”(code)。 请注意,最上层对象需要用大括号括起来,这意味着它们形成了无排列顺序的元素集合。 即它们的元素可以按任意顺序排列。
下面是示例展示了一个成功的查询和输出:
“结果”键值对输出的是一张包含许多数据对象的列表,按照PRINT语句执行的顺序排序。PRINT语句结果的详细格式在“输出语句”一章中详述。
为了向下兼容,TigerGraph平台即可使用v2版本的API,也可以使用v1版本的API生成输出。
修改默认输出API的版本
以下GSQL语句可用于设置输出API的版本。
目前,<version_string>的值只能用“v1”和“v2”。 此语句设置一次,永久生效。 默认情况下,每个版本的TigerGraph平台都会将输出API预设为最新的版本。 例如,平台版本1.1中,每个查询默认都生成v2版本API的输出。
显示查询内容
要显示查询的具体内容,请运行“SHOW QUERY query_name
”命令。 此外,“ls
”命令可以用于列出所有已创建的查询,并标识已安装的查询。
删除查询
要删除查询,请运行“DROP QUERY query_name”命令。该命令会卸载已安装的查询并从字典中将其删除。 但假设有一个查询R调用了查询Q,则GSQL语言将拒绝删除已安装的查询Q。 也就是说,必须先删除调用该查询的上一级查询或同时删除所有有调用关系的查询。
要删除所有查询,可以使用以下任一命令:
ALL的作用范围
ALL的作用范围取决于当前用户的工作范围。 如果用户已设置了工作图(working graph),则DROP ALL将删除该图上的所有作业。 如果该用户是超级用户,且已经将其范围设置为全局,则DROP ALL将删除所有图形空间中的所有作业。
Last updated