跳转至

什么是 nGQL

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

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

nGQL 可以做什么

  • 支持图遍历
  • 支持模式匹配
  • 支持聚合
  • 支持修改图
  • 支持访问控制
  • 支持聚合查询
  • 支持索引
  • 支持大部分 openCypher 9 图查询语法(不支持修改和控制语法)

示例数据 Basketballplayer

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

Note

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

占位标识符和占位符值

Nebula Graph 查询语言 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 是由 Nebula Graph 自行创造和实现的图查询语言。openCypher 是由 openCypher Implementers Group 组织所开源和维护的图查询语言,最新版本为 openCypher 9。

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

Note

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

行为未定义

不要在同一个复合语句中,同时使用原生 nGQL 语句openCypher 兼容语句,其行为是未定义的。

nGQL 完全兼容 openCypher 9 吗?

不。

openCypher 兼容性

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

不计划兼容任何 DDL,DML,DCL;

不计划兼容 Bolt 协议;

不计划兼容 APOC 与 GDS。

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

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

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

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

Compatibility

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

  1. Cypher 要求所有 Cypher 语句必须“显式地在一个事务中”执行,而 openCypher 没有这样的要求。另外,nGQL 没有事务及隔离性。

  2. 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)。

  3. Cypher 有 APoC,openCypher 9 没有 APoC。Cypher 有 Blot 协议支持要求, openCypher 9 没有。

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

用户可以在 Nebula Graph 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 queryprofiling query
Then 描述执行When内语句的预期返回结果。如果返回结果和文档不同,请提交 issue 通知 Nebula Graph 团队。
And 描述执行When内语句的副作用或执行计划。
@skip 跳过这个示例。通常表示测试代码还没有准备好。

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

是否支持 TinkerPop Gremlin?

不支持。也没有计划。

是否支持 W3C 的 RDF(SPARQL) 或 GraphQL 等?

不支持。也没有计划。

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

nGQL 也不支持 SPARQL 和 GraphQL。


最后更新: March 7, 2023