Для выполнения поиска KNN необходимо сначала настроить таблицу. Векторы с плавающей точкой и поиск KNN поддерживаются только в таблицах реального времени (не в обычных таблицах). Таблица должна содержать как минимум один атрибут float_vector, который служит вектором данных. Необходимо указать следующие свойства:

• knn_type: обязательный параметр; в настоящее время поддерживается только hnsw.

• knn_dims: обязательный параметр, указывающий размерность индексируемых векторов.

• hnsw_similarity: обязательный параметр, указывающий функцию расстояния, используемую индексом HNSW. Допустимые значения:

  • L2 - квадрат евклидова расстояния
  • IP - внутреннее произведение
  • COSINE - косинусное сходство

  Примечание: При использовании косинусного сходства (COSINE) векторы автоматически нормализуются при вставке. Это означает, что сохранённые значения векторов могут отличаться от исходных, так как они будут преобразованы в единичные векторы (векторы с математической длиной/модулем 1.0) для эффективного вычисления косинусного сходства. Такая нормализация сохраняет направление вектора при стандартизации его длины.

• hnsw_m: необязательный параметр, определяющий максимальное количество исходящих связей в графе. По умолчанию 16.

• hnsw_ef_construction: необязательный параметр, определяющий компромисс между временем построения и точностью.

Самый простой способ работать с векторными данными — использовать автоматические эмбеддинги. С этой функцией вы создаёте таблицу с параметрами MODEL_NAME и FROM, а затем просто вставляете текстовые данные — Manticore автоматически генерирует эмбеддинги для вас.

При создании таблицы для автоматических эмбеддингов укажите:

• MODEL_NAME: модель эмбеддинга для использования
• FROM: какие поля использовать для генерации эмбеддингов (пустое значение означает все текстовые/строковые поля)

Поддерживаемые модели эмбеддингов:

• Sentence Transformers: Любая подходящая модель на базе BERT из Hugging Face (например, sentence-transformers/all-MiniLM-L6-v2) — не требует API-ключа. Manticore загружает модель при создании таблицы.
• OpenAI: Модели эмбеддингов OpenAI, такие как openai/text-embedding-ada-002 — требует параметр API_KEY='<OPENAI_API_KEY>'
• Voyage: Модели эмбеддингов Voyage AI — требует параметр API_KEY='<VOYAGE_API_KEY>'
• Jina: Модели эмбеддингов Jina AI — требует параметр API_KEY='<JINA_API_KEY>'

Более подробная информация о настройке атрибута float_vector доступна здесь.

При использовании автоматических эмбеддингов не указывайте поле вектора в операторе INSERT. Эмбеддинги генерируются автоматически из текстовых полей, указанных в параметре FROM.

Поиск работает так же — укажите текст запроса, и Manticore сгенерирует эмбеддинги и найдёт похожие документы:

В качестве альтернативы вы можете вручную вставлять заранее вычисленные векторные данные, убедившись, что они соответствуют размерности, указанной при создании таблицы. Также можно вставить пустой вектор; это означает, что документ будет исключён из результатов поиска по векторам.

Важно: При использовании hnsw_similarity='cosine' векторы автоматически нормализуются при вставке до единичных векторов (векторов с математической длиной/модулем 1.0). Эта нормализация сохраняет направление вектора при стандартизации его длины, что необходимо для эффективных вычислений косинусного сходства. Это означает, что сохранённые значения будут отличаться от ваших исходных значений.

Теперь вы можете выполнять поиск KNN с помощью оператора knn в формате SQL или JSON. Оба интерфейса поддерживают одинаковые основные параметры, обеспечивая единообразный опыт независимо от выбранного формата:

• SQL: select ... from <table name> where knn ( <field>, <k>, <query vector> [,<options>] )
• JSON:

  POST /search
  {
      "table": "<table name>",
      "knn":
      {
          "field": "<field>",
          "query": "<text or vector>",
          "k": <k>,
          "ef": <ef>,
          "rescore": <rescore>,
          "oversampling": <oversampling>
      }
  }

Параметры:

• field: Имя атрибута с плавающей точкой, содержащего векторные данные.
• k: Количество документов для возврата, ключевой параметр для индексов Hierarchical Navigable Small World (HNSW). Определяет количество документов, которые должен вернуть один индекс HNSW. Однако фактическое количество документов в итоговых результатах может варьироваться. Например, если система работает с таблицами в реальном времени, разбитыми на дисковые чанки, каждый чанк может вернуть k документов, что приведёт к общему числу, превышающему заданное k (так как суммарное количество будет num_chunks * k). С другой стороны, итоговое количество документов может быть меньше k, если после запроса k документов некоторые из них отфильтровываются по определённым атрибутам. Важно отметить, что параметр k не применяется к ramchunks. В контексте ramchunks процесс извлечения работает иначе, и поэтому параметр k не влияет на количество возвращаемых документов.
• query: (Рекомендуемый параметр) Поисковый запрос, который может быть:
  • Текстовой строкой: Автоматически преобразуется в эмбеддинги, если для поля настроены авто-эмбеддинги. Вернёт ошибку, если авто-эмбеддинги не настроены.
  • Массивом векторов: Работает так же, как query_vector.
