Cypher Shell

关于 Cypher Shell CLI

Cypher Shell 是一个命令行工具，用于对 Neo4j 实例运行查询并执行管理任务。默认情况下，该 Shell 是交互式的，但您也可以通过在命令行上直接传递 Cypher 或通过管道将包含 Cypher 语句的文件（Windows 上需要 PowerShell）来将其用于脚本编写。它通过 Bolt 协议进行通信。

如果作为产品的一部分安装，Cypher Shell 将位于 bin 目录中。或者，您可以从 Neo4j 部署中心 下载并单独安装它。

语法

运行 Cypher Shell 的语法为

 cypher-shell [-h] [-a ADDRESS]
              [-u USERNAME] [--impersonate IMPERSONATE]
              [-p PASSWORD] [--encryption {true,false,default}]
              [-d DATABASE] [--access-mode {read,write}]
              [--format {auto,verbose,plain}]
              [-P PARAM] [--non-interactive] [--sample-rows SAMPLE-ROWS]
              [--wrap {true,false}] [-v] [--driver-version]
              [-f FILE] [--change-password] [--log [LOG-FILE]]
              [--history HISTORY-BEHAVIOUR]
              [--notifications] [--fail-fast | --fail-at-end]
              [--idle-timeout IDLE-TIMEOUT]
              [cypher]

位置参数

选项 描述

cypher

要执行的可选 Cypher 字符串，然后退出。

命名参数

选项 描述 默认值

-h, --help

显示此帮助消息并退出。

--fail-fast

在从文件读取时，在第一个错误发生时退出并报告失败（这是默认行为）。

--fail-at-end

在从文件读取时，在输入结束时退出并报告失败。

--enable-autocompletions

是否启用 CLI 中的 Cypher 自动完成，默认情况下禁用。

--format {auto,verbose,plain}

所需输出格式。如果您使用交互式 Shell，则以表格格式显示结果；如果您使用它进行脚本编写，则以最小格式显示结果。
verbose 以表格格式显示结果并打印统计信息。
plain 以最小格式显示数据。

auto

-P PARAM, --param PARAM

向此会话添加参数。例如：-P {a: 1}、-P '{a: 1, b: duration({seconds: 1})}' 或使用箭头语法 -P 'a ⇒ 1'。此参数可以多次指定。

[]

--non-interactive

强制非交互模式。仅在自动检测失败时（例如在 Windows 上）有用。

false

--sample-rows SAMPLE-ROWS

用于计算表格宽度的样本行数（仅适用于 format=VERBOSE）。

1000

--wrap {true,false}

如果列太窄，则换行表格列值（仅适用于 format=VERBOSE）。

true

-v, --version

打印 Cypher Shell 版本并退出。

false

--driver-version

打印 Neo4j Driver 版本并退出。

false

-f FILE, --file FILE

传递包含要执行的 Cypher 语句的文件。执行完所有语句后，Cypher Shell 会关闭。

--change-password

更改 neo4j 用户密码并退出。

false

--log [LOG-FILE]

启用将日志记录到指定文件，或者如果省略文件，则记录到标准错误。

--history [HISTORY-BEHAVIOUR]

查询和命令历史文件的文件路径或 in-memory 表示内存中的历史记录。默认值为 <user home>/.neo4j/.cypher_shell_history。也可以使用环境变量 NEO4J_CYPHER_SHELL_HISTORY 设置它。

--notifications

在交互模式下启用查询通知。

false

--idle-timeout IDLE-TIMEOUT

在交互模式下，在指定空闲时间后关闭应用程序。您可以使用 <hours>h<minutes>m<seconds>s 格式指定持续时间，例如 1h（1 小时）、1h30m（1 小时 30 分钟）或 30m（30 分钟）。

disable

连接参数

选项 描述 默认值

-a ADDRESS, --address ADDRESS, --uri ADDRESS

要连接的地址和端口。默认值为 neo4j://127.0.0.1:7687。也可以使用环境变量 NEO4J_ADDRESS 或 NEO4J_URI 指定。

neo4j://127.0.0.1:7687

-u USERNAME, --username USERNAME

要连接的用户名。也可以使用环境变量 NEO4J_USERNAME 指定。

--impersonate IMPERSONATE

要模拟的用户。

-p PASSWORD, --password PASSWORD

要连接的密码。也可以使用环境变量 NEO4J_PASSWORD 指定。

--encryption {true,false,default}

是否应该对与 Neo4j 的连接进行加密。这必须与 Neo4j 的配置一致。如果选择 default，则从指定的地址推断出加密设置。例如，neo4j+ssc 协议使用加密。

default

-d DATABASE --database DATABASE

要连接的数据库。也可以使用环境变量 NEO4J_DATABASE 指定。

--access-mode {read,write}

访问模式。默认为 WRITE。

write

在 Neo4j 发行版中运行 Cypher Shell

