Overview of NebulaGraph general query statements¶

This topic provides an overview of the general categories of query statements in NebulaGraph and outlines their use cases.

Background¶

NebulaGraph stores data in the form of vertices and edges. Each vertex can have zero or more tags and each edge has exactly one edge type. Tags define the type of a vertex and describe its properties, while edge types define the type of an edge and describe its properties. When querying, you can limit the scope of the query by specifying the tag of a vertex or the type of an edge. For more information, see Patterns.

Categories¶

The primary query statements in NebulaGraph fall into the following categories:

FETCH PROP ON
LOOKUP ON
GO
MATCH
FIND PATH
GET SUBGRAPH
SHOW

FETCH PROP ON and LOOKUP ON statements are primarily for basic data queries, GO and MATCH for more intricate queries and graph traversals, FIND PATH and GET SUBGRAPH for path and subgraph queries, and SHOW for retrieving database metadata.

Usage and use cases¶

FETCH PROP ON¶

Usage: Retrieve properties of a specified vertex or edge.

Use case: Knowing the specific vertex or edge ID and wanting to retrieve its properties.

Note:

Must specify the ID of the vertex or edge.
Must specify the tag of the vertex or the edge type of the edge.
Must use the YIELD clause to specify the returned properties.

Example:

FETCH PROP ON player "player100" YIELD properties(vertex);
              --+---  ----+-----       -------+----------
                |         |                   |
                |         |                   |
                |         |                   +--------- Returns all properties under the player tag of the vertex.
                |         |
                |         +----------------- Retrieves from the vertex "player100".
                |
                +--------------------------- Retrieves properties under the player tag.

For more information, see FETCH PROP ON.

LOOKUP ON¶

Usage: Index-based querying of vertex or edge IDs.

Use case: Finding vertex or edge IDs based on property values.

Note: - Must pre-define indexes for the tag, edge type, or property. - Must specify the tag of the vertex or the edge type of the edge. - Must use the YIELD clause to specify the returned IDs.

Example:

LOOKUP ON player WHERE player.name == "Tony Parker" YIELD id(vertex);
          --+--- ------------------+---------------       ---+------
            |                      |                         |
            |                      |                         |
            |                      |                         +---- Returns the VID of the retrieved vertex.
            |                      |
            |                      +------------ Filtering is based on the value of the property name.
            |
            +----------------------------------- Queries based on the player tag.

For more information, see LOOKUP ON.

GO¶

Usage: Traverse the graph based on a given vertex and return information about the starting vertex, edges, or target vertices as needed. Use case: Complex graph traversals, such as finding friends of a vertex, friends' friends, etc.

Note: - Use property reference symbols ($^ and $$) to return properties of the starting or target vertices, e.g., YIELD $^.player.name. - Use the functions properties($^) and properties($$) to return all properties of the starting or target vertices. Specify property names in the function to return specific properties, e.g., YIELD properties($^).name. - Use the functions src(edge) and dst(edge) to return the starting or destination vertex ID of an edge, e.g., YIELD src(edge).

Example:

GO 3 STEPS FROM "player102" OVER follow YIELD dst(edge);
-----+---       --+-------       -+----       ---+-----
     |            |               |              |
     |            |               |              |
     |            |               |              +--------- Returns the destination vertex of the last hop.
     |            |               |
     |            |               +------ Traverses out via the edge follow.
     |            |
     |            +--------------------- Starts from "player102".
     |
     +---------------------------------- Traverses 3 steps.

For more information, see GO.

MATCH¶

Usage: Execute complex graph pattern matching queries.

Use case: Complex graph pattern matching, such as finding combinations of vertices and edges that satisfy a specific pattern.

Note:

MATCH statements are compatible with the OpenCypher syntax but with some differences:

Use == for equality instead of =, e.g., WHERE player.name == "Tony Parker".
When referencing properties of vertices, you need to specify the vertex's tag, e.g., YIELD player.name.
Introduces the WHERE id(v) == "player100" syntax.
Must use the RETURN clause to specify what information to return.

Example:

MATCH (v:player{name:"Tim Duncan"})-->(v2:player) \
        RETURN v2.player.name AS Name;

For more information, see MATCH.

FIND PATH¶

Usage: Query paths between given starting and target vertices or query properties of vertices and edges along paths.

Use case: Querying paths between two vertices.

Note: Must use the YIELD clause to specify returned information.

Example:

FIND SHORTEST PATH FROM "player102" TO "team204" OVER * YIELD path AS p;
-------+-----           -------+---------------- ---+--       ----+----
       |                       |                    |             |
       |                       |                    |             |
       |                       |                    |             +---------- Returns the path as 'p'.
       |                       |                    |
       |                       |                    +----------- Travels outwards via all types of edges.
       |                       |    
       |                       |
       |                       +------------------ From the given starting and target VIDs.  
       |
       +--------------------------- Retrieves the shortest path.

For more information, see FIND PATH.

GET SUBGRAPH¶

Usage: Extract a portion of the graph that satisfies specific conditions or query properties of vertices and edges in the subgraph.

