Source: https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/ Documentation version: v5.3.2 # ngql 使用指南 ngql 是一个用于连接悦数图数据库开发版服务组中的 Graph 服务的命令行工具。本文介绍如何使用 ngql。 ## 连接和断开悦数图数据库开发版 ### 连接悦数图数据库开发版 使用配套 Docker Compose 部署时，按[在 Docker Compose 部署中进入 ngql](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/#docker-compose)操作。在开发机上直接运行时，先[下载并安装 ngql](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/#download)。以下`./ngql`示例在安装目录的`bin`中运行；Windows PowerShell 使用`.\ngql.exe`： ```` ./ngql --host --port --user --password ```` 使用默认端口映射时，在运行 Docker 的开发机上连接`127.0.0.1:9669`；从其他机器连接时，使用开发机 IP 和对应的开发机端口。输入悦数图数据库开发版当前的用户名和密码。 Note 如果密码中包含`$`等 Shell 特殊字符，请根据所使用的 Shell 使用引号包起来。 此外，也支持 TLS 加密连接。 运行`./ngql --help`查看连接命令选项的更多信息。 一旦成功[连接到悦数图数据库开发版](https://dev-docs.yueshu.com.cn/v5.3.2/get-started/first-query/#ngql)，ngql 会显示提示符 (`>`) 表示当前已连接到悦数图数据库开发版。例如： ```` Welcome to Yueshu Graph Database 5, the distributed graph database offering native GQL support! :help for help. (root@doc)> ```` 在提示符下，您可以输入 GQL 语句与悦数图数据库开发版进行交互，或使用内置命令执行各种操作。 Note 如果 Graph 服务重启或者连接时指定的用户刚刚被授予`GRANT CONNECT`权限，建议等待至少 1 个心跳间隔（预设值为`10`秒）再建立连接。如果需要修改心跳间隔，请在所有服务的配置文件中，修改参数`heartbeat_interval_secs`。 ### 执行单条 GQL 语句 在连接悦数图数据库开发版时使用选项`-e`指定要执行的单条 GQL 语句。GQL 语句必须用双引号括起来。例如： ```` ./ngql --host --port --user --password -e "GQL_statement" ```` 如果 GQL 语句包含特殊字符（如反引号```），不同的终端环境对这些字符的处理方式可能不同。 在 Bash 中，使用反斜杠（\）来转义反引号。例如： ```` ./ngql --host --port --user --password -e "CREATE SCHEMA IF NOT EXISTS \`/home_schema\`" ```` 或者，也可以使用单引号（'）来包裹整条 GQL 语句。例如： ```` ./ngql --host --port --user --password -e 'CREATE SCHEMA IF NOT EXISTS `/home_schema`' ```` 在 PowerShell 中，使用反引号（```）来转义反引号。例如： ```` ./ngql --host --port --user --password -e "CREATE SCHEMA IF NOT EXISTS ``/home_schema``" ```` 有关转义特殊字符的更多信息，请查阅您使用的终端环境的文档。 ### 导入脚本文件 还可以通过指定包含多条 GQL 语句的脚本文件来执行这些语句。为此，在连接悦数图数据库开发版时使用选项`-f`。例如： ```` ./ngql --host --port --user --password -f filename.GQL ```` 当脚本文件中的 GQL 语句超过一行时，必须用三单引号（`'''`）或三双引号（`"""`）括起来。例如： ```` $ 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 ```` ### 设置执行计划结果的最大宽度 执行计划结果中每行显示的最大宽度默认为 100 字符。如果执行结果的宽度超过最大宽度，结果将被截断。您可以在连接悦数图数据库开发版时使用选项`--width-max`修改最大宽度。例如： ```` ./ngql --host --port --user --password --width-max 200 ```` ### 为执行语句请求设置超时时间 在连接悦数图数据库开发版时，可以使用选项`-t`或`--timeout`为会话中所有执行语句请求设置超时时间。 `-t`或`--timeout`选项的值为一个带单位的正整数或正小数，单位可以是： - `ms`（毫秒） - `s`（秒） - `m`（分钟） - `h`（小时） 当值为`0`或不指定该选项时，表示没有超时时间限制。 例如： ```` ./ngql --host --port --user --password -t 60s ```` 在这个示例中，所有请求的超时时间被设置为 60 秒。如果在超时时间内没有完成请求处理，ngql 将返回错误消息。 您也可以在连接后使用命令`:timeout`动态设置或修改超时时间。更多信息，请参见内置命令中的为执行语句请求设置超时时间部分。 ### 断开悦数图数据库开发版 要断开悦数图数据库开发版，您可以使用命令`:exit`或`:q`。例如： ```` (root@doc)> :q ```` ## 内置命令 ngql 提供多个内置命令，您可以使用这些命令执行各种操作。使用命令`:help`查看所有可用的内置命令。例如： ```` (root@doc)> :help ```` 内置命令的描述如下： | 命令 | 别名 | 用法 | 描述 | `help` | `:h` | `:help` | 显示帮助。 | `sleep` | - | `:sleep 5` | 语句执行前休眠 N 秒。更多信息，请参见[暂停语句的执行](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/#_8)。 | `play` | - | `:play movie` | 加载内置数据集 movie。更多信息，请参见[导入内置数据集](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/#_9)。 | `planstyle` | - | `:planstyle box` | 调整 EXPLAIN/PROFILE 执行计划的展示视图。更多信息，请参见[设置执行计划展示视图](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/#_10)。 | `tee` | - | `:tee [-o] ` | 将所有执行结果追加到输出文件。更多信息，请参见[记录执行历史](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/#_11)。 | `notee` | - | `:notee` | 停止将所有执行结果写入到输出文件。更多信息，请参见[记录执行历史](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/#_11)。 | `pager` | - | `:pager ` | 为结果设置分页。 更多信息，请参见[分页](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/#_12)。 | `nopager` | - | `:nopager` | 取消分页。更多信息，请参见请参见[分页](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/#_12)。 | `exit` | `:e` | `:exit` | 断开连接 Graph 服务。更多信息，请参见[断开悦数图数据库开发版](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/#_6)。 | `quit` | `:q` | `:quit` | 断开连接 Graph 服务。更多信息，请参见[断开悦数图数据库开发版](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/ngql/usage/#_6)。 | `timeout` | - | `:timeout ` | 为执行语句请求设置或修改超时时间。`0`表示无超时时间。更多信息，请参见下文为执行语句请求设置超时时间。 | `warnings` | - | `:warnings` | 在每条语句执行后显示警告信息，无需手动执行`SHOW WARNINGS`。 | `nowarnings` | - | `:nowarnings` | 在每条语句执行后隐藏警告信息。您需要手动执行`SHOW WARNINGS`命令以显示警告消息。 ### 暂停语句的执行 `:sleep`命令用于暂停 GQL 语句执行的指定秒数。此命令通常用于需要暂停的操作。 例如，在执行 GQL 语句前，暂停 5 秒钟，使用以下命令： ```` (root@doc)> :sleep 5 ```` ### 导入内置数据集 `:play`命令用于导入悦数图数据库开发版的内置数据集`movie`。有关`movie`数据集的信息，请参见[示例数据集](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/example-dataset/)。 ```` (root@doc)> :play movie ```` []() ### 设置执行计划展示视图 `:planstyle`命令用于调整在 ngql 中执行 [EXPLAIN](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-admin/tuning/explain/) 或 [PROFILE](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-admin/tuning/profile/) 后所展示的执行计划的视图形式，包括嵌套视图（nest）、表格视图（table）和盒状视图（box）。默认风格为嵌套视图（nest）。 例如： ```` (root@nebula)> :planstyle table ```` ### 记录执行历史 `:tee`命令用于将执行记录实时输出到文件。执行记录包括您在命令行界面上输入的所有命令及其输出。 确保在执行要记录的操作之前启用命令`:tee`。默认情况下，命令`:tee`是禁用的。要启用`:tee`，可以在提示符下执行以下命令： ```` (root@doc)> :tee [-o] ```` - 如果指定的文件``已存在，新执行记录将追加到现有文件中。要覆盖现有文件，需添加`-o`选项。 - 如果您指定的路径不存在或没有写入文件的权限，命令`:tee`将无法写入文件。 例如，执行以下命令将执行记录输出到目录`home`下名为`output.txt`的文件中： ```` (root@doc)> :tee -o /home//output.txt ```` 如果停止将执行记录输出到文件，使用命令`:notee`。 ### 分页 `:pager`命令用于在执行语句之前设置每页显示的行数。默认情况下，每页显示的行数为`200`。 例如，执行以下命令将每页显示的行数设置为`100`： ```` (root@doc)> :pager less 100 ```` 要恢复默认的分页设置，使用命令`:nopager`。 ```` (root@doc)> :nopager ```` ### 为执行语句请求设置超时时间 除了在连接时设置超时时间外，您还可以在连接后使用命令`:timeout`动态设置或修改超时时间。 `:timeout`的值为一个带单位的正整数或正小数，单位可以是： - `ms`（毫秒） - `s`（秒） - `m`（分钟） - `h`（小时） 当`:timeout`后面没有值或值为`0`，表示没有超时时间限制。 例如： ```` (root@doc)> :timeout 10s ```` 更多信息，请参见连接和断开悦数图数据库开发版中的为执行语句请求设置超时时间部分。 ### 显示和隐藏警告信息 `:warnings`和`:nowarnings`命令用于控制是否显示执行语句后产生的警告信息。默认情况下，使用`:nowarnings`。 - `:warnings`： 此命令自动显示由最后执行的 GQL 语句生成的告警信息。启用后，语句生成的任何告警都将立即显示在 ngql 输出中，而无需手动执行`SHOW WARNINGS`命令。即使手动执行`SHOW WARNINGS`也不会显示任何信息，因为告警信息已被实时展示。 - `:nowarnings`： 此命令禁止在每条 GQL 语句执行后自动显示告警信息。启用后，告警将不会自动显示。如有需要，仍可通过执行`SHOW WARNINGS`语句手动查看。 关于`SHOW WARNINGS`的更多信息，请参见 [SHOW WARNINGS](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-admin/show/show-warnings/)。 ## 自动补全 ngql 支持 GQL 语句的自动补全。您可以使用`Tab`键自动完成正在输入的语句。例如，当您输入`SHOW`时，可以按`Tab`键完成语句。如果有多个补全选项，您可以反复按`Tab`键循环浏览可用选项。 ## 历史语句回顾 同时按住`Ctrl`和`R`键搜索历史语句，按`Esc`退出搜索。还可以使用箭头键`Up`和`Down`浏览历史语句，并按`Enter`执行选定的语句。 ## 查询结果的格式 ngql 默认以表格格式显示执行结果。例如，当执行语句`SHOW CREATE GRAPH movie`时，返回结果如下所示： ```` +------------+-------------------------------------------------------+ | graph_name | create_graph_statement | +------------+-------------------------------------------------------+ | movie | CREATE GRAPH IF NOT EXISTS `movie` TYPED `movie_type` | +------------+-------------------------------------------------------+ ```` 当处理返回大量列的查询，或某列内容特别长时，将结果以垂直格式显示会更直观。您可以在语句后附加选项`\G`来实现。例如，当您执行语句`SHOW CREATE GRAPH movie \G`时，结果如下所示： ```` *************************** 1. row *************************** graph_name: movie create_graph_statement: CREATE GRAPH IF NOT EXISTS `movie` TYPED `movie_type` ```` ## 快捷键 ngql 提供以下键盘快捷键： | 按键组合 | 描述 | Ctrl-A, Home | 将光标移动到行首。 | Ctrl-E, End | 将光标移动到行尾。 | Ctrl-B, Left | 将光标左移一个字符。 | Ctrl-F, Right | 将光标右移一个字符。 | Ctrl-Left, Alt-B | 将光标移动到上一个单词。 | Ctrl-Right, Alt-F | 将光标移动到下一个单词。 | Ctrl-D, Del | 删除光标下的字符（如果行不为空）。 | Ctrl-D | 结束文件并退出控制台（如果行为空）。 | Ctrl-C | 重置输入（创建一个新的空提示符）。 | Ctrl-L | 清屏（行保持不变）。 | Ctrl-T | 将前一个字符与当前字符互换。 | Ctrl-H, BackSpace | 删除光标前的字符。 | Ctrl-W, Alt-BackSpace | 删除光标前的单词。 | Alt-D | 删除光标后的单词。 | Ctrl-K | 删除从光标到行尾的内容。 | Ctrl-U | 删除从行首到光标的内容。 | Ctrl-P, Up | 显示历史记录中的上一个匹配项。 | Ctrl-N, Down | 显示历史记录中的下一个匹配项。 | Ctrl-R | 启动历史记录中的反向搜索（Ctrl-S 正向搜索，Ctrl-G 取消）。 | Ctrl-Y | 将缓冲区的内容粘贴到光标所在的位置（Alt-Y 粘贴下一个内容）。 | Tab | 显示下一个补全项。 | Shift-Tab | 显示上一个补全项（在 Tab 之后）。