ngql usage guide¶

ngql is a command-line tool that allows you to interact with the Graph service in a NebulaGraph Database Developer Edition service group. Use the commands below to connect and run queries with ngql.

Connection to and disconnection from NebulaGraph Database Developer Edition¶

Connection to NebulaGraph Database Developer Edition¶

For the supplied Docker Compose deployment, follow Open ngql with Docker Compose. To run the client directly on your development machine, first download and install ngql. Run the ./ngql examples below from the installation's bin directory. In Windows PowerShell, use .\ngql.exe:

./ngql --host <host> --port <port> --user <username> --password <password>

With the default port mapping, connect to 127.0.0.1:9669 on the machine running Docker. From another machine, use the Docker host's IP address and the corresponding host port. Enter the current NebulaGraph Database Developer Edition username and password.

Note

If the password contains shell special characters such as $, wrap it in quotes according to your shell.

You can also enable TLS encryption when connecting to NebulaGraph Database Developer Edition.

Run ./ngql --help to view more information about the connection command options.

Once connection to NebulaGraph Database Developer Edition is established, ngql prints the prompt symbol (>) to indicate that ngql is currently connected to NebulaGraph Database Developer Edition. For example:

Welcome to NebulaGraph 5, the distributed graph database offering native GQL support!
:help for help.

(root@nebula)>

At the prompt, you can type GQL statements to interact with NebulaGraph Database Developer Edition, or you can use the built-in commands to perform various operations.

Note

If the Graph service restarts or the user specified for connection is newly granted the privilege GRANT CONNECT, it is recommended to wait for at least one heartbeat interval (default is 10 seconds) before establishing the connection. To change the heartbeat interval, update the option heartbeat_interval_secs in the configuration files of all services.

Single GQL statement execution¶

You can execute a single GQL statement by using the option -e when connecting to NebulaGraph Database Developer Edition. The GQL statement must be enclosed in double quotation marks. For example:

./ngql --host <host> --port <port> --user <username> --password <password> -e "nGQL_statement"

If a GQL statement contains special characters, such as backticks (`), different terminal environments may interpret these characters differently.

In Bash, you can escape a backtick by using a backslash (\). For example:

./ngql --host <host> --port <port> --user <username> --password <password> -e "CREATE SCHEMA IF NOT EXISTS \`/home_schema\`"

Alternatively, you can use single quotation marks to enclose the GQL statement. For example:

./ngql --host <host> --port <port> --user <username> --password <password> -e 'CREATE SCHEMA IF NOT EXISTS `/home_schema`'

In PowerShell, you can escape a backtick by using a backtick (`). For example:

./ngql --host <host> --port <port> --user <username> --password <password> -e "CREATE SCHEMA IF NOT EXISTS ``/home_schema``"

For more information about escaping special characters, see the documentation of the terminal environment you are using.

Script file import¶

You can also execute multiple GQL statements by importing a script file that contains these statements. To do so, you can use the -f option when connecting to NebulaGraph Database Developer Edition. For example:

./ngql --host <host> --port <port> --user <username> --password <password> -f filename.GQL