您可以通过运行 cypher-shell 并传入用户名和密码参数来连接到实时 Neo4j DBMS

bin/cypher-shell -u neo4j -p <password>

输出如下

Connected to Neo4j at neo4j://127.0.0.1:7687 as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.

从不同的服务器运行 Cypher Shell

您也可以在不同的服务器（没有 Neo4j）上安装 Cypher Shell 工具并连接到 Neo4j DBMS。Cypher Shell 需要 Java 17。

DEB/RPM 发行版都安装 Java（如果尚未安装）和 Cypher Shell 可执行文件。cypher-shell 文件与 Neo4j 位于相同的 DEB/RPM Linux 存储库中。

TAR 发行版仅包含 cypher-shell 文件，因此您必须手动安装 Java。

  1. 从 Neo4j 部署中心 下载 Cypher Shell。

  2. 通过运行 cypher-shell 命令并提供 Neo4j 地址、用户名和密码来连接到 Neo4j DBMS

    cypher-shell/cypher-shell -a neo4j://IP-address:7687 -u neo4j -p <password>

    输出如下

    Connected to Neo4j at neo4j://IP-address:7687 as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.

更改访问模式

此功能在 Neo4j 5.20 及更高版本中可用。

默认情况下，访问模式设置为 write。但是，您可以在使用 cypher-shell 命令连接到 Neo4j DBMS 时或在交互式 Shell 中使用 :access-mode 命令时使用 --access-mode 参数将访问模式更改为 read 或 write。请记住，访问模式可能会影响查询可以路由到的集群中的服务器。例如，具有 modeConstraint=SECONDARY 的服务器只能进行读取。

以下是如何在读取模式下连接到 Neo4j DBMS，然后在交互式 Shell 中将访问模式更改为写入的示例。

  1. 以读取模式连接到 Neo4j DBMS

    bin/cypher-shell -u neo4j -p <password> --access-mode read
    Connected to Neo4j using Bolt protocol version 5.4 at neo4j://127.0.0.1:7687 as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.

  2. 尝试在读取访问模式下创建节点

    create ();
    Writing in read access mode not allowed. Attempted write to neo4j

  3. 在交互式 Shell 中将访问模式更改为写入

    :access-mode write

  4. 验证访问模式

    :access-mode
    Access mode write

  5. 在写入访问模式下创建节点

    create ();
    0 rows
ready to start consuming query after 66 ms, results consumed after another 0 ms
Added 1 nodes

有关 :access-mode 命令的更多信息，请在交互式 Shell 中运行以下命令

:help access-mode
usage: :access-mode - Display current access mode
:access-mode read - Reconnect with read access mode
:access-mode write - Reconnect with write access mode

可用命令

进入交互式 Shell 后，运行以下命令以显示所有可用命令

示例 1. 运行 help
:help

输出如下

Available commands:
  :access-mode  View or set access mode  (1)
  :begin        Open a transaction
  :commit       Commit the currently open transaction
  :connect      Connects to a database
  :disconnect   Disconnects from database
  :exit         Exit the logger
  :help         Show this help message
  :history      Statement history
  :impersonate  Impersonate user
  :param        Set the value of a query parameter
  :rollback     Rollback the currently open transaction
  :source       Executes Cypher statements from a file
  :sysinfo      Neo4j system information (2)
  :use          Set the active database

For help on a specific command type:
    :help command

Keyboard shortcuts:
    Up and down arrows to access statement history.
    Tab for autocompletion of commands, hit twice to select suggestion from list using arrow keys.

For help on cypher please visit:
    https://neo4j.ac.cn/docs/cypher-manual/current/
1 在 Neo4j 5.20 中引入
2 在 Neo4j 5.11 中引入

运行 Cypher 语句

您可以通过以下方式运行 Cypher 语句

  • 将 Cypher 语句直接键入交互式 Shell。

  • 使用交互式 Shell 从文件运行 Cypher 语句。

  • 将包含 Cypher 语句的文件作为 cypher-shell 参数运行。

本节中的示例使用 MATCH (n) RETURN n LIMIT 5 Cypher 语句，并将返回数据库中的 5 个节点。

示例 2. 将 Cypher 语句直接键入交互式 Shell
MATCH (n) RETURN n LIMIT 5;

以下两个示例假设您运行 cypher-shell 命令的同一文件夹中存在一个名为 example.cypher 的文件，其内容如下

MATCH (n) RETURN n LIMIT 5;
示例 3. 使用交互式 Shell 从文件运行 Cypher 语句

您可以在 Cypher 交互式 Shell 中使用 :source 命令后跟文件名来运行该文件中的 Cypher 语句

:source /path/to/your/example.cypher
示例 4. 将包含 Cypher 语句的文件作为 cypher-shell 参数运行。

