nGQL cheatsheet¶

Functions¶

Function	Description
double abs(double x)	Returns the absolute value of the argument.
double floor(double x)	Returns the largest integer value smaller than or equal to the argument. (Rounds down)
double ceil(double x)	Returns the smallest integer greater than or equal to the argument. (Rounds up)
double round(double x)	Returns the integer value nearest to the argument. Returns a number farther away from 0 if the argument is in the middle.
double sqrt(double x)	Returns the square root of the argument.
double cbrt(double x)	sReturns the cubic root of the argument.
double hypot(double x, double y)	Returns the hypotenuse of a right-angled triangle.
double pow(double x, double y)	Returns the result of $x^y$.
double exp(double x)	Returns the result of $e^x$.
double exp2(double x)	Returns the result of $2^x$.
double log(double x)	Returns the base-e logarithm of the argument.
double log2(double x)	Returns the base-2 logarithm of the argument.
double log10(double x)	Returns the base-10 logarithm of the argument.
double sin(double x)	Returns the sine of the argument.
double asin(double x)	Returns the inverse sine of the argument.
double cos(double x)	Returns the cosine of the argument.
double acos(double x)	Returns the inverse cosine of the argument.
double tan(double x)	Returns the tangent of the argument.
double atan(double x)	Returns the inverse tangent of the argument.
double rand()	Returns a random floating point number in the range from 0 (inclusive) to 1 (exclusive); i.e.[0,1).
int rand32(int min, int max)	Returns a random 32-bit integer in `[min, max)`. If you set only one argument, it is parsed as `max` and `min` is `0` by default. If you set no argument, the system returns a random signed 32-bit integer.
int rand64(int min, int max)	Returns a random 64-bit integer in `[min, max)`. If you set only one argument, it is parsed as `max` and `min` is `0` by default. If you set no argument, the system returns a random signed 64-bit integer.
collect()	Puts all the collected values into a list.
avg()	Returns the average value of the argument.
count()	Returns the number of records.
max()	Returns the maximum value.
min()	Returns the minimum value.
std()	Returns the population standard deviation.
sum()	Returns the sum value.
bit_and()	Bitwise AND.
bit_or()	Bitwise OR.
bit_xor()	Bitwise XOR.
int size()	Returns the number of elements in a list or a map.
int range(int start, int end, int step)	Returns a list of integers from `[start,end]` in the specified steps. `step` is 1 by default.
int sign(double x)	Returns the signum of the given number. If the number is 0, the system returns 0. If the number is negative, the system returns -1. If the number is positive, the system returns 1.
double e()	Returns the base of the natural logarithm, e (2.718281828459045).
double pi()	Returns the mathematical constant pi (3.141592653589793).
double radians()	Converts degrees to radians. `radians(180)` returns `3.141592653589793`.

String functions

Function	Description
int strcasecmp(string a, string b)	Compares string a and b without case sensitivity. When a = b, the return value is 0. When a > b, the return value is greater than 0. When a < b, the return value is less than 0.
string lower(string a)	Returns the argument in lowercase.
string toLower(string a)	The same as `lower()`.
string upper(string a)	Returns the argument in uppercase.
string toUpper(string a)	The same as `upper()`.
int length(string a)	Returns the length of the given string in bytes.
string trim(string a)	Removes leading and trailing spaces.
string ltrim(string a)	Removes leading spaces.
string rtrim(string a)	Removes trailing spaces.
string left(string a, int count)	Returns a substring consisting of `count` characters from the left side of string a. If string a is shorter than `count`, the system returns string a.
string right(string a, int count)	Returns a substring consisting of `count` characters from the right side of string a. If string a is shorter than `count`, the system returns string a.
string lpad(string a, int size, string letters)	Left-pads string a with string `letters` and returns a substring with the length of `size`.
string rpad(string a, int size, string letters)	Right-pads string a with string `letters` and returns a substring with the length of `size`.
string substr(string a, int pos, int count)	Returns a substring extracting `count` characters starting from the specified position `pos` of string a.
string substring(string a, int pos, int count)	The same as `substr()`.
string reverse(string)	Returns a string in reverse order.
string replace(string a, string b, string c)	Replaces string b in string a with string c.
list split(string a, string b)	Splits string a at string b and returns a list of strings.
string toString()	Takes in any data type and converts it into a string.
int hash()	Takes in any data type and encodes it into a hash value.

Data and time functions

Function	Description
int now()	Returns the current date and time of the system time zone.
timestamp timestamp()	Returns the current date and time of the system time zone.
date date()	Returns the current UTC date based on the current system.
time time()	Returns the current UTC time based on the current system.
datetime datetime()	Returns the current UTC date and time based on the current system.

Schema functions