When a GQL statement in the script file spans multiple lines, it must be enclosed in triple single quotes (''') or triple double quotes ("""). For example:

$ cat filename.GQL

"""
CREATE GRAPH TYPE IF NOT EXISTS social_network AS {
    NODE Person (LABEL Person {id INT64 PRIMARY KEY, name STRING DEFAULT 'unknown', age INT32 DEFAULT 0}),
    NODE Company (LABEL Company {id INT64 PRIMARY KEY, name STRING})
    }
"""

CREATE GRAPH IF NOT EXISTS social_network TYPED social_network

Modification of the max width of the execution plan result¶

By default, the maximum width of each row of the execution plan result is set to 100 characters. If the width of the execution result exceeds the maximum width, the result is truncated. You can modify the maximum width by using the option --width-max when connecting to NebulaGraph Database Developer Edition. For example:

./ngql --host <host> --port <port> --user <username> --password <password> --width-max 200

Timeout setting for statement execution requests¶

When connecting to NebulaGraph Database Developer Edition, you can use the option -t or --timeout to set a timeout for all statement execution requests in a session.

The value for the option -t or --timeout must be a positive integer or decimal with a unit, which can be:

ms (milliseconds)
s (seconds)
m (minutes)
h (hours)

If the value is 0 or the option is not specified, it indicates no timeout limit.

Example:

./ngql --host <host> --port <port> --user <username> --password <password> -t 60s

In this example, the timeout for all requests is set to 60 seconds. If a request is not processed within the timeout period, ngql returns an error message.

You can also dynamically set or modify the timeout after connection by using the command :timeout. For more information, see the Timeout setting for statement execution requests section in Built-in commands.

Disconnection from NebulaGraph Database Developer Edition¶

To disconnect from NebulaGraph Database Developer Edition, you can use the command :exit or :q. For example:

(root@nebula)> :q

Built-in commands¶

ngql provides built-in commands that you can use to perform various operations. You can use the command :help to view all available built-in commands. For example:

(root@nebula)> :help

Built-in command descriptions are as follows:

Command	Alias	Usage	Description
`help`	`:h`	`:help`	Displays help information.
`sleep`	-	`:sleep 5`	Pauses execution for N seconds before executing the next statement. For more information, see Sleep.
`play`	-	`:play movie`	Loads the built-in dataset 'movie'. For more information, see Import built-in datasets.
`planstyle`	-	`:planstyle box`	Adjusts the display style of EXPLAIN/PROFILE execution plans. For more information, see Execution plan style setting.
`tee`	-	`:tee [-o] <filename>`	Appends all execution results to an output file. For more information, see Log execution history.
`notee`	-	`:notee`	Stops appending execution results to the output file. For more information, see Log execution history.
`pager`	-	`:pager <command> <row_limit>`	Sets pagination for results. For more information, see Pagination.
`nopager`	-	`:nopager`	Cancels pagination. For more information, see Pagination.
`exit`	`:e`	`:exit`	Disconnects from the Graph service. For more information, see Disconnection from NebulaGraph Database Developer Edition.
`quit`	`:q`	`:quit`	Disconnects from the Graph service. For more information, see Disconnection from NebulaGraph Database Developer Edition.
`timeout`	-	`:timeout <seconds>`	Sets or modifies the timeout for statement execution requests. `0` indicates no timeout. For more information, see Timeout setting for statement execution requests below.
`warnings`	-	`:warnings`	Shows warnings after every statement, without the need to manually execute `SHOW WARNINGS`.
`nowarnings`	-	`:nowarnings`	Hides warnings after every statement. You need to manually execute `SHOW WARNINGS` to display warning messages.

Sleep¶

The command :sleep allows you to pause the execution of GQL statements for a specified number of seconds. This command is usually used for operations that require a pause.

For example, to pause the execution of GQL for 5 seconds, use the following command:

(root@nebula)> :sleep 5

Import the built-in dataset¶

The command :play allows you to import the built-in dataset movie in NebulaGraph Database Developer Edition. For information about the dataset movie, see Example dataset.

(root@nebula)> :play movie

Execution plan style setting¶

The command :planstyle adjusts the display style of execution plans when you run EXPLAIN or PROFILE in ngql. The supported styles are nest, table and box. By default, the nest style is used.

Example:

(root@nebula)> :planstyle table

Log execution history¶

The command :tee allows you to output execution records to a file in real time. Execution records include the statements that you execute and the results of the execution.

Make sure that the command :tee is enabled before you execute the operations that you want to log. By default, the command :tee is disabled. To enable the command :tee, you can use the following command at the prompt:

(root@nebula)> :tee [-o] </path/to/filename>

If the file specified by </path/to/filename> already exists, new execution records are appended to the existing file. To overwrite the existing file, add the option -o.
If the path that you specify does not exist or you do not have permission to write to the file, the command :tee fails to write to the file.

For example, to output execution records to a file named output.txt in the directory home, you can use the following command:

(root@nebula)> :tee -o /home/<your_username>/output.txt

To stop writing to the output file, use the command :notee.

Pagination¶

The command :pager sets the number of rows displayed per page before executing a statement. By default, the number of rows displayed per page is 200.

For example, to set the number of rows displayed per page to 100, you can use the following command:

(root@nebula)> :pager less 100

To restore to the default pagination settings, you can use the command :nopager.

(root@nebula)> :nopager

Timeout setting for statement execution requests¶

In addition to setting the timeout for statement execution requests when establishing a connection, you can also dynamically set or modify the timeout for requests after the connection is established by using the command :timeout.

The value for :timeout must be a positive integer or decimal with a unit, which can be:

ms (milliseconds)
s (seconds)
m (minutes)
h (hours)

If :timeout is not followed by a value or the value is 0, it indicates no timeout limit.

Example:

(root@nebula)> :timeout 10s

For more information, see the Timeout setting for statement execution requests section in Connection to and disconnection from NebulaGraph Database Developer Edition.

Displaying and hiding of warnings¶

:warnings and :nowarnings commands control whether warnings generated after executing statements are displayed. By default, :nowarnings is used.

:warnings:

This command enables the automatic display of warnings generated by the last executed GQL statement. When enabled, any warnings produced by the statement are shown immediately in the output of ngql, without the need to manually execute SHOW WARNINGS. Even if you manually execute SHOW WARNINGS, no warnings are displayed because the warnings are displayed in real time.

:nowarnings:

This command disables the automatic display of warnings after each GQL statement. When disabled, warnings are not automatically displayed, but can still be viewed manually by executing SHOW WARNINGS if necessary.

For more information about SHOW WARNINGS, see SHOW WARNINGS statement.

Auto-completion¶

ngql supports auto-completion for GQL statements. You can use the Tab key to automatically complete the statement you are entering. For example, when you type SHOW, you can press the Tab key to complete the statement. If there are multiple completions, you can press the Tab key repeatedly to cycle through the available options.

History statement review¶

Press the command Ctrl + R to search for history statements and press the Esc to exit the search. You can also use the arrow keys Up and Down to cycle through the history statements and press the key Enter to execute the selected statement.

Formats for displaying query results¶

ngql displays execution results in a table format by default. For example, when you execute the statement SHOW CREATE GRAPH movie, the result is shown as follows:

+------------+-------------------------------------------------------+
| graph_name | create_graph_statement                                |
+------------+-------------------------------------------------------+
| movie      | CREATE GRAPH IF NOT EXISTS `movie` TYPED `movie_type` |
+------------+-------------------------------------------------------+

When dealing with queries that return a large number of columns, or when the content of a column is particularly lengthy, it can be beneficial to display the results in a vertical format. This can be achieved by appending the \G option to your statement. For example, when you execute the statement SHOW CREATE GRAPH movie \G, the result is shown as follows:

*************************** 1. row ***************************
            graph_name: movie
create_graph_statement: CREATE GRAPH IF NOT EXISTS `movie` TYPED `movie_type`

Keyboard shortcuts¶

ngql provides the following keyboard shortcuts:

Key combination	Description
`Ctrl-A`, `Home`	Moves cursor to the beginning of the line.
`Ctrl-E`, `End`	Moves cursor to the end of the line.
`Ctrl-B`, `Left`	Moves cursor one character to the left.
`Ctrl-F`, `Right`	Moves cursor one character to the right.
`Ctrl-Left`, `Alt-B`	Moves cursor to the previous word.
`Ctrl-Right`, `Alt-F`	Moves cursor to the next word.
`Ctrl-D`, `Del`	Deletes character under cursor (if line is not empty).
`Ctrl-D`	Ends the file and exits from the console (if line is empty).
`Ctrl-C`	Resets input (creates a new empty prompt).
`Ctrl-L`	Clears screen (line remains unmodified).
`Ctrl-T`	Transposes previous character with the current character.
`Ctrl-H`, `BackSpace`	Deletes character before the cursor.
`Ctrl-W`, `Alt-BackSpace`	Deletes word leading up to the cursor.
`Alt-D`	Deletes word following the cursor.
`Ctrl-K`	Deletes from the cursor to the end of the line.
`Ctrl-U`	Deletes from the start of the line to the cursor.
`Ctrl-P`, `Up`	Displays the previous match from history.
`Ctrl-N`, `Down`	Displays the next match from history.
`Ctrl-R`	Initiates reverse search in history (`Ctrl-S` for forward, `Ctrl-G` to cancel).
`Ctrl-Y`	Pastes from Yank buffer (`Alt-Y` to paste next Yank instead).
`Tab`	Displays next completion.
`Shift-Tab`	Displays previous completion (after `Tab`).