系统和语言基础

运行GSQL

新版本中的的-g选项可以设定工作图

在shell提示符上输入gsql即可进入GSQL交互模式。用户也可以同时输入用户名、密码以及交互模式所需要使用的图数据库名。

GSQL进入交互模式的方法

gsql [-u username] [-p password] [-g gname]

如果仅仅提供了用户名，GSQL会要求输入用户密码：

示例：仅通过用户名登录

os$ gsql -u victor
Password for victor : ***
GSQL >

假设没有提供用户名，则GSQL会默认使用tigergraph这个用户名：

示例：未提供用户名登录：

os$ gsql
Password for tigergraph : *****
GSQL >

想要退出GSQL shell，输入exit或quit即可：

GSQL> EXIT 或 GSQL> QUIT

多个Shell会话

多会话模式允许GSQL同时运行多个会话，从而使得多个客户端（用户或计算机）能够同时连接数据库并同步操作。数据的一致性和数据隔离由加锁逻辑来实现。

多行模式：- BEGIN, END, ABORT

在交互模式中，默认每一行对应一个语句。GSQL解释器会在行末字符（End-Of-Line character）出现的时候运行本行代码。

但是在多行模式中，用户可以将一行命令分多行输入，而不会在行末立刻执行代码。这种模式在某条语句特别长的时候非常实用。另一个用处是在定义JOB时使用，因为一个JOB通常包含多个语句。

通过命令BEGIN可以进入多行模式。此时行末字符不会激活代码运行。此时shell会始终处于多行模式中，直到END命令被输入。END命令会一次性执行多行模式中的所有代码。下面的示例中BEGIN和END的使用，让SELECT长语句可以分多行输入。

示例：通过BEGIN和END定义多行语句块

BEGIN
SELECT member_id, last_name, first_name,  date_joined, status
   FROM Member
   WHERE age >= 21
   ORDER BY last_name, first_name
END

此外，通过ABORT命令可以临时退出多行模式，此前输入的代码不会被执行。

脚本文件（Command Files）和内联命令（Inline Commands）

命令文件是一个包含一系列GSQL语句的文本文件。其中的空白行和注释部分会被系统忽略执行。按照惯例，GSQL脚本文件会以. gsql 结尾，但是客户也可自定义。命令文件会自动被识别为多行模式，所以无需使用BEGIN和END命令进行标识。脚本文件的执行方式为：在GSQL shell中将文件名前添加@符号，例如：

GSQL> @file.gsl

或者在操作系统（如Linux Shell）中把文件名作为参数传递给gsql命令：

os$ gsql file.gsql

同理，单个GSQL命令也可以作为字符串，在被引号引用后，放在GSQL语句中直接运行。使用单引号双引号皆可。建议如果针对整个命令则使用单引号，而针对命令中的字符串使用双引号。

示例：在gsql命令中引用内联命令或脚本文件

gsql [-u username] [-g graphname] ['command_string' | command_file]

下面的示例中，文件name_query.gsql包含了一个多行语句块CREATE QUERY，该语句块定义了namesSimilar这个查询:

示例：使用脚本文件和内联命令

os$ gsql pagerank_query.gsql
os$ gsql 'INSTALL QUERY namesSimilar'
os$ gsql 'RUN QUERY namesSimilar (0,"michael","jackson",100)'

帮助信息

可以通过help命令查询现有GSQL的帮助信息:

GSQL> HELP [BASIC|QUERY]

HELP命令包含可选项，可以针对某些指定的命令显示更详细的信息。

ls命令用于显示目录（catalog），展示所有的顶点类，边类，图形，查询，作业以及用户自定义的会话参数。

--reset 选项

--reset选项会从Dictionary中删除整个数据库数据以及相关联的定义内容（包括图模型、数据加载任务、查询任务）；这个删除操作是不可逆的，所以请务必谨慎使用。同时，REST++，GPE和GSE三个模块也会随之关闭:

$ gsql --reset
 
Resetting the catalog.
 
Shutdown restpp gse gpe ...
Graph store /home/tigergraph/tigergraph/gstore/0/ has been cleared!
The catalog was reset and the graph store was cleared.

总结：

下表列出了目前已经介绍过的所有基础命令：

