什么是 nGQL¶

nGQL（NebulaGraph Query Language）是 NebulaGraph 使用的的声明式图查询语言，支持灵活高效的图模式，而且 nGQL 是为开发和运维人员设计的类 SQL 查询语言，易于学习。

nGQL 是一个进行中的项目，会持续发布新特性和优化，因此可能会出现语法和实际操作不一致的问题，如果遇到此类问题，请提交 issue 通知 NebulaGraph 团队。NebulaGraph 3.0 及更新版本正在支持 openCypher 9。

nGQL 可以做什么¶

支持图遍历

支持模式匹配

支持聚合

支持修改图

支持访问控制

支持聚合查询

支持索引

支持大部分 openCypher 9 图查询语法（不支持修改和控制语法）

示例数据 Basketballplayer¶

用户可以下载 NebulaGraph 示例数据 basketballplayer 文件，然后使用 NebulaGraph Console，使用选项-f执行脚本。

Note

导入示例数据前，确保已执行ADD HOSTS命令将 Storage 主机增加至集群中。更多信息，请参见管理 Storage 主机。

占位标识符和占位符值¶

NebulaGraph 查询语言 nGQL 参照以下标准设计：

(Draft) ISO/IEC JTC1 N14279 SC 32 - Database_Languages - GQL

(Draft) ISO/IEC JTC1 SC32 N3228 - SQL_Property_Graph_Queries - SQLPGQ

OpenCypher 9

在模板代码中，任何非关键字、字面值或标点符号的标记都是占位符标识符或占位符值。

本文中 nGQL 语法符号的说明如下。

符号	含义
< >	语法元素的名称。
:	定义元素的公式。
[ ]	可选元素。
{ }	显式的指定元素。
\|	所有可选的元素。
...	可以重复多次。

例如创建点的 nGQL 语法：

INSERT VERTEX [IF NOT EXISTS] [tag_props, [tag_props] ...]
VALUES <vid>: ([prop_value_list])

tag_props:
  tag_name ([prop_name_list])

prop_name_list:
   [prop_name [, prop_name] ...]

prop_value_list:
   [prop_value [, prop_value] ...]

示例语句：

nebula> CREATE TAG IF NOT EXISTS player(name string, age int);

关于 openCypher 兼容性¶

原生 nGQL 和 openCypher 的关系¶

原生 nGQL 是由 NebulaGraph 自行创造和实现的图查询语言。openCypher 是由 openCypher Implementers Group 组织所开源和维护的图查询语言，最新版本为 openCypher 9。

由于 nGQL 语言部分兼容了 openCypher，这个部分在本文中称为 openCypher 兼容语句。

Note

nGQL 语言 = 原生 nGQL 语句 + openCypher 兼容语句

nGQL 完全兼容 openCypher 9 吗？¶

不。

openCypher 兼容性

nGQL 设计目标仅为兼容部分的 DQL 语句(match, optional match, with等)。

不计划兼容任何 DDL，DML，DCL；

不计划兼容 Bolt 协议；

不计划兼容 APOC 与 GDS。

在本文搜索 "compatibility" 或者 “兼容性” 查看具体不兼容的细节。

在 NebulaGraph Issues 中已经列出已知的兼容错误。如果发现这种类型的新问题，请提交问题并附带incompatible标签。

nGQL 和 openCypher 9 的主要差异有哪些？¶

