cypher-shell

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cypher-shell

cypher-shell

Neo4j Cypher Shell skill. Connect once, query fast, inspect schemas.
Neo4j Cypher Shell 技能:一次连接,快速查询,查看架构。

Connection Config

连接配置

connect
writes
~/.neo4j-connection
(env vars) and injects a one-line loader into the user's shell profile (
~/.zshrc
,
~/.bashrc
, or
~/.profile
). After that, every new Bash invocation has credentials loaded automatically via native cypher-shell env vars:
Env Varcypher-shell flag
NEO4J_URI
-a, --address, --uri
NEO4J_USERNAME
-u, --username
NEO4J_PASSWORD
-p, --password
NEO4J_DATABASE
-d, --database
Execution pattern (after connect):
bash
cypher-shell --format verbose "<QUERY>"
No
source
, no flags, no credentials. Just
cypher-shell
+ query.
Pre-flight for every command (except
connect
and
install
): verify env var
NEO4J_URI
is set. If not:
bash
if [ -z "$NEO4J_URI" ]; then echo "Not connected. Run /cypher-shell connect <uri>"; exit 1; fi

connect
命令会写入
~/.neo4j-connection
(环境变量文件),并向用户的Shell配置文件(
~/.zshrc
~/.bashrc
~/.profile
)中注入一行加载代码。之后,每次新启动Bash会话时,都会通过原生cypher-shell环境变量自动加载凭据:
环境变量cypher-shell 参数
NEO4J_URI
-a, --address, --uri
NEO4J_USERNAME
-u, --username
NEO4J_PASSWORD
-p, --password
NEO4J_DATABASE
-d, --database
执行模式(连接后):
bash
cypher-shell --format verbose "<QUERY>"
无需
source
、无需参数、无需凭据。只需输入
cypher-shell
+ 查询语句即可。
connect
install
外的所有命令执行前都会检查环境变量
NEO4J_URI
是否已设置。如果未设置:
bash
if [ -z "$NEO4J_URI" ]; then echo "未连接,请运行 /cypher-shell connect <uri>"; exit 1; fi

Route $ARGUMENTS

路由 $ARGUMENTS

Parse the first word of
$ARGUMENTS
to determine the action:
First wordAction
connect
Connect to instance
query
Run Cypher query
schema
Retrieve graph schema
test
Test current connection
install
Show install instructions
(none)Show usage help
Everything after the first word becomes the sub-argument.

解析
$ARGUMENTS
第一个单词来确定执行操作:
第一个单词操作
connect
连接到实例
query
运行Cypher查询
schema
获取图数据库架构
test
测试当前连接
install
显示安装说明
(无)显示使用帮助
第一个单词之后的所有内容将作为子参数。

connect [URI]

connect [URI]

With URI (contains
://
)

