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

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

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

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

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

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

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

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

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

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

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

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

• Sentence Transformers: Любая подходящая модель на основе BERT из Hugging Face (например, sentence-transformers/all-MiniLM-L6-v2) — ключ API не требуется. Manticore загружает модель при создании таблицы.
• Qwen локальные эмбеддинги: Модели эмбеддингов Qwen, такие как Qwen/Qwen3-Embedding-0.6B — ключ 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>, <query vector> [,<options>] )
• JSON:

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

Параметры:

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

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

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

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

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

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

Поиск документов, похожих на конкретный, на основе его уникального ID, является распространённой задачей. Например, когда пользователь просматривает определённый элемент, 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: ID документа для поиска сходства KNN.

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

ALTER TABLE table ADD COLUMN column_name [{INTEGER|INT|BIGINT|FLOAT|BOOL|MULTI|MULTI64|JSON [secondary_index='1']|STRING|TEXT [INDEXED [ATTRIBUTE]]|TIMESTAMP}] [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 - многозначный атрибут bigint
• json - атрибут json; используйте secondary_index='1' для создания вторичного индекса по 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-таблицу в обычном режиме, чтобы новые настройки токенизации, морфологии и другие настройки обработки текста из файла конфигурации вступили в силу для новых документов. Обратите внимание, что существующие документы останутся нетронутыми. Внутренне он принудительно сохраняет текущий 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 установлен.