helix-query-from-cypher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cypher To Helix Queries

将Cypher转换为Helix查询

Translate Cypher into Helix Rust DSL by mapping patterns into explicit anchors, traversals, predicates, and return shaping.

通过将模式映射为显式锚点、遍历、谓词和返回结构，将Cypher转换为Helix Rust DSL。

When To Use

使用场景

Use this skill when the task is to:

translate a Cypher query into Helix Rust DSL
port a Neo4j query into a stored Helix route

replace

MATCH

OPTIONAL MATCH

WHERE

RETURN

DISTINCT

ORDER BY

LIMIT

MERGE

CASE

UNWIND

FOREACH

, or

DETACH DELETE

with Helix DSL equivalents

explain how a Cypher graph pattern should be expressed in Helix Rust

Do not use this skill as the main guide for Gremlin, SQL, or dynamic inline-query JSON.

当需要完成以下任务时，可使用此技能：

将Cypher查询转换为Helix Rust DSL
将Neo4j查询移植为Helix存储路由

用Helix DSL等效语法替换

MATCH

、

OPTIONAL MATCH

、

WHERE

、

RETURN

、

DISTINCT

、

ORDER BY

、

LIMIT

、

MERGE

、

CASE

、

UNWIND

、

FOREACH

或

DETACH DELETE

解释如何在Helix Rust中表达Cypher图模式

请勿将此技能作为Gremlin、SQL或动态内联查询JSON的主要指南。

First Steps

前期步骤

Before translating:

Inspect the local repo for real labels, edge labels, property names, and route style.
Parse the Cypher into anchors, edge directions, hop depth, filters, return shape, ordering, and pagination.
Decide whether the target route is read or write.
Identify optional branches, per-element writes, null or existence checks, and timestamp usage.
Identify any Cypher constructs that need semantic rather than literal translation.

If the local repo does not already contain an obvious Helix pattern, use:

```
docs/cypher-rosetta.md
```
```
docs/dsl-cheatsheet.md
```
```
examples/authoring-patterns.md
```
```
examples/search-patterns.md
```

在转换之前：

检查本地仓库中的实际标签、边标签、属性名称和路由风格。
将Cypher解析为锚点、边方向、跳数深度、过滤器、返回结构、排序和分页规则。
确定目标路由是读路由还是写路由。
识别可选分支、逐元素写入、空值或存在性检查以及时间戳的使用方式。
识别任何需要语义转换而非字面转换的Cypher结构。

如果本地仓库中没有明显的Helix模式，请参考：

```
docs/cypher-rosetta.md
```
```
docs/dsl-cheatsheet.md
```
```
examples/authoring-patterns.md
```
```
examples/search-patterns.md
```

Translation Workflow

转换流程

1. Choose The First Anchor

1. 选择首个锚点

Translate the first practical Cypher node pattern into the narrowest Helix anchor you can justify.

Prefer:

node ID or edge ID
unique property lookup
equality-indexed property lookup
scoped label scan
broad label scan

将第一个实用的Cypher节点模式转换为你能合理使用的最窄Helix锚点。

优先选择：

节点ID或边ID
唯一属性查找
等值索引属性查找
作用域标签扫描
宽泛标签扫描

2. Translate Edge Direction Explicitly

2. 显式转换边方向

Cypher pattern direction should map directly:

```
()-[:REL]->()
```
to
```
out(Some("REL"))
```
```
()<-[:REL]-()
```
to
```
in_(Some("REL"))
```
```
()-[e:REL]->()
```
to
```
out_e(Some("REL"))
```
undirected or symmetric traversal usually to
```
both(Some("REL"))
```
or
```
both_e(Some("REL"))
```
when the schema and task justify it

Cypher模式方向应直接映射：

```
()-[:REL]->()
```
对应
```
out(Some("REL"))
```
```
()<-[:REL]-()
```
对应
```
in_(Some("REL"))
```
```
()-[e:REL]->()
```
对应
```
out_e(Some("REL"))
```
无向或对称遍历通常对应
```
both(Some("REL"))
```
或
```
both_e(Some("REL"))
```
（当模式和任务需要时）

3. Translate WHERE Into Predicates

3. 将WHERE转换为谓词

Typical mappings:

equality to
```
Predicate::eq_param
```

numeric comparisons to

Predicate::gt_param

gte_param

lt_param

lte_param

membership to
```
Predicate::is_in_param
```
null checks to
```
Predicate::is_null
```
property-existence checks to
```
Predicate::has_key
```

