Sign inTry Free

VECTOR_ADD

On this page

The VECTOR_ADD function adds the two vector arguments and returns a vector which is the result of that addition.

Syntax

VECTOR_ADD(vector_expression, vector_expression)

Arguments

  • vector_expression: An expression that evaluates to a vector. Vectors can be stored in SingleStore using the native VECTOR type (Vector Type) or the BLOB type (BLOB Types). SingleStore recommends using the VECTOR type when possible.

  • JSON strings are allowed as vector_expressions when the other argument is of type VECTOR.

Return Type

If one of the two arguments is of type VECTOR, the function will return a VECTOR of the same type as that argument.

If both arguments are BLOBs, then the return type will be by default a BLOB that contains a vector encoded as 32-bit floating point numbers (F32). Alternatively if a suffix is used, the return type will be a BLOB that contains a vector encoded using the type of the suffix.

See Using Suffixes for Other Element Types with BLOBs for information on using suffixes with vectors encoded as BLOBs.

Remarks

  • If both arguments are of type VECTOR, those arguments must have the same element types and the same number of elements.

  • If one argument is a VECTOR, the other argument (which may be a JSON string or a BLOB) will be converted to the type of the VECTOR argument.

    • It will cause an error if the JSON string has a different number of elements than the VECTOR argument.

    • It will cause an error if the length of the BLOB is such that the BLOB cannot be converted to the type of the VECTOR. Note that there is no type checking in this conversion, so ensure that the BLOBs were encoded with the same type as the VECTOR argument.

  • If both arguments are BLOBs, both arguments will be treated as vectors with 32-bit floating-point numbers. It will cause an error if the arguments are different lengths.

  • The default format for vector element storage and processing is a 32-bit floating-point number (F32). When the inputs are BLOBs, the function assumes the inputs are vectors encoded as 32-bit floating-point numbers.

  • When a suffix is used, the function will interpret the inputs as vectors encoded as specified by the suffix. See Using Suffixes for Other Element Types with BLOBs for more information.

Output Format for Examples

Vectors may be output in JSON or binary format. Use JSON format for examples and for output readability. For production, use the default binary for efficiency.

To get JSON output which will match the examples, use the following command to output vectors in JSON.

SET vector_type_project_format = JSON;

Use the following command to set the output format back to binary.

SET vector_type_project_format = BINARY;

Using VECTOR_ADD with the VECTOR Data Type

The examples below show three different uses of VECTOR_ADD with varying types of VECTOR arguments.

Example 1 - Vector Type

The example below adds two vectors stored as VECTORs.

First create a table of vectors of length 4 using the VECTOR data type and insert data into that table.

CREATE TABLE vectors (id int, vec VECTOR(4) not null);


INSERT INTO vectors VALUES (1, '[0.45, 0.55, 0.495, 0.5]');
INSERT INTO vectors VALUES (2, '[0.1, 0.8, 0.2, 0.555]');
INSERT INTO vectors VALUES (3, '[-0.5, -0.03, -0.1, 0.86]');
INSERT INTO vectors VALUES (4, '[0.5, 0.3, 0.807, 0.1]');

Note

The default element type for Vector Type is 32-bit floating point (F32). The Vector Type supports other element types, including integer types, as described in the Vector Type documentation.

The following SQL adds the vector '[0.1,0.1,0.1,0.1]' to the vectors in the vectors table.

Click the Playground icon to the right of the SQL listing to try this query. Also, try experimenting and writing your own query.

SET vector_type_project_format = JSON;  /* to make vector output readable */


SET @qv = '[0.1,0.1,0.1,0.1]':>VECTOR(4);


/* run both SET commands before this query */
SELECT id, VECTOR_ADD(vec, @qv)
FROM vectors
ORDER BY id;
+------+---------------------------------------------------+
| id   | VECTOR_ADD(vec, @qv)                              |
+------+---------------------------------------------------+
|    1 | [0.550000012,0.650000036,0.595000029,0.600000024] |
|    2 | [0.200000003,0.900000036,0.300000012,0.655000031] |
|    3 | [-0.400000006,0.0700000003,0,0.960000038]         |
|    4 | [0.600000024,0.400000006,0.907000005,0.200000003] |
+------+---------------------------------------------------+

