Skip to content
Developer Edition runs on one host and does not require a product license file. Need multi-host deployment or performance testing at scale? Explore Enterprise Edition

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.

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 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().

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().

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().

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().

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().

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.

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