compound logic to

Predicate::and(vec![...])

and

Predicate::or(vec![...])

典型映射：

等值条件对应
```
Predicate::eq_param
```

数值比较对应

Predicate::gt_param

、

gte_param

、

lt_param

、

lte_param

成员关系对应
```
Predicate::is_in_param
```
空值检查对应
```
Predicate::is_null
```
属性存在性检查对应
```
Predicate::has_key
```

复合逻辑对应

Predicate::and(vec![...])

和

Predicate::or(vec![...])

4. Translate RETURN Into Explicit Output Shaping

4. 将RETURN转换为显式输出结构

Use:

```
project(...)
```
for intentional fields
```
value_map(...)
```
when a looser property map is acceptable
```
count()
```
for counts
```
dedup()
```
for
```
DISTINCT
```
```
order_by
```
,
```
skip
```
,
```
limit
```
, and
```
range
```
for result ordering and pagination

使用：

```
project(...)
```
定义指定字段
```
value_map(...)
```
当允许更宽松的属性映射时
```
count()
```
用于计数
```
dedup()
```
对应
```
DISTINCT
```
```
order_by
```
、
```
skip
```
、
```
limit
```
和
```
range
```
用于结果排序和分页

5. Handle Non-1:1 Cypher Features Carefully

5. 谨慎处理非1:1对应的Cypher特性

Do not force literal translations for:

```
MERGE
```
path-returning queries
```
RETURN *
```

Translate them semantically instead.

请勿强行进行字面转换的情况：

```
MERGE
```
返回路径的查询
```
RETURN *
```

请改为进行语义转换。

Key Cypher Rules

关键Cypher规则

MATCH

MATCH

usually becomes one or more

var_as(...)

bindings plus explicit traversal steps.

MATCH

通常会转换为一个或多个

var_as(...)

绑定加上显式遍历步骤。

WHERE

WHERE

becomes explicit predicate calls. Keep parameter names aligned with the user's query or local route conventions.

WHERE

转换为显式谓词调用。保持参数名称与用户查询或本地路由约定一致。

RETURN

RETURN

should become a deliberate Helix result shape, not an implicit full-object dump unless the route truly wants that.

RETURN

应转换为明确的Helix结果结构，除非路由确实需要，否则不要隐式返回完整对象。

DISTINCT

Use

dedup()

before shaping or returning results.

在构造或返回结果前使用

dedup()

。

MERGE

There is no single drop-in

MERGE

translation pattern in this skill. Use explicit read-first branching with

var_as_if

本技能中没有单一的直接替代

MERGE

的转换模式。请使用

var_as_if

进行显式的先读后分支处理。

OPTIONAL MATCH

Use

.optional(sub(...))

when a related traversal should not eliminate the root path just because the optional branch has no match.

当相关遍历不应因可选分支无匹配而排除根路径时，使用

.optional(sub(...))

。

CASE WHEN

Use

.choose(...)

for traversal-level if/then/else logic.

使用

.choose(...)

实现遍历级别的if/then/else逻辑。

UNWIND And FOREACH

UNWIND 和 FOREACH

Use

for_each_param(...)

when a write route needs to iterate an array parameter and perform graph work per element.

当写路由需要迭代数组参数并对每个元素执行图操作时，使用

for_each_param(...)

。

Multi-Hop Patterns

多跳模式

Use bounded

repeat(RepeatConfig::new(...).times(N).emit_after())

for Cypher patterns like

[:REL*1..N]

对于类似

[:REL*1..N]

的Cypher模式，使用带边界的

repeat(RepeatConfig::new(...).times(N).emit_after())

。

IS NULL And Property Existence

IS NULL 和属性存在性

Use

Predicate::is_null

for null-style checks and

Predicate::has_key

when the query is really testing whether the property exists.

使用

Predicate::is_null

进行空值风格检查，当查询实际是测试属性是否存在时，使用

Predicate::has_key

。

Server-Side Timestamps

服务器端时间戳

Use the server-side timestamp helper from your current Helix build when translating Cypher

timestamp()

usage.

转换Cypher的

timestamp()

用法时，请使用当前Helix构建中的服务器端时间戳工具。

Canonical Example

标准示例

Cypher:

cypher

MATCH (u:User {userId: $userId})-[:FOLLOWS]->(v:User)
WHERE v.status = $status
RETURN v
ORDER BY v.createdAt DESC
LIMIT $limit