Function	Description
id(vertex)	Returns the ID of a vertex. The data type of the result is the same as the vertex ID.
map properties(vertex)	Returns the properties of a vertex.
map properties(edge)	Returns the properties of an edge.
string type(edge)	Returns the edge type of an edge.
src(edge)	Returns the source vertex ID of an edge. The data type of the result is the same as the vertex ID.
dst(edge)	Returns the destination vertex ID of an edge. The data type of the result is the same as the vertex ID.
int rank(edge)	Returns the rank value of an edge.

List functions

Function	Description
keys(expr)	Returns a list containing the string representations for all the property names of vertices, edges, or maps.
labels(vertex)	Returns the list containing all the tags of a vertex.
nodes(path)	Returns the list containing all the vertices in a path.
range(start, end [, step])	Returns the list containing all the fixed-length steps in `[start,end]`. `step` is 1 by default.
relationships(path)	Returns the list containing all the relationships in a path.
reverse(list)	Returns the list reversing the order of all elements in the original list.
tail(list)	Returns all the elements of the original list, excluding the first one.
head(list)	Returns the first element of a list.
last(list)	Returns the last element of a list.
coalesce(list)	Returns the first not null value in a list.
reduce()	See reduce() function。

count() function

Function	Description
count()	Syntax: `count({expr \| *})` . `count()`returns the number of rows (including NULL). `count(expr)`returns the number of non-NULL values that meet the expression. count() and size() are different.

collect() function

Function	Description
collect()	The collect() function returns a list containing the values returned by an expression. Using this function aggregates data by merging multiple records or values into a single list.

reduce() function

Function	Syntax	Description
reduce()	`reduce(<accumulator> = <initial>, <variable> IN <list> \| <expression>)`	The `reduce()` function applies an expression to each element in a list one by one, chains the result to the next iteration by taking it as the initial value, and returns the final result.

hash() function

Function	Description
hash()	The `hash()` function returns the hash value of the argument. The argument can be a number, a string, a list, a boolean, null, or an expression that evaluates to a value of the preceding data types. The source code of the `hash()` function (MurmurHash2), seed (`0xc70f6907UL`), and other parameters can be found in `MurmurHash2.h`.

concat() function

Function Description

concat() The concat() function requires at least two or more strings. All the parameters are concatenated into one string.
Syntax: concat(string1,string2,...)

concat_ws() function

Function Description

concat_ws() The concat_ws() function connects two or more strings with a predefined separator.

Predicate functions

Predicate functions return true or false. They are most commonly used in WHERE clauses.

<predicate>(<variable> IN <list> WHERE <condition>)

Functions	Description
exists()	Returns `true` if the specified property exists in the vertex, edge or map. Otherwise, returns `false`.
any()	Returns `true` if the specified predicate holds for at least one element in the given list. Otherwise, returns `false`.
all()	Returns `true` if the specified predicate holds for all elements in the given list. Otherwise, returns `false`.
none()	Returns `true` if the specified predicate holds for no element in the given list. Otherwise, returns `false`.
single()	Returns `true` if the specified predicate holds for exactly one of the elements in the given list. Otherwise, returns `false`.

CASE expressions

The CASE expression uses conditions to filter the result of an nGQL query statement. It is usually used in the YIELD and RETURN clauses. The CASE expression will traverse all the conditions. When the first condition is met, the CASE expression stops reading the conditions and returns the result. If no conditions are met, it returns the result in the ELSE clause. If there is no ELSE clause and no conditions are met, it returns NULL.

Syntax:
```
CASE <comparer>
WHEN <value> THEN <result>
[WHEN ...]
[ELSE <default>]
END
```

Parameter	Description
`comparer`	A value or a valid expression that outputs a value. This value is used to compare with the `value`.
`value`	It will be compared with the `comparer`. If the `value` matches the `comparer`, then this condition is met.
`result`	The `result` is returned by the `CASE` expression if the `value` matches the `comparer`.
`default`	The `default` is returned by the `CASE` expression if no conditions are met.

General queries statements¶

MATCH

MATCH <pattern> [<WHERE clause>] RETURN <output>