• query_vector: (Устаревший параметр) Поисковый вектор в виде массива чисел. Поддерживается для обратной совместимости. Примечание: Используйте либо query, либо query_vector, не оба одновременно.
• ef: необязательный размер динамического списка, используемого во время поиска. Более высокий ef обеспечивает более точный, но более медленный поиск.
• rescore: Включает повторный расчёт KNN (по умолчанию отключён). Установите 1 в SQL или true в JSON для включения повторного расчёта. После завершения поиска KNN с использованием квантизированных векторов (с возможным оверсемплингом) расстояния пересчитываются с использованием оригинальных (полной точности) векторов, и результаты пересортировываются для улучшения точности ранжирования.
• oversampling: Устанавливает множитель (число с плавающей точкой), на который умножается k при выполнении поиска KNN, что приводит к выбору большего количества кандидатов, чем требуется, с использованием квантизированных векторов. По умолчанию оверсемплинг не применяется. Эти кандидаты могут быть повторно оценены, если включён повторный расчёт. Оверсемплинг также работает с неквантизированными векторами. Поскольку он увеличивает k, что влияет на работу индекса HNSW, это может вызвать небольшое изменение точности результатов.

Документы всегда сортируются по расстоянию до поискового вектора. Любые дополнительные критерии сортировки, которые вы укажете, применяются после этого основного условия сортировки. Для получения расстояния существует встроенная функция knn_dist().

Индексы HNSW должны быть полностью загружены в память для выполнения поиска KNN, что может привести к значительному потреблению памяти. Для уменьшения использования памяти можно применить скалярное квантование — метод сжатия высокоразмерных векторов путём представления каждого компонента (измерения) ограниченным числом дискретных значений. Manticore поддерживает 8-битное и 1-битное квантование, что означает, что каждый компонент вектора сжимается с 32-битного float до 8 бит или даже 1 бита, уменьшая использование памяти в 4 или 32 раза соответственно. Эти сжатые представления также позволяют быстрее вычислять расстояния, так как больше компонентов вектора можно обработать за одну SIMD-инструкцию. Хотя скалярное квантование вводит некоторую погрешность, это часто оправданный компромисс между точностью поиска и эффективностью ресурсов. Для ещё лучшей точности квантование можно сочетать с повторным расчётом и оверсемплингом: выбирается больше кандидатов, чем запрошено, и расстояния для этих кандидатов пересчитываются с использованием оригинальных 32-битных float-векторов.

Поддерживаемые типы квантования:

• 8bit: Каждый компонент вектора квантован до 8 бит.
• 1bit: Каждый компонент вектора квантован до 1 бита. Используется асимметричное квантование: векторы запроса квантованы до 4 бит, а хранимые векторы — до 1 бита. Такой подход обеспечивает большую точность, чем более простые методы, хотя и с некоторыми потерями в производительности.
• 1bitsimple: Каждый компонент вектора квантован до 1 бита. Этот метод быстрее, чем 1bit, но обычно менее точен.

ПРИМЕЧАНИЕ: Поиск похожих документов по id требует Manticore Buddy. Если не работает, убедитесь, что Buddy установлен.

Нахождение документов, похожих на конкретный, на основе его уникального идентификатора — распространённая задача. Например, когда пользователь просматривает определённый элемент, Manticore Search может эффективно определить и отобразить список элементов, наиболее похожих на него в векторном пространстве. Вот как это можно сделать:

• SQL: select ... from <table name> where knn ( <field>, <k>, <document id> )
• JSON:

  POST /search
  {
      "table": "<table name>",
      "knn":
      {
          "field": "<field>",
          "doc_id": <document id>,
          "k": <k>
      }
  }

Параметры:

• field: Это имя атрибута с плавающей точкой, содержащего векторные данные.
• k: Это количество документов для возврата и ключевой параметр для индексов Hierarchical Navigable Small World (HNSW). Он указывает количество документов, которые должен вернуть один индекс HNSW. Однако фактическое количество документов в итоговых результатах может варьироваться. Например, если система работает с таблицами в реальном времени, разделёнными на дисковые чанки, каждый чанк может вернуть k документов, что приведёт к общему числу, превышающему указанное k (так как суммарное количество будет num_chunks * k). С другой стороны, итоговое количество документов может быть меньше k, если после запроса k документов некоторые из них отфильтровываются по определённым атрибутам. Важно отметить, что параметр k не применяется к ramchunks. В контексте ramchunks процесс извлечения работает иначе, и поэтому параметр k не влияет на количество возвращаемых документов.
• document id: Идентификатор документа для поиска по сходству KNN.

Manticore также поддерживает дополнительную фильтрацию документов, возвращаемых поиском KNN, либо по полнотекстовому совпадению, фильтрам атрибутов, либо по обоим критериям.

ALTER TABLE table ADD COLUMN column_name [{INTEGER|INT|BIGINT|FLOAT|BOOL|MULTI|MULTI64|JSON|STRING|TIMESTAMP|TEXT [INDEXED [ATTRIBUTE]]}] [engine='columnar']
ALTER TABLE table DROP COLUMN column_name
ALTER TABLE table MODIFY COLUMN column_name bigint

