# 命令行工具

> 此文档主要介绍 lgraph_cypher 文档的使用，注意不再更新维护，请使用 [lgraph_cli](../7.client-tools/6.bolt-console-client.md)

TuGraph 发布版本附带名为`lgraph_cypher`的查询客户端，可用于向 TuGraph 服务器提交 OpenCypher 请求。`lgraph_cypher`客户端有两种执行模式：单命令模式和交互式模式。

## 1.单命令模式

在单命令模式下，`lgraph_cypher`可用于提交单个 Cypher 查询并将结果直接打印到终端，打印结果也可以容易地重定向写入指定文件。当用户需要从服务器获取大量结果并将其保存在文件中时，这非常便利。
在此模式下，`lgraph_cypher`工具具有以下选项：

### 1.1.命令行参数:

| 参数     | 类型   | 说明                                                                     |
| -------- | ------ | ------------------------------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| --help   | \\     | 列出所有参数及说明。                                                     |
| -example | \\     | 列出命令实例。                                                           |
| -c       | string | 数据库的配置文件，用于获取 ip 与 port 信息。                             |
| -h       | string | 数据库服务器 ip 地址，如有配置文件则可舍去此参数。默认值为`127.0.0.1` 。 |
| -p       | string | 数据库服务器端口，如有配置文件则可舍去此参数。默认值为`7071` 。          |
| -u       | string | 数据库登录用户名。                                                       |
| -P       | string | 数据库登录密码。                                                         |
| -f       | string | 包含单条 Cypher 查询单文本文件的路径。                                   |
| -s       | string | 单行 cypher 查询命令。以`"`开头结尾。                                    |
| -t       | int    | 进行 cypher 查询时服务器的超时阈值。默认值为`150`秒。 -format            | string | 查询结果显示模式。支持`plain`与`table`两种格式。`plain`格式会将查询结果单列打印。`table`格式会将查询结果以表格方式显示。默认值为`table`。 |

### 1.2.命令示例:

**cypher 命令文件查询：**

```powershell
$ ./lgraph_cypher.py -c /home/usr/lgraph_standalone.json -u user -P password -f /home/usr/cypher.json
```

**cypher 命令单句查询：**

```powershell
$ ./lgraph_cypher.py -c /home/usr/lgraph_standalone.json -u user -P password -s "MATCH (n) RETURN n"
```

## 2.交互模式

`lgraph_cypher`也可以在交互模式下运行。在交互式模式下，客户端与服务器保持连接，并在读取-评估-打印-循环中与用户进行交互。

### 2.1.进入 lgraph_cypher 交互模式:

如不加`-f`或`-s`命令行选项，运行`lgraph_cypher`时将会进入交互模式。使用方式如下：

```
$ ./lgraph_cypher.py -c /home/usr/lgraph_standalone.json -u admin -P 73@TuGraph
```

如成功进入则会显示相应登录成功信息：

```
**********************************************************************
*                  TuGraph Graph Database X.Y.Z                      *
*                                                                    *
*        Copyright(C) 2023 Ant Group. All rights reserved.           *
*                                                                    *
**********************************************************************
login success
----------------------------------
Host: 127.0.0.1
Port: 7071
Username: admin
----------------------------------
type ":help" to see all commands.
>
```

现在我们也提供一个交互式 shell ，用于用户输入 Cypher 查询语句或使用`:help`命令来检查可用命令。

### 2.2.command种类与说明:

除 Cypher 查询外，`lgraph_cypher` 的 shell 还接受以下命令：

| 命令                     | 对应参数                           | 说明                                                                                                |
| ------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| :help                    | \\                                 | 显示服务器信息与所有 command 对应说明。                                                             |
| :db_info                 | \\                                 | 当前服务器状态查询。对应 REST API 的/db/info。                                                      |
| :clear                   | \\                                 | 清空屏幕。                                                                                          |
| :use                     | {图的名称}                         | 使用该名称指定的图，默认值为`default` 。                                                            |
| :source                  | `-t {查询timeout值} -f {查询文件}` | 可交互模式下的 cypher 命令文件查询。超时阈值默认值为`150`秒。查询文件格式参考无交互式查询参数。     |
| :exit                    | \\                                 | 退出交互模式并返回原命令行。                                                                        |
| :format                  | `plain` or `table`                 | 更改 cypher 查询结果的显示模式。支持`plain`与`table`模式。                                          |
| :save all/command/result | `-f {文件路径}` `{cypher语句}`     | 存储 cypher 命令（command）或查询结果（result）或以上二者（all）。默认存储位置为`/saved_cypher.txt` |

**注意:**

- 每条命令都应该以冒号开始 `:`.

**:save 命令例子:**

```
:save all -f /home/usr/saved.txt match (n) where return n, n.name limit 1000
```

### 2.3.cypher 查询命令:

在交互模式下，用户也可直接输入单句 cypher 命令进行查询，以"`;`"结束。输入命令不区分大小写。例子如下：

```
login success
>MATCH (n) RETURN n, n.name;
+---+---+-------------+
|   | n |n.name       |
+---+---+-------------+
| 0 | 0 |david        |
| 1 | 1 |Ann          |
| 2 | 2 |first movie  |
| 3 | 3 |Andres       |
+---+---+-------------+
time spent: 0.000520706176758
size of query: 4
>
```

`lgraph_cypher`输入命令时支持多行输入，用户可使用`ENTER`键将长查询语句分多行输入。多行输入情况下命令行开头会从`>`变为`=>`，然后用户可以继续输入查询的其余部分。

例子如下：

```
login success
>MATCH (n)
=>WHERE n.uid='M11'
=>RETURN n, n.name;
```

### 2.4.辅助功能:

**历史查询：** 在交互模式下按上下方向键可查询输入历史。

**自动补全：** lgraph_cypher 会根据输入历史进行自动补全。在补全提示出现的情况下，按下右方向键就会自动补全命令。