Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

functions and expressions #562

Merged
merged 1 commit into from
Jul 19, 2021
Merged

functions and expressions #562

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 51 additions & 31 deletions docs-2.0/3.ngql-guide/6.functions-and-expressions/1.math.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)`.<br>If you set only one argument, it is parsed as `max` and `min` is `0` by default.<br>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)`.<br>If you set only one argument, it is parsed as `max` and `min` is `0` by default.<br>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.<br>If the number is 0, the system returns 0.<br>If the number is negative, the system returns -1.<br>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)

<!--collect_set() | Puts all the collected values to a set. | -->
```
69 changes: 35 additions & 34 deletions docs-2.0/3.ngql-guide/6.functions-and-expressions/10.collect.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |
+---+
Expand All @@ -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"] |
+-----+--------------------------------------------------------------------------+
...
```
```
40 changes: 20 additions & 20 deletions docs-2.0/3.ngql-guide/6.functions-and-expressions/11.reduce.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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(<accumulator> = <initial>, <variable> IN <list> | <expression>)
```

- 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;
Expand All @@ -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 |
+------+------+-----+
Expand All @@ -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 |
+---------------------+-----+--------+
Expand Down
9 changes: 3 additions & 6 deletions docs-2.0/3.ngql-guide/6.functions-and-expressions/12.hash.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,19 @@
# 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)
```

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

Expand Down
Loading