14.21 Vector Functions — MySQL 9.2

14.21 Функции векторов

MySQL 9.2 поддерживает SQL-функции для работы со значениями VECTOR. Эти функции описаны в этом разделе.

Таблица 14.31 Функции векторов

Таблица 14.31 Функции векторов
Имя	Описание
`DISTANCE()`	Вычисляет расстояние между двумя векторами по указанному методу
`STRING_TO_VECTOR()`	Получает двоичное значение столбца VECTOR, представленное соответствующей строкой
`VECTOR_DIM()`	Получает длину вектора (то есть количество элементов, которое он содержит)
`VECTOR_TO_STRING()`	Получает строковое представление столбца VECTOR, заданного его двоичным значением как строка

DISTANCE(vector, vector, string)

Вычисляет расстояние между двумя векторами по указанному методу вычисления. Принимает следующие аргументы:
- Столбец типа данных VECTOR.
- Входной запрос типа данных VECTOR.
- Строка, определяющая метрику расстояния. Поддерживаемые значения — COSINE, DOT и EUCLIDEAN. Поскольку аргумент является строкой, он должен быть заключен в кавычки.
VECTOR_DISTANCE — синоним этой функции.

Примеры:
```
mysql> SELECT DISTANCE(STRING_TO_VECTOR("[1.01231, 2.0123123, 3.0123123, 4.01231231]"), STRING_TO_VECTOR("[1, 2, 3, 4]"), "COSINE");
+-----------------------------------------------------------------------------------------------------------------------+
| DISTANCE(STRING_TO_VECTOR("[1.01231, 2.0123123, 3.0123123, 4.01231231]"), STRING_TO_VECTOR("[1, 2, 3, 4]"), "COSINE") |
+-----------------------------------------------------------------------------------------------------------------------+
|                                                                                              0.0000016689300537109375 |
+-----------------------------------------------------------------------------------------------------------------------+
```
Примечание

DISTANCE() доступна только для пользователей HeatWave MySQL на OCI; она не включена в коммерческие или сообщественные дистрибутивы MySQL.
STRING_TO_VECTOR(string)

Преобразует строковое представление вектора в двоичное. Ожидаемый формат строки состоит из списка одного или нескольких разделенных запятыми значений с плавающей точкой, заключенных в квадратные скобки ([ ]). Значения могут быть выражены с использованием десятичной или научной записи. Поскольку аргумент является строкой, он должен быть заключен в кавычки.

TO_VECTOR() — синоним этой функции.

Примеры:
```
mysql> SELECT STRING_TO_VECTOR("[1.05, -17.8, 32]");
+---------------------------------------+
| STRING_TO_VECTOR("[1.05, -17.8, 32]") |
+---------------------------------------+
| 0x6666863F66668EC100000042            |
+---------------------------------------+
1 row in set (0.00 sec)

mysql> SELECT TO_VECTOR("[1.05, -17.8, 32, 123.456]");
+-----------------------------------------+
| TO_VECTOR("[1.05, -17.8, 32, 123.456]") |
+-----------------------------------------+
| 0x6666863F66668EC10000004279E9F642      |
+-----------------------------------------+
1 row in set (0.00 sec)
```
VECTOR_TO_STRING() — обратная функция:
```
mysql> SELECT VECTOR_TO_STRING(STRING_TO_VECTOR("[1.05, -17.8, 32]"));
+---------------------------------------------------------+
| VECTOR_TO_STRING(STRING_TO_VECTOR("[1.05, -17.8, 32]")) |
+---------------------------------------------------------+
| [1.05000e+00,-1.78000e+01,3.20000e+01]                  |
+---------------------------------------------------------+
1 row in set (0.00 sec)
```
Ранее эта функция отклоняла значения, содержащие дополнительные пробелы, кроме необязательного одиночного пробела после запятых. В MySQL 9.1 и более поздних версиях все символы пробела в таких значениях — после чисел, перед или после квадратных скобок или любой комбинации из них — обрезаются перед использованием.

VECTOR_DIM(vector)

Для заданного значения столбца VECTOR эта функция возвращает количество элементов, содержащихся в векторе.

Пример:

mysql> SELECT VECTOR_DIM(0x0040004000800080);
+--------------------------------+
| VECTOR_DIM(0x0040004000800080) |
+--------------------------------+
|                              2 |
+--------------------------------+
1 row in set (0.00 sec)

mysql> SELECT VECTOR_DIM(TO_VECTOR('[2, 3, 5]') );
+-------------------------------------+
| VECTOR_DIM(TO_VECTOR('[2, 3, 5]') ) |
+-------------------------------------+
|                                   3 |
+-------------------------------------+
1 row in set (0.00 sec)

Аргумент этой функции, который невозможно разобрать как значение вектора, вызывает ошибку.

VECTOR_TO_STRING(vector)

Для заданного двоичного представления значения столбца VECTOR эта функция возвращает его строковое представление, которое имеет тот же формат, что и аргумент функции STRING_TO_VECTOR().

FROM_VECTOR() принимается как синоним для этой функции.

Примеры:
```
mysql> SELECT VECTOR_TO_STRING(0x00000040000040400000A0400000E040);
+------------------------------------------------------+
| VECTOR_TO_STRING(0x00000040000040400000A0400000E040) |
+------------------------------------------------------+
| [2.00000e+00,3.00000e+00,5.00000e+00,7.00000e+00]    |
+------------------------------------------------------+
1 row in set (0.00 sec)

mysql> SELECT FROM_VECTOR(0x00000040000040400000A040);
+-----------------------------------------+
| FROM_VECTOR(0x00000040000040400000A040) |
+-----------------------------------------+
| [2.00000e+00,3.00000e+00,5.00000e+00]   |
+-----------------------------------------+
1 row in set (0.00 sec)
```
Аргумент этой функции, который невозможно разобрать как значение вектора, вызывает ошибку.

Максимальный размер выходных данных этой функции составляет 262128 (16 * 16383) байт.