您可以在运行 cypher-shell 时传递一个包含 Cypher 语句的文件作为参数。

此处的示例使用 --format plain 标志来获得简单的输出。

使用 cat（UNIX）

cat example.cypher | bin/cypher-shell -u neo4j -p <password> --format plain

使用 type（Windows）

type example.cypher | bin/cypher-shell.bat -u neo4j -p <password> --format plain

查询参数

Cypher Shell 支持基于参数的查询。使用 :param <Cypher Map> 设置参数或使用较旧的箭头语法 :param name ⇒ <Cypher Expression>。使用 :param 列出当前参数。使用 :param clear 清除参数。

参数可以设置为任何 Cypher 表达式。某些表达式需要在线评估，并且需要打开会话。参数表达式只评估一次。例如，:param {now: datetime()} 将在设置参数时将参数 now 设置为当前日期和时间。

示例 5. 在 Cypher Shell 中使用参数

  1. 使用 :param 关键字将参数 alias 设置为 Robin，将 born 设置为 date('1940-03-20')

    :param {alias: 'Robin', born: date('1940-03-20')}

  2. 使用 :params 关键字检查当前参数

    :param
    {
  alias: 'Robin',
  born: date('1981-08-01')
}

  3. 现在在 Cypher 查询中使用 alias 和 born 参数

    CREATE (:Person {name : 'Dick Grayson', alias : $alias, born: $born });
    Added 1 nodes, Set 3 properties, Added 1 labels

  4. 验证结果

    MATCH (n) RETURN n;
    +--------------------------------------------------------------------+
| n                                                                  |
+--------------------------------------------------------------------+
| (:Person {name: "Bruce Wayne", alias: "Batman"})                   |
| (:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]})    |
| (:Person {name: "Dick Grayson", alias: "Robin", born: 1940-03-20}) |
+--------------------------------------------------------------------+
3 rows available after 2 ms, consumed after another 2 ms

事务

Cypher Shell 支持显式和隐式事务。使用关键字 :begin、:commit 和 :rollback 控制事务状态。

从 Cypher Shell 运行的显式和隐式事务都将附加默认事务元数据，这些元数据遵循约定（参见 将元数据附加到事务）。

示例 6. 使用细粒度的事务控制

该示例使用内置 Neo4j 浏览器指南中的数据集，称为 MovieGraph。有关更多信息，请参见 Neo4j 浏览器文档。

  1. 运行一个查询，该查询显示数据库中只有一人出生于 1964 年。

    MATCH (n:Person) WHERE n.born=1964 RETURN n.name AS name;
    +----------------+
| name           |
+----------------+
| "Keanu Reeves" |
+----------------+

1 row
ready to start consuming query after 9 ms, results consumed after another 0 ms

  2. 启动一个事务，并创建一个出生于同一年的人

    :begin
neo4j# CREATE (:Person {name : 'Edward Mygma', born:1964});
    0 rows
ready to start consuming query after 38 ms, results consumed after another 0 ms
Added 1 nodes, Set 2 properties, Added 1 labels

  3. 如果您打开第二个 Cypher Shell 会话并运行步骤 1 中的查询，您会注意到与最新的 CREATE 语句相比没有任何变化。

    MATCH (n:Person) WHERE n.born=1964 RETURN n.name AS name;
    +----------------+
| name           |
+----------------+
| "Keanu Reeves" |
+----------------+

1 row
ready to start consuming query after 9 ms, results consumed after another 0 ms

  4. 返回第一个会话并提交事务。

    neo4j# :commit

  5. 现在，如果您运行步骤 1 中的查询，您会看到 Edward Mygma 已添加到数据库中。

    MATCH (n:Person) WHERE n.born=1964 RETURN n.name AS name;
    +----------------+
| name           |
+----------------+
| "Keanu Reeves" |
| "Edward Mygma" |
+----------------+

2 rows
ready to start consuming query after 1 ms, results consumed after another 1 ms

过程

Cypher Shell 支持运行当前用户有权访问的任何过程。

示例 7. 调用 dbms.showCurrentUser 过程
CALL dbms.showCurrentUser();
+------------------------------+
| username | roles     | flags |
+------------------------------+
| "neo4j"  | ["admin"] | []    |
+------------------------------+

1 row available after 66 ms, consumed after another 2 ms

支持的操作系统

您可以通过 Windows 系统上的 cmd 和 Unix 系统上的 bash 来使用 Cypher Shell CLI。

其他 Shell 可能会按预期工作，但没有测试范围来保证兼容性。

键盘快捷键

以下键盘命令在交互模式下可用。

键 操作

↑ 和 ↓（箭头键）

访问语句历史记录。

↹（Tab 键）

命令和 Cypher 语法的自动完成。对 Cypher 语法的建议并不完整。

Home（键）

将光标移动到当前行的第一个字符。

End（键）

将光标移动到当前行的最后一个字符。