Pattern	Example	Description
Match vertices	`(v)`	You can use a user-defined variable in a pair of parentheses to represent a vertex in a pattern. For example: `(v)`.
Match tags	`MATCH (v:player) RETURN v`	You can specify a tag with `:<tag_name>` after the vertex in a pattern.
Match vertex properties	`MATCH (v:player{name:"Tim Duncan"}) RETURN v`	You can specify a vertex property with `{<prop_name>: <prop_value>}` after the tag in a pattern.
Match a VID.	`MATCH (v) WHERE id(v) == 'player101' RETURN v`	You can use the VID to match a vertex. The `id()` function can retrieve the VID of a vertex.
Match multiple VIDs.	`MATCH (v:player { name: 'Tim Duncan' })--(v2) WHERE id(v2) IN ["player101", "player102"] RETURN v2`	To match multiple VIDs, use `WHERE id(v) IN [vid_list]`.
Match connected vertices	`MATCH (v:player{name:"Tim Duncan"})--(v2) RETURN v2.name AS Name`	You can use the `--` symbol to represent edges of both directions and match vertices connected by these edges. You can add a `>` or `<` to the `--` symbol to specify the direction of an edge.
Match paths	`MATCH p=(v:player{name:"Tim Duncan"})-->(v2) RETURN p`	Connected vertices and edges form a path. You can use a user-defined variable to name a path as follows.
Match edges	`MATCH (v:player{name:"Tim Duncan"})-[e]-(v2) RETURN e`	Besides using `--`, `-->`, or `<--` to indicate a nameless edge, you can use a user-defined variable in a pair of square brackets to represent a named edge. For example: `-[e]-`.
Match an edge type	`MATCH ()-[e:follow]-() RETURN e`	Just like vertices, you can specify an edge type with `:<edge_type>` in a pattern. For example: `-[e:follow]-`.
Match edge type properties	`MATCH (v:player{name:"Tim Duncan"})-[e:follow{degree:95}]->(v2) RETURN e`	You can specify edge type properties with `{<prop_name>: <prop_value>}` in a pattern. For example: `[e:follow{likeness:95}]`.
Match multiple edge types	`MATCH (v:player{name:"Tim Duncan"})-[e:follow \| :serve]->(v2) RETURN e`	The `\|` symbol can help matching multiple edge types. For example: `[e:follow\|:serve]`. The English colon (:) before the first edge type cannot be omitted, but the English colon before the subsequent edge type can be omitted, such as `[e:follow\|serve]`.
Match multiple edges	`MATCH (v:player{name:"Tim Duncan"})-[]->(v2)<-[e:serve]-(v3) RETURN v2, v3`	You can extend a pattern to match multiple edges in a path.
Match fixed-length paths	`MATCH p=(v:player{name:"Tim Duncan"})-[e:follow*2]->(v2) RETURN DISTINCT v2 AS Friends`	You can use the `:<edge_type>*<hop>` pattern to match a fixed-length path. `hop` must be a non-negative integer. The data type of `e` is the list.
Match variable-length paths	`MATCH p=(v:player{name:"Tim Duncan"})-[e:follow*1..3]->(v2) RETURN v2 AS Friends`	`minHop`: Optional. It represents the minimum length of the path. `minHop`: must be a non-negative integer. The default value is 1. `maxHop`: Required. It represents the maximum length of the path. `maxHop` must be a non-negative integer. It has no default value. The data type of `e` is the list.
Match variable-length paths with multiple edge types	`MATCH p=(v:player{name:"Tim Duncan"})-[e:follow \| serve*2]->(v2) RETURN DISTINCT v2`	You can specify multiple edge types in a fixed-length or variable-length pattern. In this case, `hop`, `minHop`, and `maxHop` take effect on all edge types. The data type of `e` is the list.
Retrieve vertex or edge information	`MATCH (v:player{name:"Tim Duncan"}) RETURN v` `MATCH (v:player{name:"Tim Duncan"})-[e]->(v2) RETURN e`	Use `RETURN {<vertex_name> \| <edge_name>}` to retrieve all the information of a vertex or an edge.
Retrieve VIDs	`MATCH (v:player{name:"Tim Duncan"}) RETURN id(v)`	Use the `id()` function to retrieve VIDs.
Retrieve tags	`MATCH (v:player{name:"Tim Duncan"}) RETURN labels(v)`	Use the `labels()` function to retrieve the list of tags on a vertex. To retrieve the nth element in the `labels(v)` list, use `labels(v)[n-1]`.
Retrieve a single property on a vertex or an edge	`MATCH (v:player{name:"Tim Duncan"}) RETURN v.age`	Use `RETURN {<vertex_name> \| <edge_name>}.<property>` to retrieve a single property. Use `AS` to specify an alias for a property.
Retrieve all properties on a vertex or an edge	`MATCH p=(v:player{name:"Tim Duncan"})-[]->(v2) RETURN properties(v2)`	Use the `properties()` function to retrieve all properties on a vertex or an edge.
Retrieve edge types	`MATCH p=(v:player{name:"Tim Duncan"})-[e]->() RETURN DISTINCT type(e)`	Use the `type()` function to retrieve the matched edge types.
Retrieve paths	`MATCH p=(v:player{name:"Tim Duncan"})-[*3]->() RETURN p`	Use `RETURN <path_name>` to retrieve all the information of the matched paths.
Retrieve vertices in a path	`MATCH p=(v:player{name:"Tim Duncan"})-[]->(v2) RETURN nodes(p)`	Use the `nodes()` function to retrieve all vertices in a path.
Retrieve edges in a path	`MATCH p=(v:player{name:"Tim Duncan"})-[]->(v2) RETURN relationships(p)`	Use the `relationships()` function to retrieve all edges in a path.
Retrieve path length	`MATCH p=(v:player{name:"Tim Duncan">})-[*..2]->(v2) RETURN p AS Paths, length(p) AS Length`	Use the `length()` function to retrieve the length of a path.

LOOKUP