Example 2 - Vector Type and BLOB Type

Inputs to VECTOR_ADD can also be BLOBs. If one input is of type VECTOR and the other of type BLOB, VECTOR_ADD will automatically convert the BLOB to the type of the VECTOR argument.

The SQL below shows an example where VECTOR_ADD is used with a vector that is encoded as a BLOB using JSON_ARRAY_PACK. VECTOR_ADD will automatically convert this BLOB to the type of, vec, the left-hand argument.

SET vector_type_project_format = JSON;  /* to make vector output readable */


SET @qv = JSON_ARRAY_PACK('[0.1,0.1,0.1,0.1]'); 


/* run both SET commands before this query */
SELECT id, VECTOR_ADD(vec, @qv)
FROM vectors
ORDER BY id;
+------+---------------------------------------------------+
| id   | VECTOR_ADD(vec, @qv)                              |
+------+---------------------------------------------------+
|    1 | [0.550000012,0.650000036,0.595000029,0.600000024] |
|    2 | [0.200000003,0.900000036,0.300000012,0.655000031] |
|    3 | [-0.400000006,0.0700000003,0,0.960000038]         |
|    4 | [0.600000024,0.400000006,0.907000005,0.200000003] |
+------+---------------------------------------------------+

Important

It is important to ensure that the vector encoded as a BLOB has the same element type and length as the vector(s) stored as VECTORs. In this case, the default 32-bit floating point element type was used for both the BLOB encoding and the VECTOR type.

Example 3 - JSON String Argument and I16 Element Type

This example shows how to use VECTOR_ADD with a VECTOR with an elementType of 16-bit integer (I16) and how to use a JSON string as input to VECTOR_ADD.

First create a table with a VECTOR attribute of length 3 and element type I16 and insert data into that table.

CREATE TABLE vectors_i16(id INT, vec VECTOR(3, I16));


INSERT INTO vectors_i16 VALUES(1, '[1, 2, 3]');
INSERT INTO vectors_i16 VALUES(2, '[4, 5, 6]');
INSERT INTO vectors_i16 VALUES(3, '[1, 4, 8]');

The following SQL adds the vector '[1,2,3]' to each of the vectors in the vectors_i16 table.

Then use the JSON_ARRAY_PACK built-in function to easily insert properly formatted vectors.

In this example, the JSON string '[1,2,3]' is used as input to the VECTOR_ADD function. VECTOR_ADD will detect that the second argument, vec, is of type VECTOR of length 3 and with element type 16-bit integer and will automatically convert the JSON string to a VECTOR of that type.

SET vector_type_project_format = JSON;  /* to make vector output readable */


SELECT id, vec, VECTOR_ADD(vec, '[1,2,3]')
FROM vectors_i16
ORDER BY id;
+------+---------+----------------------------+
| id   | vec     | VECTOR_ADD(vec, '[1,2,3]') |
+------+---------+----------------------------+
|    1 | [1,2,3] | [2,4,6]                    |
|    2 | [4,5,6] | [5,7,9]                    |
|    3 | [1,4,8] | [2,6,11]                   |
+------+---------+----------------------------+

Using VECTOR_ADD with Vectors as BLOBs

The following examples and descriptions show the use of VECTOR_ADD with arguments that are both vectors stored as BLOBs.

Example 1 - BLOB Arguments

Create a table with a column of type BLOB to store the vectors. The second column in this table, with column name vec and type BLOB, will store the vectors. This example demonstrates storing vector data using BLOBs, hence the column of type BLOB named vec.

CREATE TABLE vectors_b (id int, vec BLOB not null);


INSERT INTO vectors_b VALUES (1, JSON_ARRAY_PACK('[0.1, 0.8, 0.2, 0.555]')); 
INSERT INTO vectors_b VALUES (2, JSON_ARRAY_PACK('[0.45, 0.55, 0.495, 0.5]'));

