The GSQL Shell

The GSQL shell is a fully functional Java environment for interacting with the TigerGraph database. It is one of the primary ways to interact with the TigerGraph database and is included in a standard TigerGraph installation.

Launch the shell

As the TigerGraph Linux user, type gsql into the bash terminal to start a GSQL shell session:

$ gsql

If authentication is enabled, you will need to provide credentials in order to launch the shell.

Change scope

In the GSQL shell, you can run commands on a global scope or on a local scope. When you start a GSQL session, you are in the global scope. To change to the local scope of a graph, run the USE GRAPH command.

GSQL > USE GRAPH social
Using graph 'social'

To switch back to the global scope, run USE GLOBAL.

GSQL > USE GLOBAL

Operating on different scopes will require different privileges. For more information, see Roles and Privileges.

Multi-line commands

By default, GSQL treats each line as one command; the GSQL interpreter will activate as soon as the end-df-line character is entered.

GSQL > ls (1)
---- Global vertices, edges, and all graphs
Vertex Types:
  - VERTEX Person(PRIMARY_ID id STRING, name STRING, score FLOAT, tag STRING, flag BOOL) WITH STATS="OUTDEGREE_BY_EDGETYPE"
  - DIRECTED EDGE Friend(FROM Person, TO Person, weight FLOAT, tag STRING, flag BOOL) WITH REVERSE_EDGE="Also_Friend"
  - DIRECTED EDGE Also_Friend(FROM Person, TO Person, weight FLOAT, tag STRING, flag BOOL) WITH REVERSE_EDGE="Friend"
  - UNDIRECTED EDGE Coworker(FROM Person, TO Person, weight FLOAT, tag STRING, flag BOOL)

Graphs:
  - Graph social(Person:v, Friend:e, Also_Friend:e, Coworker:e)
Jobs:


JSON API version: v2
Syntax version: v1
GSQL > CREATE QUERY example () { (2)
Encountered "<EOF>" at line 1, column 25.
Was expecting:
    "}" ...

1	GSQL executes a single-line command immediately after encountering the end-of-line character.
2	Trying to enter a multi-line command in the default single-line mode will cause an error.

Multi-line mode allows the user to enter several lines of text without triggering immediate execution. This is useful when a statement is very long and the user would like to split it into multiple lines. It is also useful when defining a job or query, because they typically contain multiple statements.

To enter multi-line mode, use the command BEGIN. The end-of-line character is now disabled from triggering execution. The shell remains in multi-line mode until the command END or ABORT is entered. The END command triggers the execution of the multi-line block. Alternately, the ABORT command exits multi-line mode and discards the multi-line block.

Example

In the example below, BEGIN and END are used to allow the SELECT statement to be split into several lines:

GSQL > BEGIN
GSQL > CREATE QUERY example () {
GSQL > PRINT "Hello world";
GSQL > }
GSQL > END
Successfully created queries: [example].

Run GSQL scripts and in-line commands

You don’t always need to enter the interactive shell in order to run a GSQL command. You can also run command in-line or through a GSQL script.

To run a GSQL command non-interactively, run the bash command gsql followed by the GSQL commands you want to run in quotes:

$ gsql 'ls'

To run a GSQL script, put all your GSQL commands in a file (conventionally ending with the extension .gsql), and run:

$ gsql <filename>

Replace <filename> with the name of the script file.

You can also run a GSQL script from the GSQL shell. To do so, type in the file name prefixed with the @ character:

GSQL > @<filename>

Replace <filename> with the name of the script file.