LOOKUP ON {<vertex_tag> | <edge_type>} 
[WHERE <expression> [AND <expression> ...]] 
[YIELD <return_list> [AS <alias>]]

Pattern	Example	Description
Retrieve vertices	`LOOKUP ON player WHERE player.name == "Tony Parker" YIELD player.name AS name, player.age AS age`	The following example returns vertices whose `name` is `Tony Parker` and the tag is `player`.
Retrieve edges	`LOOKUP ON follow WHERE follow.degree == 90 YIELD follow.degree`	Returns edges whose `degree` is `90` and the edge type is `follow`.
List vertices with a tag	`LOOKUP ON player`	Shows how to retrieve the VID of all vertices tagged with `player`.
List edges with an edge types	`LOOKUP ON like`	Shows how to retrieve the source Vertex IDs, destination vertex IDs, and ranks of all edges of the `like` edge type.
Count the numbers of vertices or edges	`LOOKUP ON player \| YIELD COUNT(*) AS Player_Number`	Shows how to count the number of vertices tagged with `player`.
Count the numbers of edges	`LOOKUP ON like \| YIELD COUNT(*) AS Like_Number`	Shows how to count the number of edges of the `like` edge type.

GO

GO [[<M> TO] <N> STEPS ] FROM <vertex_list>
OVER <edge_type_list> [{REVERSELY | BIDIRECT}]
[ WHERE <conditions> ]
[YIELD [DISTINCT] <return_list>]
[| GROUP BY {col_name | expr | position} YIELD <col_name>]
[| ORDER BY <expression> [{ASC | DESC}]]
[| LIMIT [<offset_value>,] <number_rows>]

Example	Description
`GO FROM "player102" OVER serve`	Returns the teams that player 102 serves.
`GO 2 STEPS FROM "player102" OVER follow`	Returns the friends of player 102 with 2 hops.
`GO FROM "player100", "player102" OVER serve WHERE serve.start_year > 1995 YIELD DISTINCT properties($$).name AS team_name, properties(edge).start_year AS start_year, properties($^).name AS player_name`	Adds a filter for the traversal.
`GO FROM "player100" OVER follow, serve YIELD properties(edge).degree, properties(edge).start_year`	The following example traverses along with multiple edge types. If there is no value for a property, the output is `UNKNOWN_PROP`.
`GO FROM "player100" OVER follow REVERSELY YIELD src(edge) AS destination`	The following example returns the neighbor vertices in the incoming direction of player 100.
`GO FROM "player100" OVER follow REVERSELY YIELD src(edge) AS id \| GO FROM $-.id OVER serve WHERE $^.player.age > 20 YIELD properties($^).name AS FriendOf, properties($$).name AS Team`	The following example retrieves the friends of player 100 and the teams that they serve.
`GO FROM "player102" OVER follow YIELD dst(edge) AS both`	The following example returns all the neighbor vertices of player 102.
`GO 2 STEPS FROM "player100" OVER follow YIELD src(edge) AS src, dst(edge) AS dst, properties($$).age AS age \| GROUP BY $-.dst YIELD $-.dst AS dst, collect_set($-.src) AS src, collect($-.age) AS age`	The following example the outputs according to age.

FETCH

FETCH PROP ON {<tag_name>[, tag_name ...] | *} 
<vid> [, vid ...] 
[YIELD <return_list> [AS <alias>]]

Example	Description
`FETCH PROP ON player "player100"`	Specify a tag in the `FETCH` statement to fetch the vertex properties by that tag.
`FETCH PROP ON player "player100" YIELD player.name AS name`	Use a `YIELD` clause to specify the properties to be returned.
`FETCH PROP ON player "player101", "player102", "player103"`	Specify multiple VIDs (vertex IDs) to fetch properties of multiple vertices. Separate the VIDs with commas.
`FETCH PROP ON player, t1 "player100", "player103"`	Specify multiple tags in the `FETCH` statement to fetch the vertex properties by the tags. Separate the tags with commas.
`FETCH PROP ON * "player100", "player106", "team200"`	Set an asterisk symbol `*` to fetch properties by all tags in the current graph space.
`FETCH PROP ON serve "player102" -> "player106" YIELD dst(edge)`	Syntax: `FETCH PROP ON <edge_type> <src_vid> -> <dst_vid>[@<rank>] [, <src_vid> -> <dst_vid> ...] [YIELD <output>]`
`FETCH PROP ON serve "player100" -> "team204"`	The following statement fetches all the properties of the `serve` edge that connects vertex `"player100"` and vertex `"team204"`.
`FETCH PROP ON serve "player100" -> "team204" YIELD serve.start_year`	Use a `YIELD` clause to fetch specific properties of an edge.
`FETCH PROP ON serve "player100" -> "team204", "player133" -> "team202"`	Specify multiple edge patterns (`<src_vid> -> <dst_vid>[@<rank>]`) to fetch properties of multiple edges. Separate the edge patterns with commas.
`FETCH PROP ON serve "player100" -> "team204"@1`	To fetch on an edge whose rank is not 0, set its rank in the FETCH statement.
`GO FROM "player101" OVER follow YIELD follow._src AS s, follow._dst AS d \| FETCH PROP ON follow $-.s -> $-.d YIELD follow.degree`	The following statement returns the `degree` values of the `follow` edges that start from vertex `"player101"`.
`$var = GO FROM "player101" OVER follow YIELD follow._src AS s, follow._dst AS d; FETCH PROP ON follow $var.s -> $var.d YIELD follow.degree`	You can use user-defined variables to construct similar queries.

