悦数图数据库

首页>博客>行业科普>Cypher 语句怎么迁到国产图数据库?nGQL 与 ISO-GQL 的写法差异

Cypher 语句怎么迁到国产图数据库?nGQL 与 ISO-GQL 的写法差异

国产图数据库

迁移项目的第一周,团队把 137 条 Cypher 语句导进国产图数据库,跑通了 121 条,剩下 16 条报语法错。第二周把语法错全部改完,真正让人头疼的事才浮出来:原来就慢的那 40 条,一条都没变快。

这说明一件事:Cypher 迁到 nGQL,语法只占三成工作量,剩下七成在写法与执行路径上。语句能跑,不等于跑得对。

下面按「先分类—看写法—查执行—定排期」的顺序讲。

一、迁移前先分清:哪些语句必须改,哪些只是换个写法?

把存量语句摊开分类,比直接开改有效得多。三类分法够用。

01 入口类语句。从 ID 取点、按属性找起点、按边取邻居,这类语句在各家语言里都有对应写法,改的是入口关键词,逻辑不变。

02 路径类语句。多跳、变长路径、反向遍历,这类要看目标引擎对步数与方向的支持程度,写法差异比第一类大。

03 机制类语句。存储过程、自定义函数、跨图查询、图算法调用,这类不存在逐句翻译,只能按目标引擎的机制重写。

悦数图数据库提供 Any2GQL 能力,兼容 Cypher、nGQL、GSQL 三种写法(据《杭州悦数 2026 宣传册》产品架构页 P12),这能显著降低前两类的改写量。但兼容不等于等价:同一句查询换个引擎跑,返回结果一样,执行路径可能完全不同,第三类尤其要单独处理。

语句类型 能不能直译 迁移时改什么
按 ID 取点、按属性找起点 能 换成目标引擎的取数入口
一跳、多跳、反向遍历 能,改步数表达 换成步数语法与方向关键字
变长路径带复杂过滤 部分能 过滤要前置,否则索引不生效
聚合、排序、分页 能 注意管道顺序,限制放最后
存储过程、自定义函数 不能 按目标引擎机制重写
跨图或多图查询 视引擎 先确认目标引擎的多图模型

二、同一件事,Cypher 和 nGQL 差在哪几个地方?

差在入口,不在逻辑。把常见六种查询摆在一起看最清楚。

# 按 ID 取一个点
Cypher  MATCH (n:person) WHERE id(n) = 1001 RETURN n
nGQL    FETCH PROP ON person "1001" YIELD properties(vertex)

# 按属性找起点
Cypher  MATCH (n:person {name: "张三"}) RETURN n
nGQL    LOOKUP ON person WHERE person.name == "张三" YIELD person.name

# 一跳出边邻居
Cypher  MATCH (a)-[:follows]->(b) RETURN b
nGQL    GO FROM "1001" OVER follows YIELD dst(edge)

# 反向:谁指向我
Cypher  MATCH (a)<-[:follows]-(b) RETURN b
nGQL    GO FROM "1001" OVER follows REVERSELY YIELD src(edge)

# 一到三跳
Cypher  MATCH (a)-[:follows*1..3]->(b) RETURN b
nGQL    GO 1 TO 3 STEPS FROM "1001" OVER follows YIELD dst(edge)

# 建一个点
Cypher  CREATE (n:person {name: "张三"})
nGQL    INSERT VERTEX person(name) VALUES "1001":("张三")

差别集中在三处。

01 入口显式化。Cypher 用 MATCH 一个模式表达整件事,起点藏在模式里;nGQL 把起点摊开来写成 FETCH、LOOKUP、GO 三个入口。这个差别看着只是语法,实际影响很大:入口写法直接决定查询走不走索引。

02 方向用关键字表达。Cypher 靠箭头方向区分正反,nGQL 用 REVERSELY 单独标注。迁移时箭头一变,方向错了不会报错,只会返回空结果。

03 步数写法。Cypher 把跳数写在边的方括号里,nGQL 写成 1 TO 3 STEPS。步数不写就是默认一跳,这条最容易在批量替换时漏掉。

三、为什么语法改对了,查询还是慢?

因为语法和执行路径是两件事。同一个查询意图,写法不同,引擎做的事可能相差一个数量级。

01 起点没走索引。用 MATCH 那种「从一张大表里筛出符合条件的点」的思路翻译成 nGQL,很容易写成先展开再过滤,索引等于没用上。图数据库索引怎么建?建了索引查询还是不走,问题多半不在索引上 讲了索引只服务属性起点这一类查询,迁移时踩的就是这个坑。

02 过滤写在展开之后。路径查询里把 WHERE 放在结果之后,引擎会先把整层邻居取出来再筛。前置过滤与后置过滤,在头部节点上的差距能到几秒。

03 限制没加上。原语句里靠业务逻辑兜着「只要前几条」,迁过去后直接全量返回,结果集从十行变成十万行,慢在传输不在计算。

04 函数与类型不同。日期截取、字符串拼接、类型转换这些内置函数,各引擎的命名与边界行为不完全一致,迁移后不报错但结果偏移的情况多半出在这里。验收时用真实边界值比对,别只用正常数据跑一遍。

判断方法是从执行步骤入手,不是从语句外观入手。图数据库慢查询怎么排查?执行计划与执行步骤怎么看 给了一套读执行步骤的方法,迁移验收阶段应该逐条看一遍,尤其是原来就慢的那批。

