Source: https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/ Documentation version: v5.3.2 # 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](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/#docker-compose). To run the client directly on your development machine, first [download and install ngql](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/#download). Run the `./ngql` examples below from the installation's `bin` directory. In Windows PowerShell, use `.\ngql.exe`: ```` ./ngql --host --port --user --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](https://dev-docs.nebula-graph.io/v5.3.2/get-started/first-query/#ngql) 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 --port --user --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 --port --user --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 --port --user --password -e 'CREATE SCHEMA IF NOT EXISTS `/home_schema`' ```` In PowerShell, you can escape a backtick by using a backtick (```). For example: ```` ./ngql --host --port --user --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 --port --user --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 --port --user --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 --port --user --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](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/#sleep). | `play` | - | `:play movie` | Loads the built-in dataset 'movie'. For more information, see [Import built-in datasets](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/#import_the_built-in_dataset). | `planstyle` | - | `:planstyle box` | Adjusts the display style of EXPLAIN/PROFILE execution plans. For more information, see [Execution plan style setting](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/#execution_plan_style_setting). | `tee` | - | `:tee [-o] ` | Appends all execution results to an output file. For more information, see [Log execution history](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/#log_execution_history). | `notee` | - | `:notee` | Stops appending execution results to the output file. For more information, see [Log execution history](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/#log_execution_history). | `pager` | - | `:pager ` | Sets pagination for results. For more information, see [Pagination](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/#pagination). | `nopager` | - | `:nopager` | Cancels pagination. For more information, see [Pagination](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/#pagination). | `exit` | `:e` | `:exit` | Disconnects from the Graph service. For more information, see [Disconnection from NebulaGraph Database Developer Edition](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/#disconnection_from_nebulagraph_database). | `quit` | `:q` | `:quit` | Disconnects from the Graph service. For more information, see [Disconnection from NebulaGraph Database Developer Edition](https://dev-docs.nebula-graph.io/v5.3.2/utilities/ngql/usage/#disconnection_from_nebulagraph_database). | `timeout` | - | `:timeout ` | 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/example-dataset/). ```` (root@nebula)> :play movie ```` []()[]() ### Execution plan style setting The command `:planstyle` adjusts the display style of execution plans when you run [EXPLAIN](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/tuning/explain/) or [PROFILE](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/tuning/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] ```` - If the file specified by `` 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//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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/show-warnings/). ## 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).