UNWIND

UNWIND <list> AS <alias> <RETURN clause>

Example	Description
`UNWIND [1,2,3] AS n RETURN n`	The following example splits the list `[1,2,3]` into three rows.
`WITH [1,1,2,2,3,3] AS n UNWIND n AS r WITH DISTINCT r AS r ORDER BY r RETURN collect(r)`	1. Splits the list `[1,1,2,2,3,3]` into rows. 2. Removes duplicated rows. 3. Sorts the rows. 4. Transforms the rows to a list.
`MATCH p=(v:player{name:"Tim Duncan"})--(v2) WITH nodes(p) AS n UNWIND n AS r WITH DISTINCT r AS r RETURN collect(r)`	1. Outputs the vertices on the matched path into a list. 2. Splits the list into rows. 3. Removes duplicated rows. 4. Transforms the rows to a list.

SHOW

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.

Clauses and options¶

Clause	Syntax	Example	Description
GROUP BY	`GROUP BY <var> YIELD <var>, <aggregation_function(var)>`	`GO FROM "player100" OVER follow BIDIRECT YIELD $$.player.name as Name \| GROUP BY $-.Name YIELD $-.Name as Player, count(*) AS Name_Count`	Finds all the vertices connected directly to vertex `"player100"`, groups the result set by player names, and counts how many times the name shows up in the result set.
LIMIT	`YIELD <var> [\| LIMIT [<offset_value>,] <number_rows>]`	`O FROM "player100" OVER follow REVERSELY YIELD $$.player.name AS Friend, $$.player.age AS Age \| ORDER BY $-.Age, $-.Friend \| LIMIT 1, 3`	Returns the 3 rows of data starting from the second row of the sorted output.
SKIP	`RETURN <var> [SKIP <offset>] [LIMIT <number_rows>]`	`MATCH (v:player{name:"Tim Duncan"}) --> (v2) RETURN v2.name AS Name, v2.age AS Age ORDER BY Age DESC SKIP 1`	`SKIP` can be used alone to set the offset and return the data after the specified position.
ORDER BY	`<YIELD clause> ORDER BY <expression> [ASC \| DESC] [, <expression> [ASC \| DESC] ...]`	`FETCH PROP ON player "player100", "player101", "player102", "player103" YIELD player.age AS age, player.name AS name \| ORDER BY $-.age ASC, $-.name DESC`	The `ORDER BY` clause specifies the order of the rows in the output.
RETURN	`RETURN {<vertex_name>\|<edge_name>\|<vertex_name>.<property>\|<edge_name>.<property>\|...}`	`MATCH (v:player) RETURN v.name, v.age LIMIT 3`	Returns the first three rows with values of the vertex properties `name` and `age`.
TTL	`CREATE TAG <tag_name>(<property_name_1> <property_value_1>, <property_name_2> <property_value_2>, ...) ttl_duration= <value_int>, ttl_col = <property_name>`	`CREATE TAG t2(a int, b int, c string) ttl_duration= 100, ttl_col = "a"`	Create a tag and set the TTL options.
WHERE	`WHERE {<vertex\|edge_alias>.<property_name> {>\|==\|<\|...} <value>...}`	`MATCH (v:player) WHERE v.name == "Tim Duncan" XOR (v.age < 30 AND v.name == "Yao Ming") OR NOT (v.name == "Yao Ming" OR v.name == "Tim Duncan") RETURN v.name, v.age`	The `WHERE` clause filters the output by conditions. The `WHERE` clause usually works in Native nGQL `GO` and `LOOKUP` statements, and OpenCypher `MATCH` and `WITH` statements.
YIELD	`YIELD [DISTINCT] <col> [AS <alias>] [, <col> [AS <alias>] ...] [WHERE <conditions>];`	`GO FROM "player100" OVER follow YIELD dst(edge) AS ID \| FETCH PROP ON player $-.ID YIELD player.age AS Age \| YIELD AVG($-.Age) as Avg_age, count(*)as Num_friends`	Finds the players that "player100" follows and calculates their average age.
WITH	`MATCH $expressions WITH {nodes()\|labels()\|...}`	`MATCH p=(v:player{name:"Tim Duncan"})--() WITH nodes(p) AS n UNWIND n AS n1 RETURN DISTINCT n1`	The `WITH` clause can retrieve the output from a query part, process it, and pass it to the next query part as the input.