Helix Rust DSL:

rust

read_batch()
    .var_as(
        "user",
        g().n_with_label("User")
            .where_(Predicate::eq_param("userId", "userId")),
    )
    .var_as(
        "results",
        g().n(NodeRef::var("user"))
            .out(Some("FOLLOWS"))
            .where_(Predicate::eq_param("status", "status"))
            .order_by("createdAt", Order::Desc)
            .limit(Expr::param("limit"))
            .project(vec![
                PropertyProjection::new("$id"),
                PropertyProjection::new("userId"),
                PropertyProjection::new("name"),
                PropertyProjection::new("status"),
                PropertyProjection::new("createdAt"),
            ]),
    )
    .returning(["results"])

Cypher：

cypher

MATCH (u:User {userId: $userId})-[:FOLLOWS]->(v:User)
WHERE v.status = $status
RETURN v
ORDER BY v.createdAt DESC
LIMIT $limit

Helix Rust DSL：

rust

read_batch()
    .var_as(
        "user",
        g().n_with_label("User")
            .where_(Predicate::eq_param("userId", "userId")),
    )
    .var_as(
        "results",
        g().n(NodeRef::var("user"))
            .out(Some("FOLLOWS"))
            .where_(Predicate::eq_param("status", "status"))
            .order_by("createdAt", Order::Desc)
            .limit(Expr::param("limit"))
            .project(vec![
                PropertyProjection::new("$id"),
                PropertyProjection::new("userId"),
                PropertyProjection::new("name"),
                PropertyProjection::new("status"),
                PropertyProjection::new("createdAt"),
            ]),
    )
    .returning(["results"])

Anti-Patterns

反模式

Do not:

translate Cypher by string substitution alone
ignore edge direction
preserve Cypher variable names if they conflict with the local Helix route style and make the translation worse
assume every Cypher clause is a single-token replacement in Helix
return every property by default just because the Cypher query returned a node variable
invent labels, properties, or edge names instead of reading the target schema

请勿：

仅通过字符串替换来转换Cypher
忽略边方向
如果Cypher变量名与本地Helix路由风格冲突且会降低转换质量，仍保留这些变量名
假设每个Cypher子句在Helix中都有单一令牌替代
仅仅因为Cypher查询返回了节点变量就默认返回所有属性
自行创建标签、属性或边名称，而不读取目标模式

Validation Checklist

验证清单

Before finishing:

verify the first anchor is correct and narrow enough
verify edge directions are translated correctly
verify
```
WHERE
```
clauses became explicit
```
Predicate
```
logic
verify optional traversals use
```
optional(sub(...))
```
when required
verify multi-hop traversal uses bounded
```
repeat(...)
```
with explicit emission behavior
verify
```
RETURN
```
became an intentional Helix output shape
verify
```
DISTINCT
```
,
```
ORDER BY
```
,
```
SKIP
```
, and
```
LIMIT
```
were mapped deliberately
verify
```
CASE
```
,
```
UNWIND
```
,
```
FOREACH
```
, delete, and timestamp logic were translated to Helix-native constructs when present
verify
```
MERGE
```
was translated semantically, not literally
verify labels, edge labels, and properties match the local repo exactly

完成转换前：

验证首个锚点正确且足够精准
验证边方向转换正确
验证
```
WHERE
```
子句已转换为显式
```
Predicate
```
逻辑
验证可选遍历在需要时使用了
```
optional(sub(...))
```
验证多跳遍历使用了带边界的
```
repeat(...)
```
并具有显式的触发行为
验证
```
RETURN
```
已转换为明确的Helix输出结构
验证
```
DISTINCT
```
、
```
ORDER BY
```
、
```
SKIP
```
和
```
LIMIT
```
已被有意映射
验证
```
CASE
```
、
```
UNWIND
```
、
```
FOREACH
```
、删除和时间戳逻辑在存在时已转换为Helix原生结构
验证
```
MERGE
```
已进行语义转换而非字面转换
验证标签、边标签和属性与本地仓库完全匹配

Repo References

仓库参考

For shared references in this repo, see:

```
docs/cypher-rosetta.md
```
```
docs/dsl-cheatsheet.md
```
```
examples/authoring-patterns.md
```
```
examples/search-patterns.md
```

有关本仓库中的共享参考，请查看：

```
docs/cypher-rosetta.md
```
```
docs/dsl-cheatsheet.md
```
```
examples/authoring-patterns.md
```
```
examples/search-patterns.md
```