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}]
                    [--enable-autocompletions] [--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] [--idle-timeout IDLE-TIMEOUT]
                    [--error-format {gql,legacy,stacktrace}] [--fail-fast | --fail-at-end] [cypher]

位置参数

选项 描述

cypher

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

命名参数

选项 描述 默认值

-h, --help

显示此帮助消息并退出。

--fail-fast

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

--fail-at-end

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

--enable-autocompletions

是否在 CLI 中启用 Cypher 自动补全。自动补全仅适用于 Neo4j 5 及更高版本。

false

--format {auto,verbose,plain}

所需的输出格式。如果您以交互方式使用 shell，则以表格形式显示结果；如果您将其用于脚本编写，则以最小格式显示结果。
verbose 以表格形式显示结果并打印统计信息。
plain 以最小格式显示数据。

auto

-P PARAM, --param PARAM

为此会话添加参数。示例：-P '{a: 1}' 或 -P '{a: 1, b: duration({seconds: 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 驱动版本并退出。

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 分钟)。

禁用

--error-format {gql,legacy,stacktrace}

控制错误显示方式。

legacy

连接参数

选项 描述 默认值

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

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

neo4j://localhost: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://localhost: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 21。

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.

更改访问模式

默认情况下，访问模式设置为 write。但是，您可以在使用 cypher-shell 命令连接到 Neo4j DBMS 时，或在交互式 shell 中使用 :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://localhost: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
  :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
  :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/

运行 Cypher 语句

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

  • 直接在交互式 shell 中键入 Cypher 语句。

  • 在交互式 shell 中从文件运行 Cypher 语句。

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

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

示例 2. 直接在交互式 shell 中键入 Cypher 语句
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 Browser 指南中的数据集，名为 MovieGraph。有关更多信息，请参阅 Neo4j Browser 文档。

  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 (键)

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