Space statements¶

Statement	Syntax	Example	Description
CREATE SPACE	`CREATE SPACE [IF NOT EXISTS] <graph_space_name> ( [partition_num = <partition_number>,] [replica_factor = <replica_number>,] vid_type = {FIXED_STRING(<N>)\| INT[64]} ) [COMMENT = '<comment>']`	`CREATE SPACE my_space_1 (vid_type=FIXED_STRING(30))`	Creates a graph space with
CREATE SPACE	`CREATE SPACE <new_graph_space_name> AS <old_graph_space_name>`	`CREATE SPACE my_space_4 as my_space_3`	Clone a graph space.
USE	`USE <graph_space_name>`	`USE space1`	Specifies a graph space as the current working graph space for subsequent queries.
SHOW SPACES	`SHOW SPACES`	`SHOW SPACES`	Lists all the graph spaces in the NebulaGraph examples.
DESCRIBE SPACE	`DESC[RIBE] SPACE <graph_space_name>`	`DESCRIBE SPACE basketballplayer`	Returns the information about the specified graph space.息。
DROP SPACE	`DROP SPACE [IF EXISTS] <graph_space_name>`	`DROP SPACE basketballplayer`	Deletes everything in the specified graph space.

TAG statements¶

Statement	Syntax	Example	Description
CREATE TAG	`CREATE TAG [IF NOT EXISTS] <tag_name> ( <prop_name> <data_type> [NULL \| NOT NULL] [DEFAULT <default_value>] [COMMENT '<comment>'] [{, <prop_name> <data_type> [NULL \| NOT NULL] [DEFAULT <default_value>] [COMMENT '<comment>']} ...] ) [TTL_DURATION = <ttl_duration>] [TTL_COL = <prop_name>] [COMMENT = '<comment>']`	`CREATE TAG woman(name string, age int, married bool, salary double, create_time timestamp) TTL_DURATION = 100, TTL_COL = "create_time"`	Creates a tag with the given name in a graph space.
DROP TAG	`DROP TAG [IF EXISTS] <tag_name>`	`CREATE TAG test(p1 string, p2 int)`	Drops a tag with the given name in the current working graph space.
ALTER TAG	`ALTER TAG <tag_name> <alter_definition> [, alter_definition] ...] [ttl_definition [, ttl_definition] ... ] [COMMENT = '<comment>']`	`ALTER TAG t1 ADD (p3 int, p4 string)`	Alters the structure of a tag with the given name in a graph space. You can add or drop properties, and change the data type of an existing property. You can also set a TTL（Time-To-Live）on a property, or change its TTL duration.
SHOW TAGS	`SHOW TAGS`	`SHOW TAGS`	Shows the name of all tags in the current graph space.
DESCRIBE TAG	`DESC[RIBE] TAG <tag_name>`	`DESCRIBE TAG player`	Returns the information about a tag with the given name in a graph space, such as field names, data type, and so on.
DELETE TAG	`DELETE TAG <tag_name_list> FROM <VID>`	`DELETE TAG test1 FROM "test"`	Deletes a tag with the given name on a specified vertex.

Edge type statements¶

Statement	Syntax	Example	Description
CREATE EDGE	`CREATE EDGE [IF NOT EXISTS] <edge_type_name> ( <prop_name> <data_type> [NULL \| NOT NULL] [DEFAULT <default_value>] [COMMENT '<comment>'] [{, <prop_name> <data_type> [NULL \| NOT NULL] [DEFAULT <default_value>] [COMMENT '<comment>']} ...] ) [TTL_DURATION = <ttl_duration>] [TTL_COL = <prop_name>] [COMMENT = '<comment>']`	`CREATE EDGE e1(p1 string, p2 int, p3 timestamp) TTL_DURATION = 100, TTL_COL = "p2"`	Creates an edge type with the given name in a graph space.type。
DROP EDGE	`DROP EDGE [IF EXISTS] <edge_type_name>`	`DROP EDGE e1`	Drops an edge type with the given name in a graph space.
ALTER EDGE	`ALTER EDGE <edge_type_name> <alter_definition> [, alter_definition] ...] [ttl_definition [, ttl_definition] ... ] [COMMENT = '<comment>']`	`ALTER EDGE e1 ADD (p3 int, p4 string)`	Alters the structure of an edge type with the given name in a graph space.
SHOW EDGES	`SHOW EDGES`	`SHOW EDGES`	Shows all edge types in the current graph space.
DESCRIBE EDGE	`DESC[RIBE] EDGE <edge_type_name>`	`DESCRIBE EDGE follow`	Returns the information about an edge type with the given name in a graph space, such as field names, data type, and so on.

Vertex statements¶