Use case: Analyzing structures of the graph or specific regions, such as extracting the social network subgraph of a person or the transportation network subgraph of an area.

Note: Must use the YIELD clause to specify returned information.

Example:

GET SUBGRAPH 5 STEPS FROM "player101" YIELD VERTICES AS nodes, EDGES AS relationships;
             -----+- -----+--------         ------------------------+----------------
                  |       |                                         |
                  |       |                                         |
                  |       +------- Starts from "player101".         +------------ Returns all vertices and edges.
                  |
                  +----------------- Gets exploration of 5 steps

For more information, see GET SUBGRAPH.

SHOW¶

SHOW statements are mainly used to obtain metadata information from the database, not for retrieving the actual data stored in the database. These statements are typically used to query the structure and configuration of the database.

Statement	Syntax	Example	Description
SHOW CHARSET	`SHOW CHARSET`	`SHOW CHARSET`	Shows the available character sets.
SHOW COLLATION	`SHOW COLLATION`	`SHOW COLLATION`	Shows the collations supported by NebulaGraph.
SHOW CREATE SPACE	`SHOW CREATE SPACE <space_name>`	`SHOW CREATE SPACE basketballplayer`	Shows the creating statement of the specified graph space.
SHOW CREATE TAG/EDGE	`SHOW CREATE {TAG <tag_name> \| EDGE <edge_name>}`	`SHOW CREATE TAG player`	Shows the basic information of the specified tag.
SHOW HOSTS	`SHOW HOSTS [GRAPH \| STORAGE \| META]`	`SHOW HOSTS` `SHOW HOSTS GRAPH`	Shows the host and version information of Graph Service, Storage Service, and Meta Service.
SHOW INDEX STATUS	`SHOW {TAG \| EDGE} INDEX STATUS`	`SHOW TAG INDEX STATUS`	Shows the status of jobs that rebuild native indexes, which helps check whether a native index is successfully rebuilt or not.
SHOW INDEXES	`SHOW {TAG \| EDGE} INDEXES`	`SHOW TAG INDEXES`	Shows the names of existing native indexes.
SHOW PARTS	`SHOW PARTS [<part_id>]`	`SHOW PARTS`	Shows the information of a specified partition or all partitions in a graph space.
SHOW ROLES	`SHOW ROLES IN <space_name>`	`SHOW ROLES in basketballplayer`	Shows the roles that are assigned to a user account.
SHOW SNAPSHOTS	`SHOW SNAPSHOTS`	`SHOW SNAPSHOTS`	Shows the information of all the snapshots.
SHOW SPACES	`SHOW SPACES`	`SHOW SPACES`	Shows existing graph spaces in NebulaGraph.
SHOW STATS	`SHOW STATS`	`SHOW STATS`	Shows the statistics of the graph space collected by the latest `STATS` job.
SHOW TAGS/EDGES	`SHOW TAGS \| EDGES`	`SHOW TAGS`,`SHOW EDGES`	Shows all the tags in the current graph space.
SHOW USERS	`SHOW USERS`	`SHOW USERS`	Shows the user information.
SHOW SESSIONS	`SHOW SESSIONS`	`SHOW SESSIONS`	Shows the information of all the sessions.
SHOW SESSIONS	`SHOW SESSION <Session_Id>`	`SHOW SESSION 1623304491050858`	Shows a specified session with its ID.
SHOW QUERIES	`SHOW [ALL] QUERIES`	`SHOW QUERIES`	Shows the information of working queries in the current session.
SHOW META LEADER	`SHOW META LEADER`	`SHOW META LEADER`	Shows the information of the leader in the current Meta cluster.

Compound queries¶

Query statements in NebulaGraph can be combined to achieve more complex queries.

When referencing the results of a subquery in a compound statement, you need to create an alias for the result and use the pipe symbol(|) to pass it to the next subquery. Use $- in the next subquery to reference the alias of that result. See Pipe Symbol for details.

Example:

nebula> GO FROM "player100" OVER follow \
        YIELD dst(edge) AS dstid, properties($$).name AS Name | \
        GO FROM $-.dstid OVER follow YIELD dst(edge);
+-------------+
| dst(EDGE)   |
+-------------+
| "player100" |
| "player102" |
| "player125" |
| "player100" |
+-------------+

The pipe symbol | is applicable only in nGQL and cannot be used in OpenCypher statements. If you need to perform compound queries using MATCH statements, you can use the WITH clause.

Example:

nebula> MATCH (v:player)-->(v2:player) \
        WITH DISTINCT v2 AS v2, v2.player.age AS Age \
        ORDER BY Age \
        WHERE Age<25 \
        RETURN v2.player.name AS Name, Age;
+----------------------+-----+
| Name                 | Age |
+----------------------+-----+
| "Luka Doncic"        | 20  |
| "Ben Simmons"        | 22  |
| "Kristaps Porzingis" | 23  |
+----------------------+-----+

More information¶

nGQL command cheatsheet

Last update: January 30, 2024