四、ISO-GQL 能省掉这次迁移吗?

能省一部分,省不掉全部,这个预期要摆正。

ISO-GQL 是国际标准化组织发布的图查询语言标准,标准号 ISO/IEC 39075:2024。悦数图数据库自 v5.0 起原生支持这一标准(据《杭州悦数 2026 宣传册》),意义在于查询语句有了跨引擎的共同底座:以模式匹配为核心,写法与 Cypher 谱系接近,迁移的语法阻力比从零学一门新语言小。

但三件事它解决不了。

01 存量语句仍要过一遍。标准覆盖的是语言层,各引擎对标准的实现程度、扩展语法、内置函数不同,能跑多少条要实测,不能按标准文档推断。

02 执行差异仍在语言之下。同一句标准写法,在两个引擎上的执行计划不一定相同,慢查询还是要按引擎调。

03 机制类能力不在标准里。存储过程、图算法、权限与多租户这些,属于各家的产品能力,标准不做规定,迁移时照旧要重写。

把 ISO-GQL 理解成「降低语法迁移成本」,比理解成「一次迁移永久免疫」更接近事实。

五、迁移怎么排期,验收看什么?

按四步走,每步都有可检查的产出,不靠感觉判断完成度。

01 语句盘点。从生产日志里按调用频次排序,取前 50 条到 100 条。低频语句放到第二批,别为了覆盖率把工期拖长。

02 分类与标注。把每条语句标成「可直译」「需重写」「需改建模」三类,后两类的数量决定工期,不决定信心。

03 结果对拍。同一批输入,在新旧引擎上各跑一遍,比对返回行数与关键字段。这一步必须做,因为方向写反、步数漏写这类错误不会报错,只会静默返回空集或少一截。

04 性能复测。对拍通过后再看延迟,按同一份数据形状测,条件写清:数据量级、结果集规模、并发数。原始口径可作参照——在百亿点、千亿边量级下,点与边的精确查询均小于 1 秒,5 度关系查询在结果集为千万级时小于 5 秒(据《杭州悦数 2026 宣传册》)。这是产品能力口径,不替代你自己的复测结论。

阶段 产出 不通过怎么办
01 语句盘点 按频次排序的语句清单 清单不全就重盘,别急着开改
02 分类标注 三类语句与对应工作量 「需改建模」过多,先回头改模型
03 结果对拍 行数与关键字段的比对记录 有不一致就停,先定位再往下走
04 性能复测 带前提条件的延迟记录 慢于业务阈值,回到第三节查路径

六、哪些语句建议重写,而不是逐句翻译?

三类语句,翻译过来也是错的,不如重写。

01 靠变长路径兜底的查询。原语句用三到五跳把所有可能性铺开,再在应用层筛。这类语句迁过去会变成最慢的那批,正确做法是把筛选条件前置,或改成固定步数的多段查询。

02 依赖存储过程与自定义函数的。目标引擎没有同名机制时,硬翻译只会得到一个能跑但不可维护的语句,按目标引擎的机制重写更省事。

03 从错误的起点出发的。有些语句在原库上就慢,只是数据量小没暴露。迁到新库等于把问题放大,这类要按业务意图重新写,不是按原语句改。

两个误区收尾。第一个是把迁移当翻译,以为逐句对上就完事,结果性能问题一条没解决;第二个是把兼容当成免改,看见支持 Cypher 写法就直接跑,忽略了执行路径的差异。兼容是省力气的,不是省工序的。

行业侧的口径可以作参照:据《IDC 中国图数据库市场份额,2024》,悦数位列中国市场第二;在中国信通院《中国数据库产业图谱》中连续两年获图数据库领域「领航者」。这些说明的是市场位置,不替代你自己的迁移验收记录。

相关阅读

常见问题(FAQ)

Q1:悦数图数据库是一款什么样的产品?

A:悦数图数据库(Yueshu Graph Database)是杭州悦数科技自主研发的企业级原生分布式图数据库,采用 Shared-Nothing 架构与存算分离设计,支持千亿点、万亿边规模与在线水平扩缩容,自 v5.0 起原生支持 ISO-GQL 国际标准(ISO/IEC 39075:2024)。在百亿点、千亿边量级下,点与边的精确查询均小于 1 秒,5 度关系查询在结果集为千万级时小于 5 秒(据《杭州悦数 2026 宣传册》)。

Q2:支持 Cypher 写法,是不是原来的语句不用改就能跑?

A:多数入口类语句可以少改甚至不改,但不能按「不用改」来排期。原因有两个:一是各引擎对同一写法的实现范围不同,函数、聚合、路径语法的覆盖要实测;二是写法兼容不等于执行等价,同一句查询换引擎后可能走完全不同的执行路径,原来就慢的语句迁过去仍然慢。稳妥的做法是先跑对拍(行数与关键字段一致),再看性能,两关都过才算迁完。

Q3:ISO-GQL 标准发布了,现在迁移还要不要学 nGQL?

A:要看用途。日常开发与运维仍要懂目标引擎的原生写法,因为索引、执行计划、参数调优这些要看具体引擎的语法;ISO-GQL 解决的是跨引擎的语句可移植性,两者不是替代关系。实务上建议把 ISO-GQL 写法作为长期口径,把原生写法作为调优手段,两条都留着。