命令	命令描述
HELP [BASIC|QUERY]	显示帮助菜单或其子命令
LS	命令用于显示目录（catalog），展示所有的图模型及其顶点、边、数据加载任务、查询任务 关于不同图和不同用户下目录展示的不同，详见注释
BEGIN	进入多行编辑模式（仅在shell环境下适用）
END	关闭多行模式并运行该多行代码块
ABORT	退出多行模式并放弃该多行代码块
@file.gsql	在GSQL Shell中运行命令文件file.gsql
os$ gsql file.gsql	在操作系统中运行命令文件file.gsql
os$ gsql 'command_string'	在操作系统中运行单个gsql语句命令
os$ gsql --reset	删除图数据并清空字典（Dictionary）

关于LS命令的注释:

从1.2版本开始，ls命令根据不同用户和不同的当前图形，会有不同的输出结果:

1. 若用户未指定查询图或指定要求全局结果（USE GLOBAL）

   1. 若该用户为超级用户，则ls命令显示全局顶点、全局边以及所有图数据库结构（graph schema）

   2. 若该用户不是超级用户，则ls显示结果为空（null）

2. 若用户已指定查询图，则ls输出结果只显示对应图模型、数据加载任务、查询任务和其他定义内容信息。

会话参数

会话参数（session parameter）是内建的系统变量，变量值仅在当前会话中有效，在会话结束后失效。在一个交互式命令行模式下，会话自进入命令行模式时开始，在退出命令行模式时结束。若运行一个命令文件，则该会话的时间为文件执行的时间。

通过SET命令可以设置会话参数

SET session_parameter = value

会话参数	含义和用法
sys.data_root	必须为字符串值。表示存储数据文件的文件夹的相对或绝对路径。在该变量设定之后，可以用$sys.data_root调用该参数。
gsql_src_dir	必须为字符串值。表示GSQL软件安装目录的根目录相对或绝对路径。在该变量设定之后，可以用$gsql_src_dir调用该参数。
exit_on_error	若该变量为true（默认值），则当GSQL命令中出现语义错误时，GSQL shell会即刻停止。该变量可设为true或false（大小写敏感）。若该变量设定为false则命令执行就不会停止，即便有报错（语法错误除外）也会继续运行下去。这个参数会特别影响到以下命令： • CREATE • INSTALL QUERY • RUN JOB 语义错误（semantic error）包括：引用不存在的实体（entity）或不恰当地重用某个实体。 本参数不影响GSQL交互模式，因为 GSQL交互模式不会因为任何错误退出。 本参数不适用于语法错误（syntactic errors），任何语法错误都会终止代码执行。

示例：exit_on_error = FALSE

# exitOnError.gsql
SET exit_on_error = FALSE
 
CREATE VERTEX v(PRIMARY_ID id INT, name STRING)
CREATE VERTEX v(PRIMARY_ID id INT, weight FLOAT) #error 1: can't define VERTEX v
 
CREATE UNDIRECTED EDGE e2 (FROM u, TO v) #error 2: vertex type u doesn't exist
CREATE UNDIRECTED EDGE e1 (FROM v, TO v)
 
CREATE GRAPH g(v) #error 3: no graph definition has no edge type
CREATE GRAPH g2(*)

结果

os$ gsql exitOnError.gsql
 
The vertex type v is created.
Semantic Check Fails: The vertex name v is used by another object! Please use a different name.
failed to create the vertex type v
Semantic Check Fails: FROM or TO vertex type does not exist!
failed to create the edge type e2
The edge type e1 is created.
Semantic Check Fails: There is no edge type specified! Please specify at least one edge type!
The graph g could not be created!
 
Restarting gse gpe restpp ...
 
Finish restarting services in 11.955 seconds!
The graph g2 is created.

属性的数据类型

每个顶点和边的属性都拥有一个指定的数据类型。下表列出了目前支持的数据类型：

基本类型

