Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/vector/
Documentation version: v5.3.2

# Vector functions

The following reference covers vector arithmetic and vector functions supported by GQL, with examples.

[]()[]()

## Arithmetic operations for vectors

Arithmetic operations for vectors include addition and subtraction between vectors, as well as addition, subtraction, multiplication, and division between a vector and a number. When performing operations between vectors, ensure that the dimensions of the vectors are the same. For more information, see [Supported arithmetic operations](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/vector-type/#supported_arithmetic_operations).

### Examples

#### Add a vector to another vector

````
LET x = VECTOR<3, FLOAT>([10.1, 20.2, 30.3]), y = VECTOR<3, FLOAT>([2.2, 3.3, 4.4]) RETURN x + y AS z

````

Return:

````
+------------------+
| z                |
+------------------+
| [12.3,23.5,34.7] |
+------------------+

````

#### Subtract a vector from another vector

````
LET x = VECTOR<3, FLOAT>([10.1, 20.2, 30.3]), y = VECTOR<3, FLOAT>([2.0, 3.0, 4.0]) RETURN x - y AS z

````

Return:

````
+-----------------+
| z               |
+-----------------+
| [8.1,17.2,26.3] |
+-----------------+

````

#### Add a number to each element of a vector

````
LET x = VECTOR<3, FLOAT>([1.1, 2.2, 3.3]) RETURN x + 1 AS x

````

Return:

````
+---------------+
| x             |
+---------------+
| [2.1,3.2,4.3] |
+---------------+

````

#### Subtract a number from each element of a vector

````
LET x = VECTOR<3, FLOAT>([10.1, 2.2, 3.3]) RETURN x - 1 AS x

````

Return:

````
+---------------+
| x             |
+---------------+
| [9.1,1.2,2.3] |
+---------------+

````

#### Multiply each element of a vector by a number

````
LET x = VECTOR<3, FLOAT>([1.1, 2.2, 3.3]) RETURN x * 2 AS x

````

Return:

````
+---------------+
| x             |
+---------------+
| [2.2,4.4,6.6] |
+---------------+

````

#### Divide each element of a vector by a number

````
LET x = VECTOR<3, FLOAT>([1.1, 2.2, 3.3]) RETURN x / 2 AS x

````

Return:

````
+-----------------+
| x               |
+-----------------+
| [0.55,1.1,1.65] |
+-----------------+

````

## euclidean()

Returns the Euclidean distance between two vectors. The Euclidean distance measures the straight-line distance between two vectors in a multi-dimensional space.

Null behavior: default

### Function signature

````
euclidean(v1: VECTOR, v2: VECTOR) -> FLOAT

````

or

````
vector_distance(v1: VECTOR, v2: VECTOR [EUCLIDEAN]) -> FLOAT

````

The number of dimensions in vectors `v1` and `v2` must be the same.

### Examples

Example 1:

````
RETURN euclidean(VECTOR<3,FLOAT>([1,2,3]), VECTOR<3,FLOAT>([4,5,6])) AS euclidean_distance

````

or

````
RETURN vector_distance(VECTOR<3,FLOAT>([1,2,3]), VECTOR<3,FLOAT>([4,5,6]) EUCLIDEAN) AS euclidean_distance

````

Return:

````
+--------------------+
| euclidean_distance |
+--------------------+
| 5.196152           |
+--------------------+

````

Example 2:

````
RETURN euclidean(VECTOR<3,FLOAT>([1,2,3]), null) AS euclidean_distance

````

Return:

````
+--------------------+
| euclidean_distance |
+--------------------+
| null               |
+--------------------+

````

## inner_product()

Returns the inner product of two vectors.

The inner product, also known as the dot product, calculates the sum of the products of the corresponding coordinates in two vectors. The dot product is positive if the angle between the vectors is less than 90 degrees, negative if the angle between the vectors is greater than 90 degrees, and zero if the vectors are orthogonal.

Null behavior: default

### Function signature

````
inner_product(v1: VECTOR, v2: VECTOR) -> FLOAT

````

or

````
vector_distance(v1: VECTOR, v2: VECTOR DOT) -> FLOAT

````

The number of dimensions in vectors `v1` and `v2` must be the same.

### Examples

Example 1:

````
RETURN inner_product(VECTOR<3,FLOAT>([1,2,3]), VECTOR<3,FLOAT>([4,5,6])) AS ip

````

or

````
RETURN vector_distance(VECTOR<3,FLOAT>([1,2,3]), VECTOR<3,FLOAT>([4,5,6]) DOT) AS ip

````

Return:

````
+------+
| ip   |
+------+
| 32.0 |
+------+

````

Example 2:

````
RETURN inner_product(VECTOR<3,FLOAT>([1,2,3]), null) AS ip

````

Return:

````
+------+
| ip   |
+------+
| null |
+------+

````

## cosine()

Returns the cosine similarity between two vectors.

The cosine similarity is computed by taking the [inner product](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/vector/#inner_product) of two vectors and dividing it by the product of their magnitudes.

For input vectors with non-zero magnitudes, the cosine similarity value range is `[-1, 1]`. 

Null behavior: default

### Function signature

````
cosine(v1: VECTOR, v2: VECTOR) -> FLOAT

````

or

````
vector_distance(v1: VECTOR, v2: VECTOR COSINE) -> FLOAT

````

The number of dimensions in vectors `v1` and `v2` must be the same.

### Examples

Example 1:

````
RETURN cosine(VECTOR<3,FLOAT>([1,2,3]), VECTOR<3,FLOAT>([4,5,6])) AS cos

````

or

````
RETURN vector_distance(VECTOR<3,FLOAT>([1,2,3]), VECTOR<3,FLOAT>([4,5,6]) COSINE) AS cos

````

Return:

````
+-----------+
| cos       |
+-----------+
| 0.9746318 |
+-----------+

````

Example 2:

````
RETURN cosine(VECTOR<3,FLOAT>([1,2,3]), null) AS cos

````

Return:

````
+------+
| cos  |
+------+
| null |
+------+

````

## abs()

Returns a vector where each element is the absolute value of the corresponding element in the given vector. 

This function also supports numeric data types. For details, see the [Math function `abs()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/math/#abs).

Null behavior: default

### Function signature

````
abs(num: VECTOR) -> VECTOR

````

### Examples

````
LET x = VECTOR<3, FLOAT>([1.1, -2.2, 3.3]) RETURN abs(x) AS x

````

Return:

````
+------------------+
| x                |
+------------------+
| [1.1,2.2,3.3]    |
+------------------+

````

## abs2()

Returns a vector where each element is the square of the corresponding element in the given vector.

Null behavior: default

### Function signature

````
abs2(num: VECTOR) -> VECTOR

````

### Examples

````
LET x = VECTOR<3, FLOAT>([1.1, -2.2, 3.3]) RETURN abs2(x) AS x

````

Return:

````
+-----------------------+
| x                     |
+-----------------------+
| [1.21,4.84,10.889999] |
+-----------------------+

````

## sqrt()

Returns a vector where each element is the square root of the corresponding element in the given vector.

This function also supports numeric data types. For details, see the [Math function `sqrt()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/math/#sqrt).

Null behavior: default

### Function signature

````
sqrt(num: VECTOR) -> VECTOR

````

### Examples

````
LET x = VECTOR<3, FLOAT>([1.21,4.84,10.89]) RETURN sqrt(x) AS x

````

Return:

````
+---------------+
| x             |
+---------------+
| [1.1,2.2,3.3] |
+---------------+

````

## ln()

Returns a vector where each element is the natural logarithm (base `e`) of the corresponding element in the given vector.

The base `e` is an irrational and transcendental number, approximately equal to 2.71828.

This function also supports numeric data types. For details, see the [Math function `ln()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/math/#ln).

Null behavior: default

### Function signature

````
ln(v: VECTOR) ->  VECTOR

````

### Examples

````
LET x = VECTOR<3, FLOAT>([64.0, 256.0, 16.0]) RETURN ln(x) AS x 

````

Return:

````
+--------------------------------+
| x                              |
+--------------------------------+
| [4.158883,5.5451775,2.7725887] |
+--------------------------------+

````

## log10()

Returns a vector where each element is the base-10 logarithm of the corresponding element in the given vector.

This function also supports numeric data types. For details, see the [Math function `log10()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/math/#log10).

Null behavior: default

### Function signature

````
log10(v: VECTOR) ->  VECTOR

````

### Examples

````
LET x = VECTOR<3, FLOAT>([64.0, 256.0, 16.0]) RETURN log10(x) AS x

````

Return:

````
+---------------------------+
| x                         |
+---------------------------+
| [1.80618,2.40824,1.20412] |
+---------------------------+

````

## exp()

Returns a vector where each element is the exponential value with base `e` raised to the power of the corresponding element in the given vector.

The base `e` is an irrational and transcendental number, approximately equal to 2.71828.

This function also supports numeric data types. For details, see the [Math function `exp()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/math/#exp).

Null behavior: default

### Function signature

````
exp(v: VECTOR) ->  VECTOR 

````

### Examples

````
LET x = VECTOR<3, FLOAT>([1, 2, 3]) RETURN exp(x) AS x

````

Return:

````
+--------------------------------+
| x                              |
+--------------------------------+
| [2.7182817,7.389056,20.085537] |
+--------------------------------+

````

## normalize()

Returns the normalized vector, scaled to unit length (magnitude of 1). The normalized vector maintains the same direction as the original one.

Null behavior: default

### Function signature

````
normalize(v: VECTOR) ->  VECTOR 

````

### Examples

````
LET x = VECTOR<3, FLOAT>([1, 2, 3]) RETURN normalize(x) AS x

````

Return:

````
+----------------------------------+
| x                                |
+----------------------------------+
| [0.26726124,0.5345225,0.8017837] |
+----------------------------------+

````

## accum()

Returns the sum of all elements within a vector. 

Null behavior: default

### Function signature

````
accum(v: VECTOR) ->  FLOAT 

````

### Examples

````
LET x = VECTOR<3, FLOAT>([10.1, 20.2, 30.3]) RETURN accum(x) AS z

````

Return:

````
+------+
| z    |
+------+
| 60.6 |
+------+

````

## mean()

Returns the average value of all elements within a vector.

Null behavior: default

### Function signature

````
mean(v: VECTOR) ->  FLOAT 

````

### Examples

````
LET x = VECTOR<3, FLOAT>([1.1, 2.2, 3.3]) RETURN mean(x) AS z

````

Return:

````
+-----+
| z   |
+-----+
| 2.2 |
+-----+

````

## prod()

Returns the product of all elements within a vector. The product is calculated by multiplying all the elements together.

Null behavior: default

### Function signature

````
prod(v: VECTOR) ->  FLOAT 

````

### Examples

````
LET x = VECTOR<3, FLOAT>([1.1, 2.2, 3.3]) RETURN prod(x) AS z

````

Return:

````
+-------+
| z     |
+-------+
| 7.986 |
+-------+

````

## norm()

Returns the Euclidean norm of a vector. The Euclidean norm measures the length of this vector in a multi-dimensional space.

Null behavior: default

### Function signature

````
norm(v: VECTOR) ->  FLOAT 

````

### Examples

````
LET x = VECTOR<3, FLOAT>([1.1, 2.2, 3.3]) RETURN norm(x) AS z

````

Return:

````
+----------+
| z        |
+----------+
| 4.115823 |
+----------+

````

## squared_norm()

Returns the squared Euclidean norm of a vector. The squared norm is the sum of the squares of each element in this vector, which is equivalent to the square of the [Euclidean norm](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/vector/#norm).

Null behavior: default

### Function signature

````
squared_norm(v: VECTOR) ->  FLOAT 

````

### Examples

````
LET x = VECTOR<3, FLOAT>([1.1, 2.2, 3.3]) RETURN squared_norm(x) AS z

````

Return:

````
+-----------+
| z         |
+-----------+
| 16.939999 |
+-----------+

````