GSQL Shell Sessions

Whenever you launch the GSQL shell, you are starting a GSQL shell session.

GSQL allows multiple concurrent sessions. You can limit the length of each session through bash environment variables as well as use session parameters to alter the behavior of the shell for a specific session.

Session timeout

For added security, you can configure your GSQL client session to automatically timeout after a period of inactivity. Set the GSQL_CLIENT_IDLE_TIMEOUT_SEC bash environment to a specific number of seconds. Then every time you start a GSQL session, the idle timeout will be applied.

To disable the timeout, omit <num_sec>. The default setting is no timeout.

Example

The following example uses the Linux export command to set the environment variable:

tigergraph@123:~$ export GSQL_CLIENT_IDLE_TIMEOUT_SEC=10
tigergraph@123:~$ gsql
Welcome to TigerGraph Developer Edition, free for non-production, research, or educational use.
GSQL-Dev > Session timeout after 10 seconds idle.
tigergraph@123:~$ export GSQL_CLIENT_IDLE_TIMEOUT_SEC=
tigergraph@123:~$ gsql
Welcome to TigerGraph Developer Edition, free for non-production, research, or educational use.

Concurrent sessions

Multiple shell sessions of GSQL may be run at the same time. This feature can be used to have multiple clients (human or machine) using the system to perform concurrent operations. A basic locking scheme is used to maintain isolation and consistency.

Session parameters

Session parameters are built-in system variables whose values are valid during the current session; their values do not endure after the session ends.

A session starts and ends when entering and exiting the GSQL shell, respectively. When running a command file, the session lasts during the execution of the command file. Use the SET command to set the value of a session parameter:

SET <session_parameter> = <value>

Session Parameter Meaning and Usage

Session Parameter	Meaning and Usage
`sys.data_root`	The value should be a string, representing the absolute or relative path to the folder where data files are stored. After the parameter has been set, a loading statement can reference this parameter with $sys.data_root.
`gsql_src_dir`	The value should be a string, representing the absolute or relative path to the root folder for the gsql system installation. After the parameter has been set, a loading statement can reference this parameter with $gsql_src_dir.
`exit_on_error`	When this parameter is true (default), if a semantic error occurs while running a GSQL command file, the GSQL shell will terminate. Accepted parameter values: true, false (case-insensitive). If the parameter is set to false, then a command file which is syntactically correct will continue running, even if certain runtime errors in individual commands occur. Specifically, this affects these commands: `CREATE QUERY`, `INSTALL QUERY`, RUN JOB Semantic errors include a reference to a nonexistent entity or an improper reuse of an entity. This session parameter does not affect GSQL interactive mode; GSQL interactive mode does not exit on any error. This session parameter does not affect syntactic errors: GSQL will always exit on a syntactic error.
`syntax_version`	The version of GSQL to be used for this session. Accepted values are `v1` or `v2`.
`export_timeout`	The timeout limit for the command `EXPORT GRAPH ALL` in milliseconds. The default value is around 138 hours.
`query_timeout`	If a query runs longer than the systemwide timeout (the default is 16 seconds), the query will abort. To customize this timeout limit for a GSQL session, set this value to an integer.

sys.data_root

The value should be a string, representing the absolute or relative path to the folder where data files are stored. After the parameter has been set, a loading statement can reference this parameter with $sys.data_root.

gsql_src_dir

The value should be a string, representing the absolute or relative path to the root folder for the gsql system installation. After the parameter has been set, a loading statement can reference this parameter with $gsql_src_dir.

exit_on_error

When this parameter is true (default), if a semantic error occurs while running a GSQL command file, the GSQL shell will terminate.

Accepted parameter values: true, false (case-insensitive). If the parameter is set to false, then a command file which is syntactically correct will continue running, even if certain runtime errors in individual commands occur.

Specifically, this affects these commands: CREATE QUERY, INSTALL QUERY, RUN JOB Semantic errors include a reference to a nonexistent entity or an improper reuse of an entity.

This session parameter does not affect GSQL interactive mode; GSQL interactive mode does not exit on any error. This session parameter does not affect syntactic errors: GSQL will always exit on a syntactic error.

syntax_version

The version of GSQL to be used for this session. Accepted values are v1 or v2.

export_timeout

The timeout limit for the command EXPORT GRAPH ALL in milliseconds. The default value is around 138 hours.

query_timeout

If a query runs longer than the systemwide timeout (the default is 16 seconds), the query will abort. To customize this timeout limit for a GSQL session, set this value to an integer.