名称	默认值	有效的输入格式（正则表达式）	范围和精度	描述INT
INT	0	[-+]?[0-9]+	从 –2 63 到 +2 63 - 1 (-9,223,372,036,854,775,808 到9,223,372,036,854,775,807)	8字节带符号整数
UINT	0	[0-9]+	从 0 到 2 64 - 1 (18,446,744,073,709,551,615)	8字节无符号整数
FLOAT	0.0	[ -+ ] ? [ 0 - 9 ] * \. ? [ 0 - 9 ] + ([ eE ] [ -+ ] ? [ 0 - 9 ] + ) ?	+/- 3.4 E +/-38, 7比特精度	4字节单精度浮点数 例如: 3.14159, .0065e14, 7E23 详见注释
DOUBLE	0.0	[ -+ ] ? [ 0 - 9 ] * \. ? [ 0 - 9 ] + ([ eE ] [ -+ ] ? [ 0 - 9 ] + ) ?	+/- 1.7 E +/-308, 15比特精度	8字节双精度浮点数 与FLOAT相比，它们的输入和输出格式相同，但DOUBLE的范围和精度更高。 详见注释。
BOOL	false	"true", "false" (case insensitive), 1, 0	true, false	布尔值true和false，在GSQL中表示为true和false，在输入和输出中表示为1和0
STRING	empty string	.*	UTF-8	字符串。 字符串值可以选择用单引号或双引号括起来。 详见“其他可选LOAD子句”一节中的QUOTE参数。

对于FLOAT和DOUBLE值来说，GSQL Loader支持科学计数法（如1.25E-7）

GSQL目前只能够读取非科学计数法的数值。 但是可以将结果以指数表示法显示。

某些数学运算式可能会返回非数字字符串结果，例如无穷大表示为“inf”。非数字结果表示为“NaN” （Not a Number）。

高级数据类型

名称	默认值	有效的输入格式（正则表达式)	范围和精度	描述
STRING COMPRESS	empty string	.*	UTF-8	一系列有限个数分类值的字符串。 GSQL系统使用字典编码（dictionary encoding）为每个新字符串分配唯一的整数，然后以整数的形式储存
DATETIME	UTC time 0	详见 “加载时间日期属性”一章	1582-10-15 00:00:00 to 9999-12-31 23:59:59	日期和时间（UTC）被设定为自1970年1月1日0点开始以来经过的秒数。不支持时区。 显示格式为YYYY-MM-DD hh：mm：ss
FIXED_BINARY( n)	N/A		N/A	由n个二进制编码的字节组成的字节流

此外，GSQL也支持以下复杂数据类型:

复杂数据类型

• 用户定义元组（UDT）：用户定义元组表示一个由若干字段（field）组成的有序结构。字段可以是同一类型或不同类型。 支持的字段类型如下所示。用户定义元组中的每个字段都具有固定大小。 字符串类型的字段必须指定一个字符长度。加载程序仅加载对应字符串开头指定长度的部分。 INT类字段和UINT类字段的大小可选择是否指定（以字节为单位）。

字段类型	是否需要用户指定大小？	长度选择（以字节为单位，字符串除外）	范围（N即大小）
INT	可选	1, 2, 4 (默认值), 8	0 to 2^(N*8) - 1
UINT	可选	1, 2, 4 (默认值), 8	-2^(N*8 - 1) to 2^(N*8 - 1) - 1
FLOAT	不需要		与FLOAT相同
DOUBLE	不需要		与DOUBLE相同
DATETIME	不需要		与DATETIME相同
BOOL	不需要		true, false
STRING	需要	任意个字符	任意长度在N以内的字符串

示例: 定义一个UDT

一个UDT的例子

TYPEDEF TUPLE <field1 INT (1), field2 UINT, field3 STRING (10), field4 DOUBLE > myTuple

在本示例中，myTuple是UDT的名字，它包含了四个字段：一个名叫field1的单字节的INT字段，一个名叫field2的四字节UINT字段，一个名叫field3的十字符长度字符串，以及一个名叫field4的八字节DOUBLE字段。

• LIST/SET：Set表示一个由同样类型的独立元素组成的集合，集合内的元素没有顺序要求。而List也表示由数个元素组成的集合，但内部元素有先后顺序。List中的元素可以重复，Set中的元素不可以重复。List和Set的默认值都为空集。List和Set支持的元素数据类型包括INT，DOUBLE，STRING，STRING COMPRESS,DATETIME和UDT。若要声明一个list或set，可使用尖括号<>将涉及到的元素括起来，例如： SET<INT>, LIST<STRING COMPRESS>.

由于GSQL采用多线程加载，所以初始加载到一个LIST中的元素顺序可能和原始顺序不同。

• MAP：Map是由键-值对（key-value pair）组成的集合。它不能包含重复的键，且每一个键对应唯一的值。Map的默认值为空集。键的数据类型可以是DOUBLE, STRING, STRING COMPRESS, DATETIME和UDT。 若想声明一个map类，使用尖括号<>将元素括起来，并用逗号分隔键和值。例如： MAP<INT, DOUBLE>.