类别	openCypher 9	nGQL
Schema	弱 Schema	强 Schema
相等运算符	`=`	`==`
数学求幂	`^`	使用`pow(x, y)`替代`^`。
边 Rank	无此概念	用`@rank`设置。
语句	-	不支持 openCypher 9 的所有 DML 语句（如`CREATE`、`MERGE`等），不支持所有的 DCL，和支持部分 `MATCH`, `OPTIONAL MATCH` 语法和函数。
语句文本换行	换行符	`\` + 换行符
Label 与 Tag 是不同的概念	Label 用于寻找点（点的索引）。	Tag 用于定义点的一种类型及相应的属性，无索引功能。
预编译与参数化查询	支持	仅支持参数化查询。

Compatibility

请注意 openCypher 9 和 Cypher 在语法和许可上有不同：

Cypher 要求所有 Cypher 语句必须“显式地在一个事务中”执行，而 openCypher 没有这样的要求。另外，nGQL 没有事务及隔离性。
Cypher 企业版功能有多种的约束（constraints），包括 Unique node property constraints、Node property existence constraints、Relationship property existence constraints、Node key constraints。 OpenCypher 标准中没有约束。而 nGQL 是强 Schema 系统，前述的约束大多通过 Schema 定义可实现（包括 NOT NULL），唯一不能支持的功能是“属性值唯一性”（UNIQUE constraint）。
Cypher 有 APoC，openCypher 9 没有 APoC。Cypher 有 Blot 协议支持要求， openCypher 9 没有。

哪里可以找到更多 nGQL 的示例？¶

用户可以在 NebulaGraph GitHub 的 features 目录内查看超过 2500 条 nGQL 示例。

features 目录内包含很多。features 格式的文件，每个文件都记录了使用 nGQL 的场景和示例。例如：

Feature: Basic match

  Background:
    Given a graph with space named "basketballplayer"

  Scenario: Single node
    When executing query:
      """
      MATCH (v:player {name: "Yao Ming"}) RETURN v;
      """
    Then the result should be, in any order, with relax comparison:
      | v                                                |
      | ("player133" :player{age: 38, name: "Yao Ming"}) |

  Scenario: One step
    When executing query:
      """
      MATCH (v1:player{name: "LeBron James"}) -[r]-> (v2)
      RETURN type(r) AS Type, v2.player.name AS Name
      """
    Then the result should be, in any order:

      | Type     | Name        |
      | "follow" | "Ray Allen" |
      | "serve"  | "Lakers"    |
      | "serve"  | "Heat"      |
      | "serve"  | "Cavaliers" |

Feature:  Comparison of where clause

  Background:
    Given a graph with space named "basketballplayer"

    Scenario: push edge props filter down
      When profiling query:
        """
        GO FROM "player100" OVER follow 
        WHERE properties(edge).degree IN [v IN [95,99] WHERE v > 0] 
        YIELD dst(edge), properties(edge).degree
        """
      Then the result should be, in any order:
        | follow._dst | follow.degree |
        | "player101" | 95            |
        | "player125" | 95            |
      And the execution plan should be:
        | id | name         | dependencies | operator info                                                         |
        | 0  | Project      | 1            |                                                                       |
        | 1  | GetNeighbors | 2            | {"filter": "(properties(edge).degree IN [v IN [95,99] WHERE (v>0)])"} |
        | 2  | Start        |              |                                                                       |

示例中的关键字说明如下。

关键字	说明
`Feature`	描述当前文档的主题。
`Background`	描述当前文档的背景信息。
`Given`	描述执行示例语句的前提条件。
`Scenario`	描述具体场景。如果场景之前有`@skip`标识，表示这个场景下示例语句可能无法正常工作，请不要在生产环境中使用该示例语句。
`When`	描述要执行的 nGQL 示例语句。可以是`executing query`或`profiling query`。
`Then`	描述执行`When`内语句的预期返回结果。如果返回结果和文档不同，请提交 issue 通知 NebulaGraph 团队。
`And`	描述执行`When`内语句的副作用或执行计划。
`@skip`	跳过这个示例。通常表示测试代码还没有准备好。

欢迎增加更多 tck case，在 CI/CD 中自动回归所使用的语句。

是否支持 TinkerPop Gremlin？¶

不支持。也没有计划。

是否支持 W3C 的 RDF（SPARQL）或 GraphQL 等？¶

不支持。也没有计划。

NebulaGraph 的数据模型是属性图，是一个强 Schema 系统，不支持 RDF 标准。

nGQL 也不支持 SPARQL 和 GraphQL。

最后更新: February 23, 2023