Statement	Syntax	Example	Description
INSERT VERTEX	`INSERT VERTEX [IF NOT EXISTS] <tag_name> (<prop_name_list>) [, <tag_name> (<prop_name_list>), ...] {VALUES \| VALUE} VID: (<prop_value_list>[, <prop_value_list>])`	`INSERT VERTEX t2 (name, age) VALUES "13":("n3", 12), "14":("n4", 8)`	Inserts one or more vertices into a graph space in NebulaGraph.
DELETE VERTEX	`DELETE VERTEX <vid> [, <vid> ...]`	`DELETE VERTEX "team1"`	Deletes vertices and the related incoming and outgoing edges of the vertices.
UPDATE VERTEX	`UPDATE VERTEX ON <tag_name> <vid> SET <update_prop> [WHEN <condition>] [YIELD <output>]`	`UPDATE VERTEX ON player "player101" SET age = age + 2`	Updates properties on tags of a vertex.
UPSERT VERTEX	`UPSERT VERTEX ON <tag> <vid> SET <update_prop> [WHEN <condition>] [YIELD <output>]`	`UPSERT VERTEX ON player "player667" SET age = 31`	The `UPSERT` statement is a combination of `UPDATE` and `INSERT`. You can use `UPSERT VERTEX` to update the properties of a vertex if it exists or insert a new vertex if it does not exist.

Edge statements¶

Statement	Syntax	Example	Description
INSERT EDGE	`INSERT EDGE [IF NOT EXISTS] <edge_type> ( <prop_name_list> ) {VALUES \| VALUE} <src_vid> -> <dst_vid>[@<rank>] : ( <prop_value_list> ) [, <src_vid> -> <dst_vid>[@<rank>] : ( <prop_value_list> ), ...]`	`INSERT EDGE e2 (name, age) VALUES "11"->"13":("n1", 1)`	Inserts an edge or multiple edges into a graph space from a source vertex (given by src_vid) to a destination vertex (given by dst_vid) with a specific rank in NebulaGraph.
DELETE EDGE	`DELETE EDGE <edge_type> <src_vid> -> <dst_vid>[@<rank>] [, <src_vid> -> <dst_vid>[@<rank>] ...]`	`DELETE EDGE serve "player100" -> "team204"@0`	Deletes one edge or multiple edges at a time.
UPDATE EDGE	`UPDATE EDGE ON <edge_type> <src_vid> -> <dst_vid> [@<rank>] SET <update_prop> [WHEN <condition>] [YIELD <output>]`	`UPDATE EDGE ON serve "player100" -> "team204"@0 SET start_year = start_year + 1`	Updates properties on an edge.
UPSERT EDGE	`UPSERT EDGE ON <edge_type> <src_vid> -> <dst_vid> [@rank] SET <update_prop> [WHEN <condition>] [YIELD <properties>]`	`UPSERT EDGE on serve "player666" -> "team200"@0 SET end_year = 2021`	The `UPSERT` statement is a combination of `UPDATE` and `INSERT`. You can use `UPSERT EDGE` to update the properties of an edge if it exists or insert a new edge if it does not exist.

Index¶

Native index

You can use native indexes together with LOOKUP and MATCH statements.

Statement	Syntax	Example	Description
CREATE INDEX	`CREATE {TAG \| EDGE} INDEX [IF NOT EXISTS] <index_name> ON {<tag_name> \| <edge_name>} ([<prop_name_list>]) [COMMENT = '<comment>']`	`CREATE TAG INDEX player_index on player()`	Add native indexes for the existing tags, edge types, or properties.
SHOW CREATE INDEX	`SHOW CREATE {TAG \| EDGE} INDEX <index_name>`	`show create tag index index_2`	Shows the statement used when creating a tag or an edge type. It contains detailed information about the index, such as its associated properties.
SHOW INDEXES	`SHOW {TAG \| EDGE} INDEXES`	`SHOW TAG INDEXES`	Shows the defined tag or edge type indexes names in the current graph space.
DESCRIBE INDEX	`DESCRIBE {TAG \| EDGE} INDEX <index_name>`	`DESCRIBE TAG INDEX player_index_0`	Gets the information about the index with a given name, including the property name (Field) and the property type (Type) of the index.
REBUILD INDEX	`REBUILD {TAG \| EDGE} INDEX [<index_name_list>]`	`REBUILD TAG INDEX single_person_index`	Rebuilds the created tag or edge type index. If data is updated or inserted before the creation of the index, you must rebuild the indexes manually to make sure that the indexes contain the previously added data.
SHOW INDEX STATUS	`SHOW {TAG \| EDGE} INDEX STATUS`	`SHOW TAG INDEX STATUS`	Returns the name of the created tag or edge type index and its status.
DROP INDEX	`DROP {TAG \| EDGE} INDEX [IF EXISTS] <index_name>`	`DROP TAG INDEX player_index_0`	Removes an existing index from the current graph space.

Full-tex index

