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