The following query adds the vector '[0.1,0.1,0.1,0.1]' to the vectors in the vectors_b table and uses JSON_ARRAY_UNPACK to see the results in JSON format.

SET @qv = JSON_ARRAY_PACK('[0.1,0.1,0.1,0.1]');


SELECT id, JSON_ARRAY_UNPACK(VECTOR_ADD(vec, @qv)) AS vector_add
FROM vectors_b
ORDER BY id;
+------+---------------------------------------------------+
| id   | vector_add                                        |
+------+---------------------------------------------------+
|    1 | [0.200000003,0.900000036,0.300000012,0.655000031] |
|    2 | [0.550000012,0.650000036,0.595000029,0.600000024] |
+------+---------------------------------------------------+

JSON_ARRAY_UNPACK was used here to output the vectors in readable format because VECTOR_ADD returns a BLOB when its inputs are BLOBs.

The following query adds the vector '[0.1,0.1,0.1,0.1]' to the vectors in the vectors_b table and uses HEX to view the results in hexadecimal format.

SET @qv = JSON_ARRAY_PACK('[0.1,0.1,0.1,0.1]');


SELECT id, HEX(VECTOR_ADD(vec, @qv)) AS vector_add
FROM vectors_b
ORDER BY id;
+------+----------------------------------+
| id   | vector_add                       |
+------+----------------------------------+
|    1 | CDCC4C3E6766663F9A99993E15AE273F |
|    2 | CDCC0C3F6766263FEC51183F9A99193F |
+------+----------------------------------+

Using Suffixes for Other Element Types with BLOBs

The default element type for vector storage and processing is 32-bit floating point (F32). However, other element types are supported.

You can specify the datatype of the vector elements to be used in the operation by adding a suffix to the function. All operations are done using the specified datatype. Omitting the suffix from the function is equivalent to suffixing it with _F32.

When using a suffix, the return type will be the type of the suffix.

Note

The functions with suffixes do not work with the VECTOR type.

The following table lists the suffixes and their data type.

Suffix

Data Type

_I8

8-bit signed integer

_I16

16-bit signed integer

_I32

32-bit signed integer

_I64

64-bit signed integer

_F32

32-bit floating-point number (IEEE standard format)

_F64

64-bit floating-point number (IEEE standard format)

Example 2 - BLOBs with 16-bit Integers

Below is an example of using JSON_ARRAY_PACK and VECTOR_ADD with 16-bit signed integers.

First create a table of vectors stored as 16-bit integers. Note the use of the _I16 suffix on JSON_ARRAY_PACK.

CREATE TABLE vectors_b_i (id int, vec BLOB not null);


INSERT INTO vectors_b_i VALUES (1, JSON_ARRAY_PACK_I16('[1, 3, 2, 5]')); 
INSERT INTO vectors_b_i VALUES(2, JSON_ARRAY_PACK_I16('[23, 4, 1, 8]'));

The following query adds the vector '[2,2,2,2]' to the vectors in the vectors_b_i.

SET @qv = JSON_ARRAY_PACK_I16('[2, 2, 2, 2]');


SELECT JSON_ARRAY_UNPACK_I16(VECTOR_ADD_I16(@qv, vec)) AS vector_add
FROM vectors_b_i;
+--------------+
| vector_add   |
+--------------+
| [3,5,4,7]    |
| [25,6,3,10]  |
+--------------+

The result is an array of 16-bit integers as indicated by the _I16 suffix.

Note

Be sure that the suffixes you use to pack the vector data match the suffixes you use to unpack the data and the suffixes you use on functions to process that data.

Formatting Binary Vector Data for BLOBs

When using the BLOB type for vector operations, vector data can be formatted using JSON_ARRAY_PACK. If your vector data is already in a packed binary format, you can load that data into the BLOBs. The data must be encoded as a BLOB containing packed numbers in little-endian byte order. Vectors stored as BLOBs can be of any length; however, the input blob length must be divisible by the size of the packed vector elements (1, 2, 4 , or 8 bytes, depending on the vector element).

Related Topics

Last modified: May 30, 2024

Was this article helpful?

On this page

Was this article helpful?