Nebula Graph Query Language (nGQL)¶

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

What is nGQL¶

nGQL is a declarative graph query language for Nebula Graph. 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 Nebula Graph team if you find a new issue of this type. Nebula Graph 2.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 Nebula Graph. After downloading the example data, you can import it to Nebula Graph by using the -f option in Nebula Graph Console.

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:

For example, create vertices or edges in nGQL syntax:

CREATE {TAG | EDGE} {<tag_name> | <edge_type>}(<property_name> <data_type>
[, <property_name> <data_type> ...]);

Example statement:

nebula> CREATE TAG 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 Nebula Graph. 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).

Is nGQL compatible with openCypher 9 completely?¶

NO.

What are the major differences between nGQL and openCypher 9?¶

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

Where can I find more nGQL examples?¶

Users can find more than 2500 nGQL examples in the features directory on the Nebula Graph 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

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

The keywords in the preceding example are described as follows.

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 Nebula Graph support W3C RDF (SPARQL) or GraphQL?¶

No. And no plan to support that.

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

Nebula Graph Query Language does not support SPARQL nor GraphQL.