Эта функция поддерживает только добавление одного поля за раз для RT таблиц или расширение столбца int до bigint. Поддерживаемые типы данных:

• int - целочисленный атрибут
• timestamp - атрибут временной метки
• bigint - атрибут большого целого числа
• float - атрибут с плавающей точкой
• bool - булев атрибут
• multi - мультизначный целочисленный атрибут
• multi64 - мультизначный атрибут большого целого числа
• json - json атрибут
• string / text attribute / string attribute - строковый атрибут
• text / text indexed stored / string indexed stored - полнотекстовое индексированное поле с оригинальным значением, сохранённым в docstore
• text indexed / string indexed - полнотекстовое индексированное поле, только индексируется (оригинальное значение не сохраняется в docstore)
• text indexed attribute / string indexed attribute - полнотекстовое индексированное поле + строковый атрибут (оригинальное значение не сохраняется в docstore)
• text stored / string stored - значение будет только сохранено в docstore, не полнотекстово индексировано, не строковый атрибут
• добавление engine='columnar' к любому атрибуту (кроме json) сделает его сохранённым в колоночном хранилище

• ❗Рекомендуется создавать резервную копию файлов таблицы перед выполнением ALTER, чтобы избежать повреждения данных в случае внезапного отключения питания или других подобных проблем.
• Запросы к таблице невозможны во время добавления столбца.
• Значения нового атрибута устанавливаются в 0.
• ALTER не работает для распределённых таблиц и таблиц без атрибутов.
• Нельзя удалять столбец id.
• При удалении поля, которое является и полнотекстовым полем, и строковым атрибутом, первый ALTER DROP удаляет атрибут, второй — полнотекстовое поле.
• Добавление/удаление полнотекстового поля поддерживается только в RT режиме.

ALTER TABLE table ft_setting='value'[, ft_setting2='value']

Вы можете использовать ALTER для изменения настроек полнотекстового поиска вашей таблицы в RT режиме. Однако это влияет только на новые документы, а не на существующие. Пример:

• создаём таблицу с полнотекстовым полем и charset_table, которая разрешает только 3 символа для поиска: a, b и c.
• затем вставляем документ 'abcd' и ищем его запросом abcd, символ d игнорируется, так как его нет в массиве charset_table
• затем понимаем, что хотим, чтобы d тоже искался, и добавляем его с помощью ALTER
• но тот же запрос where match('abcd') всё ещё ищет по abc, потому что существующий документ помнит прежнее содержимое charset_table
• затем добавляем другой документ abcd и снова ищем по abcd
• теперь находятся оба документа, и show meta показывает, что использовались два ключевых слова: abc (для старого документа) и abcd (для нового).

Вы можете изменить имя таблицы в режиме RT.

ALTER TABLE table_name RENAME new_table_name;

ПРИМЕЧАНИЕ: Переименование таблицы в режиме реального времени требует Manticore Buddy. Если не работает, убедитесь, что Buddy установлен.

ALTER TABLE table RECONFIGURE

ALTER также может перенастроить RT таблицу в plain режиме, чтобы новые настройки токенизации, морфологии и другой обработки текста из конфигурационного файла применялись к новым документам. Обратите внимание, что существующие документы останутся без изменений. Внутренне это принудительно сохраняет текущий RAM-чанк как новый диск-чанк и корректирует заголовок таблицы, чтобы новые документы токенизировались с использованием обновлённых настроек полнотекстового поиска.

ALTER TABLE table REBUILD SECONDARY

Вы также можете использовать ALTER для перестроения вторичных индексов в заданной таблице. Иногда вторичный индекс может быть отключён для всей таблицы или для одного или нескольких атрибутов в таблице:

• При обновлении атрибута его вторичный индекс отключается.
• Если Manticore загружает таблицу со старой версией вторичных индексов, которая больше не поддерживается, вторичные индексы будут отключены для всей таблицы.

ALTER TABLE table REBUILD SECONDARY перестраивает вторичные индексы из данных атрибутов и снова их включает.

Кроме того, старая версия вторичных индексов может поддерживаться, но будет лишена некоторых функций. REBUILD SECONDARY можно использовать для обновления вторичных индексов.

ALTER TABLE table REBUILD KNN

Команда повторно обрабатывает все векторные данные в таблице и перестраивает KNN индекс с нуля.

ALTER можно использовать для изменения API ключа при использовании удалённой модели для автоэмбеддингов:

ALTER TABLE table_name MODIFY COLUMN column_name API_KEY='key';

Чтобы изменить список локальных или удалённых узлов в распределённой таблице, используйте тот же синтаксис, что и при создании таблицы. Просто замените CREATE на ALTER в команде и удалите type='distributed':

ALTER TABLE `distr_table_name` [[local='local_table_name'], [agent='host:port:remote_table'] ... ]

ПРИМЕЧАНИЕ: Изменение схемы распределённой таблицы онлайн требует Manticore Buddy. Если не работает, убедитесь, что Buddy установлен.