Syntax	Example	Description
`SIGN IN TEXT SERVICE [(<elastic_ip:port> [,<username>, <password>]), (<elastic_ip:port>), ...]`	`SIGN IN TEXT SERVICE (127.0.0.1:9200)`	The full-text indexes is implemented based on Elasticsearch. After deploying an Elasticsearch cluster, you can use the `SIGN IN` statement to log in to the Elasticsearch client.
`SHOW TEXT SEARCH CLIENTS`	`SHOW TEXT SEARCH CLIENTS`	Shows text search clients.
`SIGN OUT TEXT SERVICE`	`SIGN OUT TEXT SERVICE`	Signs out to the text search clients.
`CREATE FULLTEXT {TAG \| EDGE} INDEX <index_name> ON {<tag_name> \| <edge_name>} ([<prop_name_list>])`	`CREATE FULLTEXT TAG INDEX nebula_index_1 ON player(name)`	Creates full-text indexes.
`SHOW FULLTEXT INDEXES`	`SHOW FULLTEXT INDEXES`	Show full-text indexes.
`REBUILD FULLTEXT INDEX`	`REBUILD FULLTEXT INDEX`	Rebuild full-text indexes.
`DROP FULLTEXT INDEX <index_name>`	`DROP FULLTEXT INDEX nebula_index_1`	Drop full-text indexes.
`LOOKUP ON {<tag> \| <edge_type>} WHERE <expression> [YIELD <return_list>]`	`LOOKUP ON player WHERE FUZZY(player.name, "Tim Dunncan", AUTO, OR) YIELD player.name`	Use query options.

Subgraph and path statements¶

Type	Syntax	Example	Description
GET SUBGRAPH	`GET SUBGRAPH [WITH PROP] [<step_count> STEPS] FROM {<vid>, <vid>...} [{IN \| OUT \| BOTH} <edge_type>, <edge_type>...] [YIELD [VERTICES AS <vertex_alias>] [,EDGES AS <edge_alias>]]`	`GET SUBGRAPH 1 STEPS FROM "player100" YIELD VERTICES AS nodes, EDGES AS relationships`	Retrieves information of vertices and edges reachable from the source vertices of the specified edge types and returns information of the subgraph.
FIND PATH	`FIND { SHORTEST \| ALL \| NOLOOP } PATH [WITH PROP] FROM <vertex_id_list> TO <vertex_id_list><br/>OVER <edge_type_list> [REVERSELY \| BIDIRECT] [<WHERE clause>] [UPTO <N> STEPS] [\| ORDER BY $-.path] [\| LIMIT <M>]`	`FIND SHORTEST PATH FROM "player102" TO "team204" OVER *`	Finds the paths between the selected source vertices and destination vertices. A returned path is like `(<vertex_id>)-[:<edge_type_name>@<rank>]->(<vertex_id)`.

Query tuning statements¶

Type	Syntax	Example	Description
EXPLAIN	`EXPLAIN [format="row" \| "dot"] <your_nGQL_statement>`	`EXPLAIN format="row" SHOW TAGS` `EXPLAIN format="dot" SHOW TAGS`	Helps output the execution plan of an nGQL statement without executing the statement.
PROFILE	`PROFILE [format="row" \| "dot"] <your_nGQL_statement>`	`PROFILE format="row" SHOW TAGS` `EXPLAIN format="dot" SHOW TAGS`	Executes the statement, then outputs the execution plan as well as the execution profile.

Operation and maintenance statements¶

BALANCE

Syntax	Description
`BALANCE DATA`	Starts a task to balance the distribution of storage partitions in a NebulaGraph cluster or a Group. It returns the task ID (`balance_id`).
`BALANCE DATA <balance_id>`	Shows the status of the `BALANCE DATA` task.
`BALANCE DATA STOP`	Stops the `BALANCE DATA` task.
`BALANCE DATA REMOVE <host_list>`	Scales in the NebulaGraph cluster and detaches specific storage hosts.
`BALANCE LEADER`	Balances the distribution of storage raft leaders in a NebulaGraph cluster or a Group.

Job statements

Syntax	Description
`SUBMIT JOB COMPACT`	Triggers the long-term RocksDB `compact` operation.
`SUBMIT JOB FLUSH`	Writes the RocksDB memfile in the memory to the hard disk.
`SUBMIT JOB STATS`	Starts a job that makes the statistics of the current graph space. Once this job succeeds, you can use the `SHOW STATS` statement to list the statistics.
`SHOW JOB <job_id>`	Shows the information about a specific job and all its tasks in the current graph space. The Meta Service parses a `SUBMIT JOB` request into multiple tasks and assigns them to the nebula-storaged processes.
`SHOW JOBS`	Lists all the unexpired jobs in the current graph space.
`STOP JOB`	Stops jobs that are not finished in the current graph space.
`RECOVER JOB`	Re-executes the failed jobs in the current graph space and returns the number of recovered jobs.

Kill queries

Syntax	Example	Description
`KILL QUERY (session=<session_id>, plan=<plan_id>)`	`KILL QUERY(SESSION=1625553545984255,PLAN=163)`	Terminates the query being executed, and is often used to terminate slow queries.

Last update: March 13, 2023