From f3e2449c0f00e5da2fd82a21251133615956e4b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9C=B1=E6=99=93=E9=9D=92?= <86282370+izhuxiaoqing@users.noreply.github.com> Date: Fri, 16 Jul 2021 11:42:13 +0800 Subject: [PATCH] functions and expressions --- .../6.functions-and-expressions/1.math.md | 82 ++++++++++------- .../6.functions-and-expressions/10.collect.md | 69 +++++++------- .../6.functions-and-expressions/11.reduce.md | 40 ++++---- .../6.functions-and-expressions/12.hash.md | 9 +- .../6.functions-and-expressions/2.string.md | 51 ++++++----- .../3.date-and-time.md | 36 ++++---- .../6.functions-and-expressions/4.schema.md | 13 ++- .../5.case-expressions.md | 91 ++++++++++--------- .../6.functions-and-expressions/6.list.md | 30 +++--- .../6.functions-and-expressions/7.count.md | 78 ++++++++-------- .../8.predicate.md | 52 +++++++---- .../9.user-defined-functions.md | 2 +- 12 files changed, 305 insertions(+), 248 deletions(-) diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/1.math.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/1.math.md index c00f4ec03f4..236f3d48de6 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/1.math.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/1.math.md @@ -1,50 +1,70 @@ # Built-in math functions +## Function descriptions + Nebula Graph supports the following built-in math functions: Function| Description | ---- | ----| -double abs(double x) | Returns absolute value of the argument. | -double floor(double x) | Returns the largest integer value smaller than or equal to the argument. (Rounds down)| +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 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) | Returns 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` raised by the `y`th power. | -double exp(double x) | Returns the value of e raised to the x power. | -double exp2(double x) | Returns 2 raised to the argument. | -double log(double x) | Returns natural logarithm of the argument. | +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 sine of the argument. | -double asin(double x) | Returns inverse sine of the argument.| -double cos(double x) | Returns cosine of the argument. | -double acos(double x) | Returns inverse cosine of the argument. | -double tan(double x) | Returns tangent of the argument. | -double atan(double x) | Returns inverse tangent 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 default to `0`. 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 default to `0`. If you set no argument, the system returns a random signed 64-bit integer.| -collect() | Puts all the collected values to 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 exclusive OR (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` (inclusive) to `end` (inclusive) in the specified steps. `step` is optional and default to 1.| -int sign(double x) | Returns the signum of the given number: 0 if the number is 0, -1 for any negative number, and 1 for any positive number.| +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. | +double radians() | Converts degrees to radians. `radians(180)` returns `3.141592653589793`. | !!! note - If the argument is set to `NULL`, the output is undefined. + If the argument is `NULL`, the output is undefined. + +## Example + +```ngql +# The following clause supports aggregate functions. +nebula> GO FROM "Tim Duncan" OVER like YIELD like._dst AS dst, $$.player.age AS age \ + | GROUP BY $-.dst \ + YIELD \ + $-.dst AS dst, \ + toInteger((sum($-.age)/count($-.age)))+avg(distinct $-.age+1)+1 AS statistics; ++-----------------+------------+ +| dst | statistics | ++-----------------+------------+ +| "Tony Parker" | 74.0 | ++-----------------+------------+ +| "Manu Ginobili" | 84.0 | ++-----------------+------------+ +Got 2 rows (time spent 4739/5064 us) - +``` diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/10.collect.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/10.collect.md index 6e408bcaeb6..5c17b6513e3 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/10.collect.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/10.collect.md @@ -1,16 +1,14 @@ # collect() -`collect()` returns a list containing the values returned by an expression. Using this function -aggregates data by amalgamating multiple records or values into a single list. +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. -`collect()` is an aggregation function. Like `GROUP BY` in SQL. +The aggregate function `collect()` works like `GROUP BY` in SQL. ## Examples -This example works like `GROUP BY`. - ```ngql -nebula> UNWIND [1, 2, 1] AS a RETURN a; +nebula> UNWIND [1, 2, 1] AS a \ + RETURN a; +---+ | a | +---+ @@ -20,62 +18,65 @@ nebula> UNWIND [1, 2, 1] AS a RETURN a; +---+ | 1 | +---+ -nebula> UNWIND [1, 2, 1] AS a RETURN collect(a); + +nebula> UNWIND [1, 2, 1] AS a \ + RETURN collect(a); +------------+ -| COLLECT(a) | +| collect(a) | +------------+ | [1, 2, 1] | +------------+ -nebula> UNWIND [1, 2, 1] AS a RETURN a, collect(a), size(collect(a)) + +nebula> UNWIND [1, 2, 1] AS a \ + RETURN a, collect(a), size(collect(a)); +---+------------+------------------+ -| a | COLLECT(a) | size(COLLECT(a)) | +| a | collect(a) | size(COLLECT(a)) | +---+------------+------------------+ | 2 | [2] | 1 | +---+------------+------------------+ | 1 | [1, 1] | 2 | +---+------------+------------------+ -``` -You can sort reversely, limit output rows to 3, and collect the output into a list. - -```ngql +# The following examples sort the results in descending order, limit output rows to 3, and collect the output into a list.œ nebula> UNWIND ["c", "b", "a", "d" ] AS p \ - WITH p AS q \ - ORDER BY q DESC LIMIT 3 \ - RETURN collect(q); + WITH p AS q \ + ORDER BY q DESC LIMIT 3 \ + RETURN collect(q); +-----------------+ -| COLLECT(q) | +| collect(q) | +-----------------+ | ["d", "c", "b"] | +-----------------+ + nebula> WITH [1, 1, 2, 2] AS coll \ - UNWIND coll AS x \ - WITH DISTINCT x \ - RETURN collect(x) AS ss + UNWIND coll AS x \ + WITH DISTINCT x \ + RETURN collect(x) AS ss; +--------+ | ss | +--------+ | [1, 2] | +--------+ -``` -This example aggregates all players' names by their ages. - -```ngql -nebula> MATCH (n:player) RETURN collect(n.age); +nebula> MATCH (n:player) \ + RETURN collect(n.age); +---------------------------------------------------------------+ -| COLLECT(n.age) | -----------------------------------------------------------------+ -| [32, 32, 34, 29, 41, 40, 33, 25, 40, 37, ... | +| collect(n.age) | ----------------------------------------------------------------+ +| [32, 32, 34, 29, 41, 40, 33, 25, 40, 37, ... +... -nebula> MATCH (n:player) RETURN n.age AS age, collect(n.name); +# The following example aggregates all the players' names by their ages. +nebula> MATCH (n:player) \ + RETURN n.age AS age, collect(n.name); ++-----+--------------------------------------------------------------------------+ +| age | collect(n.name) | +-----+--------------------------------------------------------------------------+ -| 27 | ["Cory Joseph"] | +| 24 | ["Giannis Antetokounmpo"] | +-----+--------------------------------------------------------------------------+ -| 28 | ["Damian Lillard", "Paul George", "Ricky Rubio"] | +| 20 | ["Luka Doncic"] | +-----+--------------------------------------------------------------------------+ -| 29 | ["Dejounte Murray", "James Harden", "Klay Thompson", "Jonathon Simmons"] | +| 25 | ["Joel Embiid", "Kyle Anderson"] | +-----+--------------------------------------------------------------------------+ ... -``` +``` \ No newline at end of file diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/11.reduce.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/11.reduce.md index 1731edbaaa9..52f82fb4be8 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/11.reduce.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/11.reduce.md @@ -1,32 +1,32 @@ # reduce() function +This topic will describe the `reduce` function. + ## OpenCypher Compatibility -In openCypher, the function `reduce()` is not defined. nGQL implements `reduce()` function as the Cypher way. +In openCypher, the `reduce()` function is not defined. nGQL will implement the `reduce()` function in the Cypher way. ## Syntax -`reduce()` returns the value resulting from the application of an expression on each successive element in a list in conjunction with the result of the computation thus far. This function will iterate through each element `e` in the given list, run the expression on `e` — taking into account the current partial result — and store the new partial result in the accumulator. This function is analogous to the fold or reduce method in functional languages such as Lisp and Scala. +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. This function iterates each element `e` in the given list, runs the expression on `e`, accumulates the result with the initial value, and store the new result in the accumulator as the initial value of the next iteration. It works like the fold or reduce method in functional languages such as Lisp and Scala. ```ngql -reduce(accumulator = initial, variable IN list | expression) +reduce( = , IN | ) ``` -- Arguments: - -| Name | Description | +| Parameter | Description | | -- | -- | -| accumulator | A variable that will hold the result and the partial results as the list is iterated. | -| initial | An expression that runs once to give a starting value to the accumulator. | -| list | An expression that returns a list. | -| variable | The closure will have a variable introduced in its context. We decide here which variable to use. | -| expression | This expression will run once per value in the list, and produce the result value. | +| accumulator | A variable that will hold the accumulated results as the list is iterated. | +| initial | An expression that runs once to give an initial value to the `accumulator`. | +| variable | A variable in the list that will be applied to the expression successively. | +| list | A list or a list of expressions. | +| expression | This expression will be run on each element in the list once and store the result value in the `accumulator`. | -- Returns: +!!! note - The type of the value returned depends on the arguments provided, along with the semantics of expression. + The type of the value returned depends on the parameters provided, along with the semantics of the expression. -## Example +## Examples ```ngql nebula> RETURN reduce(totalNum = 10, n IN range(1, 3) | totalNum + n) AS r; @@ -42,13 +42,10 @@ nebula> RETURN reduce(totalNum = -4 * 5, n IN [1, 2] | totalNum + n * 2) AS r; +-----+ | -14 | +-----+ -``` -```ngql nebula> MATCH p = (n:player{name:"LeBron James"})<-[:follow]-(m) \ - RETURN nodes(p)[0].age AS src1, \ - nodes(p)[1].age AS dst2, \ - reduce(totalAge = 100, n IN nodes(p) | totalAge + n.age) AS sum + RETURN nodes(p)[0].age AS src1, nodes(p)[1].age AS dst2, \ + reduce(totalAge = 100, n IN nodes(p) | totalAge + n.age) AS sum; +------+------+-----+ | src1 | dst2 | sum | +------+------+-----+ @@ -65,7 +62,10 @@ nebula> MATCH p = (n:player{name:"LeBron James"})<-[:follow]-(m) \ | 34 | 37 | 171 | +------+------+-----+ -nebula> LOOKUP ON player WHERE player.name == "Tony Parker" | GO FROM $-.VertexID over follow WHERE follow.degree != reduce(totalNum = 5, n IN range(1, 3) | $$.player.age + totalNum + n) YIELD $$.player.name AS id, $$.player.age AS age, follow.degree AS degree +nebula> LOOKUP ON player WHERE player.name == "Tony Parker" \ + | GO FROM $-.VertexID over follow \ + WHERE follow.degree != reduce(totalNum = 5, n IN range(1, 3) | $$.player.age + totalNum + n) \ + YIELD $$.player.name AS id, $$.player.age AS age, follow.degree AS degree; +---------------------+-----+--------+ | id | age | degree | +---------------------+-----+--------+ diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/12.hash.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/12.hash.md index dfd6f372f26..9a84d140e4c 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/12.hash.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/12.hash.md @@ -1,14 +1,11 @@ -# Hash +# hash function 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 [`MurmurHahs2.h`](https://github.com/vesoft-inc/nebula-common/blob/master/src/common/base/MurmurHash2.h). -!!! note - Roughly, The chance of collision is about 1/10 in the case of 1 billion vertices. The number of edges is irrelevant to the collision possibility. - -For Java, call like follows. +For Java, the hash function operates as follows. ```Java MurmurHash2.hash64("to_be_hashed".getBytes(),"to_be_hashed".getBytes().length, 0xc70f6907) @@ -16,7 +13,7 @@ MurmurHash2.hash64("to_be_hashed".getBytes(),"to_be_hashed".getBytes().length, 0 ## Legacy version compatibility -In nGQL 1.0, when nGQL does not support string VIDs, a common practice is to hash the strings first and then use the values as VIDs. But in nGQL 2.0, both string VIDs and integer VIDs are supported, you don't have to use `hash()` to make VIDs. +In nGQL 1.0, when nGQL does not support string VIDs, a common practice is to hash the strings first and then use the values as VIDs. But in nGQL 2.0, both string VIDs and integer VIDs are supported, so there is no need to use `hash()` to set VIDs. ## Hash a number diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/2.string.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/2.string.md index 9116781ab05..e0640c9e9e2 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/2.string.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/2.string.md @@ -2,28 +2,32 @@ Nebula Graph supports the following built-in string functions: +!!! Note + + Like SQL, the position index of nGQL starts from `1`, while in C language it starts from `0`. + Function| Description | ---- | ----| -int strcasecmp(string a, string b) | Compares strings without case sensitivity, when a = b, Returns 0, when a > b Returnsed value is greater than 0, otherwise less than 0. | +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 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 given string in bytes. | +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 the substring in [1, count], if length a is less than count, Returns a. | -string right(string a, int count) | Returns the substring in [size - count + 1, size], if length a is less than count, Returns a. | -string lpad(string a, int size, string letters) | Left-pads a string with another string to a certain length.| -string rpad(string a, int size, string letters)| Reft-pads a string with another string to a certain length. | -string substr(string a, int pos, int count) | Returns a substring from a string, starting at the specified position `pos`, extract `count` characters. | -string substring(string a, int pos, int count) | The same as substr(). | -string reverse(string) | Returns the reverse of a string. -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 an integer value. | +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. | !!! note @@ -31,17 +35,22 @@ int hash() | Takes in any data type and encodes it into an integer value. | ## Explanations for the return of `substr()` and `substring()` -- `pos` uses a 0-based index. -- If `pos` is 0, the whole string `a` is returned. +- The position index starts from `0`. + +- If `pos` is 0, the whole string is returned. + - If `pos` is greater than the maximum string index, an empty string is returned. + - If `pos` is a negative number, `BAD_DATA` is returned. -- If `count` is omitted, the function returns the substring starting at the position given by `pos` and -extending to the end of string `a`. -- Using `NULL` as any of the argument of `substr()` causes [an issue](https://github.com/vesoft-inc/nebula-graph/issues/878). + +- If `count` is omitted, the function returns the substring starting at the position given by `pos` and extending to the end of the string. + - If `count` is 0, an empty string is returned. +- Using `NULL` as any of the argument of `substr()` will cause [an issue](https://github.com/vesoft-inc/nebula-graph/issues/878). + !!! note "OpenCypher compatibility" - In openCypher, if `a` is `null`, `null` is returned. - In openCypher, if `pos` is 0, the returned substring starts from the first character, and extend to `count` characters. - - In openCypher, if either `pos` or `count` is null or a negative integer, an error is raised. + - In openCypher, if either `pos` or `count` is `null` or a negative integer, an issue is raised. diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/3.date-and-time.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/3.date-and-time.md index 2ab6ee91d33..d503132aa36 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/3.date-and-time.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/3.date-and-time.md @@ -4,25 +4,27 @@ Nebula Graph supports the following built-in date and time functions: Function| Description | ---- | ----| -int now() | Return the current date and time of the system time zone. | -date date() | Return the current UTC date based on the current system. | -time time() | Return the current UTC calendar time of the current time zone. | -datetime datetime() | Return the current UTC datetime based on the current time. | +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. | -The date(), time(), and datetime() functions accept three kind of parameters, namely empty, string, and map. - -## Examples - -```ngql -> RETURN now(), date(), time(), datetime(); -+------------+------------+--------------+-------------------------+ -| now() | date() | time() | datetime() | -+------------+------------+--------------+-------------------------+ -| 1611907165 | 2021-01-29 | 07:59:22.000 | 2021-01-29T07:59:22.000 | -+------------+------------+--------------+-------------------------+ -``` +The `date()`, `time()`, and `datetime()` functions accept three kind of parameters, namely empty, string, and map. The `timestamp()` function accepts two kind of parameters, namely empty and string. ## OpenCypher compatibility * Time in openCypher is measured in milliseconds. -* Time in nGQL is measured in seconds. The milliseconds are displayed in `000`. \ No newline at end of file + +* Time in nGQL is measured in seconds. The milliseconds are displayed in `000`. + +## Examples + +```ngql +> RETURN now(), timestamp(), date(), time(), datetime(), timestamp(); ++------------+-------------+------------+-----------------+----------------------------+ +| now() | timestamp() | date() | time() | datetime() | ++------------+-------------+------------+-----------------+----------------------------+ +| 1625470028 | 1625470028 | 2021-07-05 | 07:27:07.944000 | 2021-07-05T07:27:07.944000 | ++------------+-------------+------------+-----------------+----------------------------+ +``` \ No newline at end of file diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/4.schema.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/4.schema.md index 22381560ff1..5f8cf1f0e12 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/4.schema.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/4.schema.md @@ -10,30 +10,33 @@ list labels(vertex) | Returns the tags of a vertex. map properties(vertex_or_edge) | Takes in a vertex or an edge and returns its properties. string type(edge) | Returns the edge type of an edge. vertex startNode(path) | Takes in an edge or a path and returns its source vertex ID. -string endNode(path) | Takes in an edge or a path and returns its destination vertex ID. +string endNode(path) | Takes in an edge or a path and returns its destination vertex ID. int rank(edge) | Returns the rank value of an edge. ## Examples ```ngql -nebula> MATCH (a:player) WHERE id(a) == "player100" RETURN tags(a), labels(a), properties(a) +nebula> MATCH (a:player) WHERE id(a) == "player100" \ + RETURN tags(a), labels(a), properties(a); +------------+------------+-------------------------------+ | tags(a) | labels(a) | properties(a) | +------------+------------+-------------------------------+ | ["player"] | ["player"] | {age: 42, name: "Tim Duncan"} | +------------+------------+-------------------------------+ -nebula> MATCH p = (a :player {name : "Tim Duncan"})-[r:serve]-(t) RETURN type(r), rank(r) +nebula> MATCH p = (a :player {name : "Tim Duncan"})-[r:serve]-(t) \ + RETURN type(r), rank(r); +---------+---------+ | type(r) | rank(r) | +---------+---------+ | "serve" | 0 | +---------+---------+ -nebula> MATCH p = (a :player {name : "Tim Duncan"})-[r:serve]-(t) RETURN startNode(p), endNode(p) +nebula> MATCH p = (a :player {name : "Tim Duncan"})-[r:serve]-(t) \ + RETURN startNode(p), endNode(p); +----------------------------------------------------+----------------------------------+ | startNode(p) | endNode(p) | +----------------------------------------------------+----------------------------------+ | ("player100" :player{age: 42, name: "Tim Duncan"}) | ("team204" :team{name: "Spurs"}) | +----------------------------------------------------+----------------------------------+ -``` +``` \ No newline at end of file diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/5.case-expressions.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/5.case-expressions.md index b8130822116..1cb222df372 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/5.case-expressions.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/5.case-expressions.md @@ -1,8 +1,8 @@ # CASE expressions -The `CASE` expression uses conditions to filter the result of an nGQL query statement. It is usually used in the `YIELD` or `RETURN` clause. nGQL provides two forms of `CASE` expressions just like openCypher: the simple form and the generic form. +The `CASE` expression uses conditions to filter the result of an nGQL query statement. It is usually used in the `YIELD` and `RETURN` clauses. nGQL provides two forms of `CASE` expressions just like openCypher: the simple form and the generic form. -The `CASE` expression goes through conditions and returns a result when the first condition is met. Then 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`. +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`. ## The simple form of CASE expressions @@ -18,25 +18,25 @@ END !!! caution - Always remember to end a `CASE` expression with `END`. + Always remember to end the `CASE` expression with an `END`. -|Parameters|Description| +|Parameter|Description| |-|-| -|`comparer`|A value or a valid expression that outputs a value. This value is used to compare with `value`.| -|`value`|It will be compared with `comparer`. If they match, then this condition is met.| -|`result`|It is returned by the `CASE` expression if `value` matches `comparer`.| -|`default`|It is returned by the `CASE` expression if no conditions are met.| +|`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.| ### Examples ```ngql nebula> RETURN \ - CASE 2+3 \ - WHEN 4 THEN 0 \ - WHEN 5 THEN 1 \ - ELSE -1 \ - END \ - AS result; + CASE 2+3 \ + WHEN 4 THEN 0 \ + WHEN 5 THEN 1 \ + ELSE -1 \ + END \ + AS result; +--------+ | result | +--------+ @@ -46,13 +46,13 @@ nebula> RETURN \ ```ngql nebula> GO FROM "player100" OVER follow \ - YIELD $$.player.name AS Name, \ - CASE $$.player.age > 35 \ - WHEN true THEN "Yes" \ - WHEN false THEN "No" \ - ELSE "Nah" \ - END \ - AS Age_above_35; + YIELD $$.player.name AS Name, \ + CASE $$.player.age > 35 \ + WHEN true THEN "Yes" \ + WHEN false THEN "No" \ + ELSE "Nah" \ + END \ + AS Age_above_35; +---------------------+--------------+ | Name | Age_above_35 | +---------------------+--------------+ @@ -74,21 +74,21 @@ WHEN THEN END ``` -|Parameters|Description| +|Parameter|Description| |-|-| -|`condition`|If `condition` is evaluated as true, `result` is returned by the `CASE` expression.| -|`result`|It is returned by the `CASE` expression if `condition` is evaluated as true.| -|`default`|It is returned by the `CASE` expression if no conditions are met.| +|`condition`|If the `condition` is evaluated as true, the `result` is returned by the `CASE` expression.| +|`result`|The `result` is returned by the `CASE` expression if the `condition` is evaluated as true.| +|`default`|The `default` is returned by the `CASE` expression if no conditions are met.| ### Examples ```ngql nebula> YIELD \ - CASE WHEN 4 > 5 THEN 0 \ - WHEN 3+4==7 THEN 1 \ - ELSE 2 \ - END \ - AS result; + CASE WHEN 4 > 5 THEN 0 \ + WHEN 3+4==7 THEN 1 \ + ELSE 2 \ + END \ + AS result; +--------+ | result | +--------+ @@ -98,12 +98,12 @@ nebula> YIELD \ ```ngql nebula> MATCH (v:player) WHERE v.age > 30 \ - RETURN v.name AS Name, \ - CASE \ - WHEN v.name STARTS WITH "T" THEN "Yes" \ - ELSE "No" \ - END \ - AS Starts_with_T; + RETURN v.name AS Name, \ + CASE \ + WHEN v.name STARTS WITH "T" THEN "Yes" \ + ELSE "No" \ + END \ + AS Starts_with_T; +---------------------+---------------+ | Name | Starts_with_T | +---------------------+---------------+ @@ -121,12 +121,12 @@ To avoid the misuse of the simple form and the generic form, it is important to ```ngql nebula> GO FROM "player100" OVER follow \ - YIELD $$.player.name AS Name, $$.player.age AS Age, \ - CASE $$.player.age \ - WHEN $$.player.age > 35 THEN "Yes" \ - ELSE "No" \ - END \ - AS Age_above_35; + YIELD $$.player.name AS Name, $$.player.age AS Age, \ + CASE $$.player.age \ + WHEN $$.player.age > 35 THEN "Yes" \ + ELSE "No" \ + END \ + AS Age_above_35; +---------------------+-----+--------------+ | Name | Age | Age_above_35 | +---------------------+-----+--------------+ @@ -136,11 +136,12 @@ nebula> GO FROM "player100" OVER follow \ +---------------------+-----+--------------+ ``` -The preceding `GO` query is intended to output "Yes" when the player age is above 35. However, in this example, when the player age is 36, the actual output is not as expected: It is "No" instead of "Yes". +The preceding `GO` query is intended to output `Yes` when the player's age is above 35. However, in this example, when the player's age is 36, the actual output is not as expected: It is `No` instead of `Yes`. This is because the query uses the `CASE` expression in the simple form, and a comparison between the values of `$$.player.age` and `$$.player.age > 35` is made. When the player age is 36: * The value of `$$.player.age` is `36`. It is an integer. -* `$$.player.age > 35` is evaluated to `true`. It is a boolean. -The values of `$$.player.age` and `$$.player.age > 35` do not match. This condition is not met and "No" is returned. +* `$$.player.age > 35` is evaluated to be `true`. It is a boolean. + +The values of `$$.player.age` and `$$.player.age > 35` do not match. Therefore, the condition is not met and `No` is returned. diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/6.list.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/6.list.md index 6c064f39a4f..41fc825dfb8 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/6.list.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/6.list.md @@ -1,14 +1,16 @@ # List functions +Nebula Graph supports the following list functions: + | Function| Description | | ---- | ----| -| keys(expr) | Returns a list containing the string representations for all the property names of a vertex, edge, or map. | -| labels(vertex) | Returns the tags of a vertex. | -| nodes(path) | Returns a list containing all the nodes in a path. | -| range(start, end [, step]) | A list of Integer elements. | -| relationships(path) | Returns a list containing all the relationships in a path. | -| reverse(list) | returns a list in which the order of all elements in the original list have been reversed. |\ -| tail(list) | returns all the elements, excluding the first one. | +| 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. | @@ -16,19 +18,22 @@ !!! note - If the parameter is `NULL`, the output is undefined. + If the argument is `NULL`, the output is undefined. ## Examples ```ngql -nebula> WITH [NULL, 4923, 'abc', 521, 487] AS ids RETURN reverse(ids), tail(ids), head(ids), last(ids), coalesce(ids) +nebula> WITH [NULL, 4923, 'abc', 521, 487] AS ids \ + RETURN reverse(ids), tail(ids), head(ids), last(ids), coalesce(ids); +-----------------------------------+-------------------------+-----------+-----------+---------------+ | reverse(ids) | tail(ids) | head(ids) | last(ids) | coalesce(ids) | +-----------------------------------+-------------------------+-----------+-----------+---------------+ | [487, 521, "abc", 4923, __NULL__] | [4923, "abc", 521, 487] | __NULL__ | 487 | 4923 | +-----------------------------------+-------------------------+-----------+-----------+---------------+ -nebula> MATCH (a:player)-[r]->() WHERE id(a) == "player100" RETURN labels(a), keys(r) +nebula> MATCH (a:player)-[r]->() \ + WHERE id(a) == "player100" \ + RETURN labels(a), keys(r); +------------+----------------------------+ | labels(a) | keys(r) | +------------+----------------------------+ @@ -39,7 +44,9 @@ nebula> MATCH (a:player)-[r]->() WHERE id(a) == "player100" RETURN labels(a), k | ["player"] | ["end_year", "start_year"] | +------------+----------------------------+ -nebula> MATCH p = (a:player)-[]->(b)-[]->(c:team) WHERE a.name == "Tim Duncan" AND c.name == "Spurs" RETURN nodes(p) +nebula> MATCH p = (a:player)-[]->(b)-[]->(c:team) \ + WHERE a.name == "Tim Duncan" AND c.name == "Spurs" \ + RETURN nodes(p); +-----------------------------------------------------------------------------------------------------------------------------------------------+ | nodes(p) | +-----------------------------------------------------------------------------------------------------------------------------------------------+ @@ -56,5 +63,4 @@ nebula> MATCH p = (a:player)-[]->(b)-[]->(c:team) WHERE a.name == "Tim Duncan" A +-----------------------------------------------------------------------------------------------------------------------------+ | [[:follow "player100"->"player125" @0 {degree: 95}], [:serve "player125"->"team204" @0 {end_year: 2018, start_year: 2002}]] | +-----------------------------------------------------------------------------------------------------------------------------+ - ``` diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/7.count.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/7.count.md index 12d591c4650..cac3302a87f 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/7.count.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/7.count.md @@ -1,8 +1,9 @@ -# The count() function +# count() function -The `count()` function calculates the number of the specified values or rows. +The `count()` function counts the number of the specified values or rows. - (Native nGQL) You can use `count()` and `GROUP BY` together to group and count the number of specific values. Use `YIELD` to return. + - (OpenCypher style) You can use `count()` and `RETURN`. `GROUP BY` is not necessary. ## Syntax @@ -12,25 +13,30 @@ count({expr | *}) ``` - count(*) returns the number of rows (including NULL). -- count(expr) return non-NULL values return by an expression. -- count() and size() are different. + +- count(expr) return the number of non-NULL values that meet the expression. + +- `count()` and `size()` are different. ### Examples ```ngql -nebula> WITH [NULL, 1, 1, 2, 2] As a UNWIND a AS b RETURN count(b), count(*), count(DISTINCT b) +nebula> WITH [NULL, 1, 1, 2, 2] As a UNWIND a AS b \ + RETURN count(b), count(*), count(DISTINCT b); +----------+----------+-------------------+ -| COUNT(b) | COUNT(*) | COUNT(distinct b) | +| count(b) | count(*) | count(distinct b) | +----------+----------+-------------------+ | 4 | 5 | 2 | +----------+----------+-------------------+ ``` ```ngql -nebula> GO FROM "player101" OVER follow BIDIRECT YIELD $$.player.name AS Name | \ - GROUP BY $-.Name YIELD $-.Name, count(*); +# The statement in the following example searches for the people whom `player101` follows and people who follow `player101`, i.e. a bidirectional query. +nebula> GO FROM "player101" OVER follow BIDIRECT \ + YIELD $$.player.name AS Name \ + | GROUP BY $-.Name YIELD $-.Name, count(*); +---------------------+----------+ -| $-.Name | COUNT(*) | +| $-.Name | count(*) | +---------------------+----------+ | "Dejounte Murray" | 1 | +---------------------+----------+ @@ -46,21 +52,21 @@ nebula> GO FROM "player101" OVER follow BIDIRECT YIELD $$.player.name AS Name | +---------------------+----------+ ``` -The statement in the preceding example searches for: - -* People whom `player101` follows. -* People who follow `player101`. +The preceding example retrieves two columns: -And retrieves two columns: +* `$-.Name`: the names of the people. -* `$-.Name`, the names of the people. -* `COUNT(*)`, how many times the names show up. +* `count(*)`: how many times the names show up. -Because there are no duplicate names in the `basketballplayer` dataset, the number `2` in the result shows that the person in that row and `player101` have followed each other. +Because there are no duplicate names in the `basketballplayer` dataset, the number `2` in the column `count(*)` shows that the person in that row and `player101` have followed each other. ```ngql -nebula> LOOKUP ON player YIELD player.age As playerage \| - GROUP BY $-.playerage YIELD $-.playerage as age, count(*) AS number | ORDER BY number DESC, age DESC +# a: The statement in the following example retrieves the age distribution of the players in the dataset. +nebula> LOOKUP ON player \ + YIELD player.age As playerage \ + | GROUP BY $-.playerage \ + YIELD $-.playerage as age, count(*) AS number \ + | ORDER BY number DESC, age DESC; +-----+--------+ | age | number | +-----+--------+ @@ -76,7 +82,10 @@ nebula> LOOKUP ON player YIELD player.age As playerage \| +-----+--------+ ... -nebula> MATCH (n:player) RETURN n.age as age, count(*) as number ORDER BY number DESC, age DESC +# b: The statement in the following example retrieves the age distribution of the players in the dataset. +nebula> MATCH (n:player) \ + RETURN n.age as age, count(*) as number \ + ORDER BY number DESC, age DESC; +-----+--------+ | age | number | +-----+--------+ @@ -90,35 +99,26 @@ nebula> MATCH (n:player) RETURN n.age as age, count(*) as number ORDER BY number +-----+--------+ | 38 | 3 | +-----+--------+ - - +... ``` -The two statements in the preceding examples retrieves the age distribution of the players in the dataset. - ```ngql -nebula> MATCH (v:player{name:"Tim Duncan"}) -- (v2) RETURN count(DISTINCT v2) +# The statement in the following example counts the number of edges that Tim Duncan relates. +nebula> MATCH (v:player{name:"Tim Duncan"}) -- (v2) \ + RETURN count(DISTINCT v2); +--------------------+ -| COUNT(distinct v2) | +| count(distinct v2) | +--------------------+ | 11 | +--------------------+ -nebula> MATCH (n:player {name : "Tim Duncan"})-[]->(friend:player)-[]->(fof:player) RETURN count(fof), count(DISTINCT fof) + +# The statement in the following example counts the number of edges that Tim Duncan relates and returns two columns (no DISTINCT and DISTINCT) in multi-hop queries. +nebula> MATCH (n:player {name : "Tim Duncan"})-[]->(friend:player)-[]->(fof:player) \ + RETURN count(fof), count(DISTINCT fof); +------------+---------------------+ -| COUNT(fof) | COUNT(distinct fof) | +| count(fof) | count(distinct fof) | +------------+---------------------+ | 4 | 3 | +------------+---------------------+ ``` - -## count(NULL) - -```ngql -nebula> RETURN count(NULL), size(NULL) -+-------------+------------+ -| COUNT(NULL) | size(NULL) | -+-------------+------------+ -| 0 | __NULL__ | -+-------------+------------+ -``` diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/8.predicate.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/8.predicate.md index 188ecd56796..d2f26b31bb5 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/8.predicate.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/8.predicate.md @@ -1,22 +1,24 @@ # Predicate functions -Predicate functions return true or false. They are most commonly used in `WHERE`. +Predicate functions return `true` or `false`. They are most commonly used in `WHERE` clauses. + +Nebula Graph supports the following predicate functions: | Functions | Description | |:----- | :------------------: | -| exists() | returns true if the specified property exists in the vertex, edge or map. | -| any() | returns true if the predicate holds for at least one element in the given list. | -| all() | returns true if the predicate holds for all elements in the given list. | -| none() | returns true if the predicate holds for no element in the given list. | -| single() | returns true if the predicate holds for exactly one of the elements in the given list. | +| 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`. | !!! note NULL is returned if the list is NULL or all of its elements are NULL. -## OpenCypher compatibility +!!! compatibility -In openCypher, only function `exists()` is defined and specified. The other functions are implement-dependent. + In openCypher, only function `exists()` is defined and specified. The other functions are implement-dependent. ## Syntax @@ -27,37 +29,41 @@ In openCypher, only function `exists()` is defined and specified. The other func ## Examples ```ngql -nebula> RETURN any(n IN [1, 2, 3, 4, 5, NULL] WHERE n > 2) AS r +nebula> RETURN any(n IN [1, 2, 3, 4, 5, NULL] \ + WHERE n > 2) AS r; +------+ | r | +------+ | true | +------+ -nebula> RETURN single(n IN range(1, 5) WHERE n == 3) AS r +nebula> RETURN single(n IN range(1, 5) \ + WHERE n == 3) AS r; +------+ | r | +------+ | true | +------+ -nebula> RETURN none(n IN range(1, 3) WHERE n == 0) AS r +nebula> RETURN none(n IN range(1, 3) \ + WHERE n == 0) AS r; +------+ | r | +------+ | true | +------+ -nebula> WITH [1, 2, 3, 4, 5, NULL] AS a RETURN any(n IN a WHERE n > 2) +nebula> WITH [1, 2, 3, 4, 5, NULL] AS a \ + RETURN any(n IN a WHERE n > 2); +-------------------------+ | any(n IN a WHERE (n>2)) | +-------------------------+ | true | +-------------------------+ -nebula> MATCH p = (n:player{name:"LeBron James"})<-[:follow]-(m) \ - RETURN nodes(p)[0].name AS n1, nodes(p)[1].name AS n2, \ - all(n IN nodes(p) WHERE n.name NOT STARTS WITH "D") AS b +nebula> MATCH p = (n:player{name:"LeBron James"})<-[:follow]-(m) \ + RETURN nodes(p)[0].name AS n1, nodes(p)[1].name AS n2, \ + all(n IN nodes(p) WHERE n.name NOT STARTS WITH "D") AS b; +----------------+-------------------+-------+ | n1 | n2 | b | +----------------+-------------------+-------+ @@ -75,18 +81,30 @@ nebula> MATCH p = (n:player{name:"LeBron James"})<-[:follow]-(m) \ +----------------+-------------------+-------+ nebula> MATCH p = (n:player{name:"LeBron James"})-[:follow]->(m) \ - RETURN single(n IN nodes(p) WHERE n.age > 40) AS b + RETURN single(n IN nodes(p) WHERE n.age > 40) AS b; +------+ | b | +------+ | true | +------+ -nebula> MATCH (n:player) RETURN exists(n.id), n IS NOT NULL +nebula> MATCH (n:player) \ + RETURN exists(n.id), n IS NOT NULL; +--------------+---------------+ | exists(n.id) | n IS NOT NULL | +--------------+---------------+ | false | true | +--------------+---------------+ ... + +nebula> MATCH (n:player) \ + WHERE exists(n['name']) RETURN n; ++-------------------------------------------------------------------------------------------------------------+ +| n | ++-------------------------------------------------------------------------------------------------------------+ +| ("Grant Hill" :player{age: 46, name: "Grant Hill"}) | ++-------------------------------------------------------------------------------------------------------------+ +| ("Marc Gasol" :player{age: 34, name: "Marc Gasol"}) | ++-------------------------------------------------------------------------------------------------------------+ +... ``` diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/9.user-defined-functions.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/9.user-defined-functions.md index 4f621e3558f..11491765412 100644 --- a/docs-2.0/3.ngql-guide/6.functions-and-expressions/9.user-defined-functions.md +++ b/docs-2.0/3.ngql-guide/6.functions-and-expressions/9.user-defined-functions.md @@ -2,4 +2,4 @@ ## OpenCypher compatibility -User-defined functions are not yet supported nor designed in Nebula Graph 2.x. +User-defined functions (UDF) and storage processes are not yet supported nor designed in Nebula Graph {{ nebula.release }}.