带URI(包含
://

  1. Ask user for username (default:
    neo4j
    ) and password
  2. Optionally ask for database name
  3. Write credentials file:
bash
cat > ~/.neo4j-connection << 'EOF'
export NEO4J_URI="<uri>"
export NEO4J_USERNAME="<user>"
export NEO4J_PASSWORD="<pass>"
export NEO4J_DATABASE="<db>"
EOF
chmod 600 ~/.neo4j-connection
  1. Inject loader into shell profile so every future shell session auto-loads credentials. Detect the profile file and append the loader line only if not already present:
bash
undefined
  1. 询问用户用户名(默认:
    neo4j
    )和密码
  2. 可选询问数据库名称
  3. 写入凭据文件:
bash
cat > ~/.neo4j-connection << 'EOF'
export NEO4J_URI="<uri>"
export NEO4J_USERNAME="<user>"
export NEO4J_PASSWORD="<pass>"
export NEO4J_DATABASE="<db>"
EOF
chmod 600 ~/.neo4j-connection
  1. 向Shell配置文件注入加载代码,以便未来所有Shell会话自动加载凭据。检测配置文件并仅在代码不存在时追加加载行:
bash
undefined

Detect shell profile

检测Shell配置文件

if [ -f /.zshrc ]; then SHELL_PROFILE=/.zshrc elif [ -f /.bashrc ]; then SHELL_PROFILE=/.bashrc elif [ -f /.bash_profile ]; then SHELL_PROFILE=/.bash_profile else SHELL_PROFILE=~/.profile fi
if [ -f /.zshrc ]; then SHELL_PROFILE=/.zshrc elif [ -f /.bashrc ]; then SHELL_PROFILE=/.bashrc elif [ -f /.bash_profile ]; then SHELL_PROFILE=/.bash_profile else SHELL_PROFILE=~/.profile fi

Append loader only if not already there

仅在不存在时追加加载代码

LOADER='[ -f ~/.neo4j-connection ] && source ~/.neo4j-connection' grep -qF "$LOADER" "$SHELL_PROFILE" 2>/dev/null || echo "$LOADER" >> "$SHELL_PROFILE"

5. **Load credentials into current session** (so this session works immediately without restart):

```bash
source ~/.neo4j-connection
  1. Test connection:
    cypher-shell "RETURN 'connected' AS status;"
  2. On success, fetch server info:
bash
cypher-shell --format verbose \
  "CALL dbms.components() YIELD name, versions, edition RETURN name, versions[0] AS version, edition;"
bash
cypher-shell --format verbose \
  "SHOW DATABASES YIELD name, currentStatus, default RETURN name, currentStatus, default ORDER BY name;"
Report: version, edition, databases, URI. Confirm that credentials are persisted and no flags needed going forward.
LOADER='[ -f ~/.neo4j-connection ] && source ~/.neo4j-connection' grep -qF "$LOADER" "$SHELL_PROFILE" 2>/dev/null || echo "$LOADER" >> "$SHELL_PROFILE"

5. **将凭据加载到当前会话**(使当前会话无需重启即可立即使用):

```bash
source ~/.neo4j-connection
  1. 测试连接:
    cypher-shell "RETURN 'connected' AS status;"
  2. 连接成功后,获取服务器信息:
bash
cypher-shell --format verbose \
  "CALL dbms.components() YIELD name, versions, edition RETURN name, versions[0] AS version, edition;"
bash
cypher-shell --format verbose \
  "SHOW DATABASES YIELD name, currentStatus, default RETURN name, currentStatus, default ORDER BY name;"
报告内容:版本、版本类型、数据库、URI。确认凭据已持久化,后续操作无需再输入参数。

Without URI

不带URI

If
~/.neo4j-connection
exists, show current config (mask password). Otherwise ask for URI.
如果
~/.neo4j-connection
文件已存在,显示当前配置(密码会被掩码处理)。否则询问用户URI。

Protocol schemes

协议方案

SchemeEncryptionRouting
neo4j://
NoneYes (cluster)
neo4j+s://
TLS (CA-verified)Yes
neo4j+ssc://
TLS (self-signed)Yes
bolt://
NoneNo (single)
bolt+s://
TLS (CA-verified)No
bolt+ssc://
TLS (self-signed)No

协议加密路由
neo4j://
支持(集群)
neo4j+s://
TLS(CA验证)支持
neo4j+ssc://
TLS(自签名)支持
bolt://
不支持(单实例)
bolt+s://
TLS(CA验证)不支持
bolt+ssc://
TLS(自签名)不支持

test

test

  1. Verify
    NEO4J_URI
    env var is set (if not, tell user to run
    /cypher-shell connect <uri>
    )
  2. cypher-shell "RETURN 'ok' AS status;"
  3. Show: URI, user, database, version
  1. 验证
    NEO4J_URI
    环境变量是否已设置(如果未设置,提示用户运行
    /cypher-shell connect <uri>
  2. 执行
    cypher-shell "RETURN 'ok' AS status;"
  3. 显示:URI、用户、数据库、版本

Troubleshooting (if test fails)

故障排查(测试失败时)

  1. which cypher-shell
    — not found? ->
    install
  2. java -version
    — need 21+
  3. nc -z -w3 <host> <port>
    — port not open? Neo4j not running
  4. Auth error — reset at http://localhost:7474 or
    cypher-shell --change-password
  5. TLS error — try
    neo4j+ssc://
    or
    bolt://

  1. which cypher-shell
    — 未找到?-> 运行
    install
  2. java -version
    — 需要Java 21+
  3. nc -z -w3 <host> <port>
    — 端口未开放?Neo4j未运行
  4. 认证错误 — 在 http://localhost:7474 重置或运行
    cypher-shell --change-password
  5. TLS错误 — 尝试使用
    neo4j+ssc://
    bolt://

install

install

Print install instructions for the user (do NOT run them):
  • macOS:
    brew install cypher-shell
  • Debian/Ubuntu:
    curl -fsSL https://debian.neo4j.com/neotechnology.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/neo4j.gpg && echo 'deb [signed-by=/usr/share/keyrings/neo4j.gpg] https://debian.neo4j.com stable latest' | sudo tee /etc/apt/sources.list.d/neo4j.list && sudo apt-get update && sudo apt-get install -y cypher-shell
  • Docker:
    docker run --rm -it --network host neo4j/neo4j:latest cypher-shell
Requires Java 21+.

打印安装说明(不会自动执行):
  • macOS
    brew install cypher-shell
  • Debian/Ubuntu
    curl -fsSL https://debian.neo4j.com/neotechnology.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/neo4j.gpg && echo 'deb [signed-by=/usr/share/keyrings/neo4j.gpg] https://debian.neo4j.com stable latest' | sudo tee /etc/apt/sources.list.d/neo4j.list && sudo apt-get update && sudo apt-get install -y cypher-shell
  • Docker
    docker run --rm -it --network host neo4j/neo4j:latest cypher-shell
需要 Java 21+ 环境。

query [CYPHER or shortcut]

query [CYPHER 或快捷命令]

Full Cypher

完整Cypher语句

If sub-argument contains Cypher keywords (
MATCH
,
CREATE
,
MERGE
,
CALL
,
SHOW
,
RETURN
,
WITH
,
UNWIND
,
LOAD
,
DROP
,
DELETE
,
EXPLAIN
,
PROFILE
,
FILTER
,
LET
,
SEARCH
,
FINISH
), run directly:
bash
cypher-shell --format verbose "<sub-argument>"
如果子参数包含Cypher关键字(
MATCH
CREATE
MERGE
CALL
SHOW
RETURN
WITH
UNWIND
LOAD
DROP
DELETE
EXPLAIN
PROFILE
FILTER
LET
SEARCH
FINISH
),则直接运行:
bash
cypher-shell --format verbose "<sub-argument>"

Shortcuts

快捷命令

ShortcutQuery
count
MATCH (n) RETURN labels(n) AS label, count(n) AS count ORDER BY count DESC;
then
MATCH ()-[r]->() RETURN type(r) AS type, count(r) AS count ORDER BY count DESC;
orphans
MATCH (n) WHERE NOT (n)--() RETURN labels(n) AS label, n.name AS name, count(*) AS count ORDER BY count DESC;
indexes
SHOW INDEXES YIELD name, type, labelsOrTypes, properties, state RETURN name, type, labelsOrTypes, properties, state;
constraints
SHOW CONSTRAINTS YIELD name, type, labelsOrTypes, properties RETURN name, type, labelsOrTypes, properties;
wipe
WARN + ASK CONFIRMATION then
CALL { MATCH (n) WITH n LIMIT 10000 DETACH DELETE n } IN TRANSACTIONS OF 10000 ROWS;
then verify
MATCH (n) RETURN count(n) AS remaining;
快捷命令对应查询
count
MATCH (n) RETURN labels(n) AS label, count(n) AS count ORDER BY count DESC;
然后
MATCH ()-[r]->() RETURN type(r) AS type, count(r) AS count ORDER BY count DESC;
orphans
MATCH (n) WHERE NOT (n)--() RETURN labels(n) AS label, n.name AS name, count(*) AS count ORDER BY count DESC;
indexes
SHOW INDEXES YIELD name, type, labelsOrTypes, properties, state RETURN name, type, labelsOrTypes, properties, state;
constraints
SHOW CONSTRAINTS YIELD name, type, labelsOrTypes, properties RETURN name, type, labelsOrTypes, properties;
wipe
警告 + 确认提示 然后执行
CALL { MATCH (n) WITH n LIMIT 10000 DETACH DELETE n } IN TRANSACTIONS OF 10000 ROWS;
之后验证
MATCH (n) RETURN count(n) AS remaining;

No sub-argument -> show shortcuts list.

无子参数 -> 显示快捷命令列表。



schema [Label]

schema [标签]

Full schema (no label argument)

完整架构(无标签参数)

Run ALL and present formatted summary:
cypher
MATCH (n) RETURN labels(n) AS label, count(n) AS count ORDER BY count DESC;
cypher
MATCH ()-[r]->() RETURN type(r) AS type, count(r) AS count ORDER BY count DESC;
cypher
MATCH (a)-[r]->(b) RETURN DISTINCT labels(a) AS from_label, type(r) AS relationship, labels(b) AS to_label ORDER BY from_label, relationship, to_label;
cypher
MATCH (n) WITH labels(n) AS lbls, keys(n) AS props RETURN DISTINCT lbls AS label, props AS properties ORDER BY lbls;
cypher
MATCH ()-[r]->() WITH type(r) AS rel, keys(r) AS props WHERE size(props) > 0 RETURN DISTINCT rel AS relationship, props AS properties ORDER BY rel;
cypher
SHOW INDEXES YIELD name, type, labelsOrTypes, properties, state RETURN name, type, labelsOrTypes, properties, state ORDER BY name;
cypher
SHOW CONSTRAINTS YIELD name, type, labelsOrTypes, properties RETURN name, type, labelsOrTypes, properties ORDER BY name;
Present as ASCII schema map:
Graph Schema
============
Nodes: X total across Y labels
Rels: Z total across W types

[File] (145)  props: name, path, language
  --[:CONTAINS]--> [Function]
  --[:IMPORTS]--> [File]

[Function] (312)  props: name, file, line
  --[:CALLS]--> [Function]

Indexes: idx_file_path RANGE :File(path) ONLINE
Constraints: uniq_file_id UNIQUENESS :File(id)
运行所有查询并展示格式化的摘要:
cypher
MATCH (n) RETURN labels(n) AS label, count(n) AS count ORDER BY count DESC;
cypher
MATCH ()-[r]->() RETURN type(r) AS type, count(r) AS count ORDER BY count DESC;
cypher
MATCH (a)-[r]->(b) RETURN DISTINCT labels(a) AS from_label, type(r) AS relationship, labels(b) AS to_label ORDER BY from_label, relationship, to_label;
cypher
MATCH (n) WITH labels(n) AS lbls, keys(n) AS props RETURN DISTINCT lbls AS label, props AS properties ORDER BY lbls;
cypher
MATCH ()-[r]->() WITH type(r) AS rel, keys(r) AS props WHERE size(props) > 0 RETURN DISTINCT rel AS relationship, props AS properties ORDER BY rel;
cypher
SHOW INDEXES YIELD name, type, labelsOrTypes, properties, state RETURN name, type, labelsOrTypes, properties, state ORDER BY name;
cypher
SHOW CONSTRAINTS YIELD name, type, labelsOrTypes, properties RETURN name, type, labelsOrTypes, properties ORDER BY name;
以ASCII架构图形式展示:
Graph Schema
============
Nodes: X total across Y labels
Rels: Z total across W types

[File] (145)  props: name, path, language
  --[:CONTAINS]--> [Function]
  --[:IMPORTS]--> [File]

[Function] (312)  props: name, file, line
  --[:CALLS]--> [Function]

Indexes: idx_file_path RANGE :File(path) ONLINE
Constraints: uniq_file_id UNIQUENESS :File(id)

Label deep-dive (argument matches a label)

标签深度查询(参数匹配某个标签)

cypher
MATCH (n:<LABEL>) RETURN n LIMIT 5;
cypher
MATCH (n:<LABEL>) WITH n LIMIT 100 UNWIND keys(n) AS key
RETURN DISTINCT key AS property, head(collect(DISTINCT valueType(n[key]))) AS type, count(*) AS present_in ORDER BY present_in DESC;
cypher
MATCH (n:<LABEL>)-[r]->(m) RETURN type(r) AS rel, labels(m) AS target, count(*) AS count ORDER BY count DESC;
cypher
MATCH (n:<LABEL>)<-[r]-(m) RETURN type(r) AS rel, labels(m) AS source, count(*) AS count ORDER BY count DESC;
cypher
MATCH (n:<LABEL>) RETURN count(n) AS total;
cypher
MATCH (n:<LABEL>) WHERE NOT (n)--() RETURN count(n) AS orphans;

cypher
MATCH (n:<LABEL>) RETURN n LIMIT 5;
cypher
MATCH (n:<LABEL>) WITH n LIMIT 100 UNWIND keys(n) AS key
RETURN DISTINCT key AS property, head(collect(DISTINCT valueType(n[key]))) AS type, count(*) AS present_in ORDER BY present_in DESC;
cypher
MATCH (n:<LABEL>)-[r]->(m) RETURN type(r) AS rel, labels(m) AS target, count(*) AS count ORDER BY count DESC;
cypher
MATCH (n:<LABEL>)<-[r]-(m) RETURN type(r) AS rel, labels(m) AS source, count(*) AS count ORDER BY count DESC;
cypher
MATCH (n:<LABEL>) RETURN count(n) AS total;
cypher
MATCH (n:<LABEL>) WHERE NOT (n)--() RETURN count(n) AS orphans;

cypher-shell CLI Reference

cypher-shell CLI 参考

Key flags

关键参数

FlagDescriptionDefault
-a, --address, --uri
Connection URI
neo4j://localhost:7687
-u, --username
Usernameenv
NEO4J_USERNAME
-p, --password
Passwordenv
NEO4J_PASSWORD
-d, --database
Databaseenv
NEO4J_DATABASE
-f, --file FILE
Execute .cypher file
-P, --param
Set params:
-P '{a: 1}'
[]
--format {auto,verbose,plain}
Output format
auto
--access-mode {read,write}
Access mode
write
--non-interactive
Force non-interactive
false
--fail-fast / --fail-at-end
Error handling for files
fail-fast
--sample-rows N
Rows for table width
1000
--wrap {true,false}
Wrap long columns
true
--transaction-timeout
e.g.
10m
,
1h30m
disable
--error-format {gql,legacy,stacktrace}
Error display
gql
--encryption {true,false,default}
Encryption
default
--impersonate USER
Run as user
--change-password
Change password
--enable-autocompletions
Tab-complete (5+)
false
--notifications
Query notifications
false
--idle-timeout
Auto-exit
disable
--log [FILE]
Debug log
-v, --version
Version
参数描述默认值
-a, --address, --uri
连接URI
neo4j://localhost:7687
-u, --username
用户名环境变量
NEO4J_USERNAME
-p, --password
密码环境变量
NEO4J_PASSWORD
-d, --database
数据库环境变量
NEO4J_DATABASE
-f, --file FILE
执行.cypher文件
-P, --param
设置参数:
-P '{a: 1}'
[]
--format {auto,verbose,plain}
输出格式
auto
--access-mode {read,write}
访问模式
write
--non-interactive
强制非交互模式
false
--fail-fast / --fail-at-end
文件执行的错误处理
fail-fast
--sample-rows N
用于计算表格宽度的行数
1000
--wrap {true,false}
长列自动换行
true
--transaction-timeout
事务超时时间,例如
10m
,
1h30m
disable
--error-format {gql,legacy,stacktrace}
错误显示格式
gql
--encryption {true,false,default}
加密设置
default
--impersonate USER
模拟指定用户运行
--change-password
修改密码
--enable-autocompletions
启用Tab补全(版本5+)
false
--notifications
查询通知
false
--idle-timeout
空闲自动退出
disable
--log [FILE]
调试日志
-v, --version
显示版本

Shell commands (interactive)

交互式Shell命令

:help
:exit
:use <db>
:source <file>
:param {k:v}
:param k => expr
:param
(list)
:param clear
:begin
:commit
:rollback
:history
:connect
:disconnect
:sysinfo
:impersonate
:access-mode [read|write]
:help
:exit
:use <db>
:source <file>
:param {k:v}
:param k => expr
:param
(列出参数)
:param clear
:begin
:commit
:rollback
:history
:connect
:disconnect
:sysinfo
:impersonate
:access-mode [read|write]

Cypher quick patterns

Cypher 常用模式

cypher
MATCH (n:Label {prop: "val"}) RETURN n;
MATCH (a)-[:REL]->(b) RETURN a.name, b.name;
MATCH path = (a)-[*1..3]->(b) WHERE a.name = "x" RETURN path;
MATCH path = shortestPath((a {name:"x"})-[*]-(b {name:"y"})) RETURN path;
MATCH (n:Label) RETURN n.prop, count(n) ORDER BY count(n) DESC;
MERGE (n:Label {id: "x"}) ON CREATE SET n.created = timestamp() ON MATCH SET n.updated = timestamp();
CALL { MATCH (n:Label) WITH n LIMIT 10000 DETACH DELETE n } IN TRANSACTIONS OF 10000 ROWS;
LOAD CSV WITH HEADERS FROM 'file:///data.csv' AS row CREATE (:Label {name: row.name});
EXPLAIN MATCH (n)-[r]->(m) RETURN n, r, m;
PROFILE MATCH (n)-[r]->(m) RETURN n, r, m;
Cypher 25 (Neo4j 2025.06+):
FILTER
,
LET
,
FINISH
,
WHEN
,
NEXT
,
SEARCH
(vector),
coll.distinct/flatten/indexOf/insert/max/min/remove/sort
.
cypher
MATCH (n:Label {prop: "val"}) RETURN n;
MATCH (a)-[:REL]->(b) RETURN a.name, b.name;
MATCH path = (a)-[*1..3]->(b) WHERE a.name = "x" RETURN path;
MATCH path = shortestPath((a {name:"x"})-[*]-(b {name:"y"})) RETURN path;
MATCH (n:Label) RETURN n.prop, count(n) ORDER BY count(n) DESC;
MERGE (n:Label {id: "x"}) ON CREATE SET n.created = timestamp() ON MATCH SET n.updated = timestamp();
CALL { MATCH (n:Label) WITH n LIMIT 10000 DETACH DELETE n } IN TRANSACTIONS OF 10000 ROWS;
LOAD CSV WITH HEADERS FROM 'file:///data.csv' AS row CREATE (:Label {name: row.name});
EXPLAIN MATCH (n)-[r]->(m) RETURN n, r, m;
PROFILE MATCH (n)-[r]->(m) RETURN n, r, m;
Cypher 25(Neo4j 2025.06+)新增:
FILTER
,
LET
,
FINISH
,
WHEN
,
NEXT
,
SEARCH
(向量),
coll.distinct/flatten/indexOf/insert/max/min/remove/sort