Skip to content

NebulaGraph Query Language (nGQL)

This topic gives an introduction to the query language of NebulaGraph, nGQL.

What is nGQL

nGQL is a declarative graph query language for NebulaGraph. It allows expressive and efficient graph patterns. nGQL is designed for both developers and operations professionals. nGQL is an SQL-like query language, so it's easy to learn.

nGQL is a project in progress. New features and optimizations are done steadily. There can be differences between syntax and implementation. Submit an issue to inform the NebulaGraph team if you find a new issue of this type. NebulaGraph 3.0 or later releases will support openCypher 9.

What can nGQL do

  • Supports graph traversals
  • Supports pattern match
  • Supports aggregation
  • Supports graph mutation
  • Supports access control
  • Supports composite queries
  • Supports index
  • Supports most openCypher 9 graph query syntax (but mutations and controls syntax are not supported)

Example data Basketballplayer

Users can download the example data Basketballplayer in NebulaGraph. After downloading the example data, you can import it to NebulaGraph by using the -f option in NebulaGraph Console.


Ensure that you have executed the ADD HOSTS command to add the Storage service to your NebulaGraph cluster before importing the example data. For more information, see Manage Storage hosts.

Placeholder identifiers and values

Refer to the following standards in nGQL:

  • (Draft) ISO/IEC JTC1 N14279 SC 32 - Database_Languages - GQL
  • (Draft) ISO/IEC JTC1 SC32 N3228 - SQL_Property_Graph_Queries - SQLPGQ
  • OpenCypher 9

In template code, any token that is not a keyword, a literal value, or punctuation is a placeholder identifier or a placeholder value.

For details of the symbols in nGQL syntax, see the following table:

Token Meaning
< > name of a syntactic element
: formula that defines an element
[ ] optional elements
{ } explicitly specified elements
| complete alternative elements
... may be repeated any number of times

For example, create vertices in nGQL syntax:

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

Example statement:

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

About openCypher compatibility

Native nGQL and openCypher

Native nGQL is the part of a graph query language designed and implemented by NebulaGraph. OpenCypher is a graph query language maintained by openCypher Implementers Group.

The latest release is openCypher 9. The compatible parts of openCypher in nGQL are called openCypher compatible sentences (short as openCypher).


nGQL = native nGQL + openCypher compatible sentences

Is nGQL compatible with openCypher 9 completely?


Compatibility with openCypher

nGQL is designed to be compatible with part of DQL (match, optional match, with, etc.).

  • It is not planned to be compatible with any DDL, DML, or DCL.
  • It is not planned to be compatible with the Bolt Protocol.
  • It is not planned to be compatible with APOC and GDS.

Users can search in this manual with the keyword compatibility to find major compatibility issues.

Multiple known incompatible items are listed in NebulaGraph Issues. Submit an issue with the incompatible tag if you find a new issue of this type.

What are the major differences between nGQL and openCypher 9?

The following are some major differences (by design incompatible) between nGQL and openCypher.

Category openCypher 9 nGQL
Schema Optional Schema Strong Schema
Equality operator = ==
Math exponentiation ^ ^ is not supported. Use pow(x, y) instead.
Edge rank No such concept. edge rank (reference by @)
Statement - All DMLs (CREATE, MERGE, etc) of openCypher 9.
Label and tag A label is used for searching a vertex, namely an index of vertex. A tag defines the type of a vertex and its corresponding properties. It cannot be used as an index.
Pre-compiling and parameterized queries Support Parameterized queries are supported, but precompiling is not.


OpenCypher 9 and Cypher have some differences in grammar and licence. For example,

  1. Cypher requires that All Cypher statements are explicitly run within a transaction. While openCypher has no such requirement. And nGQL does not support transactions.

  2. Cypher has a variety of constraints, including Unique node property constraints, Node property existence constraints, Relationship property existence constraints, and Node key constraints. While OpenCypher has no such constraints. As a strong schema system, most of the constraints mentioned above can be solved through schema definitions (including NOT NULL) in nGQL. The only function that cannot be supported is the UNIQUE constraint.

  3. Cypher has APoC, while openCypher 9 does not have APoC. Cypher has Blot protocol support requirements, while openCypher 9 does not.

Where can I find more nGQL examples?

Users can find more than 2500 nGQL examples in the features directory on the NebulaGraph GitHub page.

The features directory consists of .feature files. Each file records scenarios that you can use as nGQL examples. Here is an example:

Feature: Basic match

    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, 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

    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 | |
        | "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        |              |                                                             |

The keywords in the preceding example are described as follows.

Keyword Description
Feature Describes the topic of the current .feature file.
Background Describes the background information of the current .feature file.
Given Describes the prerequisites of running the test statements in the current .feature file.
Scenario Describes the scenarios. If there is the @skip before one Scenario, this scenario may not work and do not use it as a working example in a production environment.
When Describes the nGQL statement to be executed. It can be a executing query or profiling query.
Then Describes the expected return results of running the statement in the When clause. If the return results in your environment do not match the results described in the .feature file, submit an issue to inform the NebulaGraph team.
And Describes the side effects of running the statement in the When clause.
@skip This test case will be skipped. Commonly, the to-be-tested code is not ready.

Welcome to add more tck case and return automatically to the using statements in CI/CD.

Does it support TinkerPop Gremlin?

No. And no plan to support that.

Does NebulaGraph support W3C RDF (SPARQL) or GraphQL?

No. And no plan to support that.

The data model of NebulaGraph is the property graph. And as a strong schema system, NebulaGraph does not support RDF.

NebulaGraph Query Language does not support SPARQL nor GraphQL.

Last update: November 10, 2023