Сортировки в первую очередь влияют на сравнения строковых атрибутов. Они определяют как кодировку набора символов, так и стратегию, которую Manticore использует для сравнения строк при выполнении ORDER BY или GROUP BY с участием строкового атрибута.

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

Во-первых, строки с одним байтом (ASCII, ISO-8859-1 или Windows-1251) требуют иной обработки, чем строки UTF-8, которые могут кодировать каждый символ переменным числом байт. Поэтому нам нужно знать тип набора символов, чтобы правильно интерпретировать сырые байты как осмысленные символы.

Во-вторых, нам также необходимо знать правила сортировки, специфичные для языка. Например, при сортировке по правилам США в локали en_US, акцентированный символ ï (малая буква i с диарезой) должен размещаться где-то после z. Однако при сортировке с учётом французских правил и локали fr_FR, его следует поместить между i и j. Другой набор правил может вовсе игнорировать акценты, позволяя ï и i смешиваться произвольно.

В-третьих, в некоторых случаях требуется чувствительная к регистру сортировка, а в других — регистронезависимая.

Сортировки инкапсулируют всё перечисленное: набор символов, языковые правила и чувствительность к регистру. В настоящее время Manticore предоставляет четыре сортировки:

1. libc_ci
2. libc_cs
3. utf8_general_ci
4. binary

Первые две сортировки опираются на несколько стандартных вызовов библиотеки C (libc) и, таким образом, могут поддерживать любую локаль, установленную в вашей системе. Они обеспечивают регистронезависимые (_ci) и регистрозависимые (_cs) сравнения соответственно. По умолчанию используется локаль C, что фактически сводит сортировку к побайтовому сравнению. Чтобы изменить это, необходимо указать другую доступную локаль с помощью директивы collation_libc_locale. Список локалей, доступных в вашей системе, обычно можно получить с помощью команды locale:

$ locale -a
C
en_AG
en_AU.utf8
en_BW.utf8
en_CA.utf8
en_DK.utf8
en_GB.utf8
en_HK.utf8
en_IE.utf8
en_IN
en_NG
en_NZ.utf8
en_PH.utf8
en_SG.utf8
en_US.utf8
en_ZA.utf8
en_ZW.utf8
es_ES
fr_FR
POSIX
ru_RU.utf8
ru_UA.utf8

Конкретный список системных локалей может варьироваться. Обратитесь к документации вашей ОС для установки дополнительных нужных локалей.

Локали utf8_general_ci и binary встроены в Manticore. Первая — это универсальная сортировка для UTF-8 данных (без так называемой языковой адаптации); она должна вести себя аналогично сортировке utf8_general_ci в MySQL. Вторая — простое побайтовое сравнение.

Сортировка может быть переопределена через SQL на уровне сессии с помощью оператора SET collation_connection. Все последующие SQL-запросы будут использовать эту сортировку. В противном случае все запросы будут использовать сортировку, установленную по умолчанию на сервере, или указанную в конфигурационной директиве collation_server. В настоящее время по умолчанию в Manticore используется сортировка libc_ci.

Сортировки влияют на все сравнения строковых атрибутов, включая сортировки в ORDER BY и GROUP BY, поэтому можно получить результаты, отсортированные или сгруппированные по-разному в зависимости от выбранной сортировки. Обратите внимание, что сортировки не влияют на полнотекстовый поиск; для этого используйте charset_table.

Когда Manticore выполняет полносканирующий запрос, он может либо использовать простой скан для проверки каждого документа с учётом фильтров, либо применять дополнительные данные и/или алгоритмы для ускорения выполнения запроса. Manticore использует оптимизатор на основе стоимости (CBO), также известный как «оптимизатор запросов», для определения подходящего способа.

CBO также может улучшать производительность полнотекстовых запросов. Подробнее см. ниже.

CBO может решить заменить один или несколько фильтров запроса одним из следующих элементов, если он определит, что это улучшит производительность:

1. Индекс docid использует специальный вторичный индекс только по docid, хранящийся в файлах с расширением .spt. Помимо улучшения фильтрации по числовым ID документов, индекс docid также используется для ускорения сопоставления ID документа с ID строки и для более быстрой обработки больших killlist при запуске демона.
2. колоночное сканирование опирается на колоночное хранение и может использоваться только на колоночном атрибуте. Оно сканирует каждое значение и проверяет его по фильтру, но при этом сильно оптимизировано и обычно быстрее подхода по умолчанию.
3. вторичные индексы создаются по умолчанию для всех атрибутов (кроме JSON). Они используют PGM индекс вместе с встроенным инвертированным индексом Manticore для получения списка идентификаторов строк, соответствующих значению или диапазону значений. Вторичные индексы хранятся в файлах с расширениями .spidx и .spjidx. Для информации о том, как создавать вторичные индексы по JSON атрибутам, см. json_secondary_indexes.

Оптимизатор оценивает стоимость каждого пути выполнения, используя различные статистики атрибутов, включая:

1. Информацию о распределении данных внутри атрибута (гистограммы, хранящиеся в файлах .sphi). Гистограммы создаются автоматически при индексации данных и служат основным источником информации для CBO.
2. Информацию от PGM (вторичных индексов), которая помогает оценить количество списков документов для чтения. Это помогает оценить производительность объединения doclist и выбрать подходящий алгоритм слияния (слияние с приоритетной очередью или слияние битмапов).
3. Статистику кодирования колонок, используемую для оценки производительности декомпрессии колоночных данных.
4. Колоночное дерево min-max. В то время как CBO использует гистограммы для оценки количества документов, остающихся после применения фильтра, он также должен определить, сколько документов фильтр пришлось обработать. Для колоночных атрибутов частичная оценка min-max дерева служит этой цели.
5. Полнотекстовый словарь. CBO использует статистику терминов для оценки стоимости вычисления полнотекстового дерева.

Оптимизатор вычисляет стоимость выполнения для каждого фильтра, используемого в запросе. Поскольку некоторые фильтры можно заменить несколькими разными сущностями (например, для числового ID документа Manticore может использовать обычный проход, обращение к индексу docid, колоночный проход (если ID документа хранится в колонках) и вторичный индекс), оптимизатор оценивает все доступные комбинации. Однако максимальный предел составляет 1024 комбинации.

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

Оптимизатор сравнивает стоимости каждого пути выполнения и выбирает путь с наименьшей стоимостью для выполнения запроса.

При работе с полнотекстовыми запросами, которые содержат фильтры по атрибутам, оптимизатор запросов выбирает один из двух возможных путей выполнения. Либо выполнить полнотекстовый запрос, получить совпадения и применить фильтры. Либо заменить фильтры одним или несколькими элементами, описанными выше, получить из них rowid и внедрить их в полнотекстовое дерево. Таким образом результаты полнотекстового поиска пересекутся с результатами полносканирования. Оптимизатор оценивает стоимость вычисления полнотекстового дерева и наилучший возможный путь вычисления результатов фильтра. Используя эту информацию, оптимизатор выбирает путь выполнения.

Ещё один фактор — многопоточное выполнение запросов (когда включён pseudo_sharding). CBO знает, что некоторые запросы могут выполняться в нескольких потоках, и учитывает это. CBO отдаёт предпочтение более короткому времени выполнения запроса (то есть задержке) по сравнению с пропускной способностью. Например, если запрос с использованием колоночного сканирования может быть выполнен в нескольких потоках (и занять несколько ядер CPU) и при этом быстрее, чем запрос, выполненный в одном потоке с использованием вторичных индексов, будет предпочтительным многопоточное выполнение.

Запросы с использованием вторичных индексов и docid индексов всегда выполняются в одном потоке, поскольку бенчмарки показывают, что многопоточность для них малоэффективна.

На данный момент оптимизатор учитывает только затраты CPU и не принимает во внимание использование памяти или диска.

Manticore Search поддерживает добавление эмбеддингов, сгенерированных моделями машинного обучения, к каждому документу, а затем поиск ближайших соседей по ним. Это позволяет строить такие функции, как поиск по сходству, рекомендации, семантический поиск и ранжирование релевантности на основе алгоритмов NLP, а также поиск по изображениям, видео и звуку.

Чтобы объединить векторный поиск KNN с полнотекстовым поиском для лучшей релевантности, см. Гибридный поиск.

Эмбеддинг - это способ представления данных, таких как текст, изображения или звук, в виде векторов в многомерном пространстве. Эти векторы строятся так, чтобы расстояние между ними отражало сходство представляемых ими данных. Обычно для этого используют такие алгоритмы, как word embeddings (например, Word2Vec, BERT) для текста или нейросети для изображений. Многомерная природа векторного пространства, где у каждого вектора много компонент, позволяет описывать сложные и тонкие связи между объектами. Их сходство оценивают по расстоянию между этими векторами, которое часто измеряют с помощью евклидова расстояния или косинусного сходства.

Manticore Search поддерживает поиск k ближайших соседей (KNN) с использованием библиотеки HNSW. Эта функциональность входит в состав Manticore Columnar Library.

create table test ( title text, image_vector float_vector knn_type='hnsw' knn_dims='4' hnsw_similarity='l2' );

POST /sql?mode=raw -d "create table test ( title text, image_vector float_vector knn_type='hnsw' knn_dims='4' hnsw_similarity='l2' )"

table test_vec {
    type = rt
    ...
    rt_attr_float_vector = image_vector
    knn = {"attrs":[{"name":"image_vector","type":"hnsw","dims":4,"hnsw_similarity":"L2","hnsw_m":16,"hnsw_ef_construction":200}]}
}

Query OK, 0 rows affected (0.01 sec)

[
  {
    "total": 0,
    "error": "",
    "warning": ""
  }
]

CREATE TABLE products (
    title TEXT,
    description TEXT,
    embedding_vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='Xenova/all-MiniLM-L6-v2' FROM='title'
);

CREATE TABLE products_st (
    title TEXT,
    description TEXT,
    embedding_vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='sentence-transformers/all-MiniLM-L6-v2' FROM='title'
);

CREATE TABLE products_qwen (
    title TEXT,
    description TEXT,
    embedding_vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='Qwen/Qwen3-Embedding-0.6B' FROM='title' CACHE_PATH='/opt/homebrew/var/manticore/.cache/manticore'
);

CREATE TABLE products_openai (
    title TEXT,
    description TEXT,
    embedding_vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='openai/text-embedding-ada-002' FROM='title,description' API_KEY='...'
);

CREATE TABLE products_openai_custom (
    title TEXT,
    description TEXT,
    embedding_vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='openai:text-embedding-ada-002' FROM='title,description'
    API_KEY='***' API_URL='https://custom-api.example.com/v1/embeddings' API_TIMEOUT='30'
);

CREATE TABLE products_openrouter (
    title TEXT,
    description TEXT,
    embedding_vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='openai:openai/text-embedding-ada-002' FROM='title,description'
    API_KEY='***' API_URL='https://openrouter.ai/api/v1/embeddings' API_TIMEOUT='30'
);

CREATE TABLE products_all (
    title TEXT,
    description TEXT,
    embedding_vector FLOAT_VECTOR KNN_TYPE='hnsw' HNSW_SIMILARITY='l2'
    MODEL_NAME='Xenova/all-MiniLM-L6-v2' FROM=''
);

table products {
    type = rt
    path = /path/to/products
    rt_field = title
    rt_field = description
    rt_attr_float_vector = embedding_vector
    knn = {"attrs":[{"name":"embedding_vector","type":"hnsw","hnsw_similarity":"L2","hnsw_m":16,"hnsw_ef_construction":200,"model_name":"Xenova/all-MiniLM-L6-v2","from":"title"}]}
}

table products_openai {
    type = rt
    path = /path/to/products_openai
    rt_field = title
    rt_field = description
    rt_attr_float_vector = embedding_vector
    knn = {"attrs":[{"name":"embedding_vector","type":"hnsw","hnsw_similarity":"L2","hnsw_m":16,"hnsw_ef_construction":200,"model_name":"openai/text-embedding-ada-002","from":"title,description","api_key":"your-api-key-here"}]}
}

table products_all {
    type = rt
    path = /path/to/products_all
    rt_field = title
    rt_field = description
    rt_attr_float_vector = embedding_vector
    knn = {"attrs":[{"name":"embedding_vector","type":"hnsw","hnsw_similarity":"L2","hnsw_m":16,"hnsw_ef_construction":200,"model_name":"Xenova/all-MiniLM-L6-v2","from":""}]}
}

INSERT INTO products (title) VALUES
('machine learning artificial intelligence'),
('banana fruit sweet yellow');

INSERT INTO products (title, embedding_vector) VALUES
('machine learning artificial intelligence', (0.653448,0.192478,0.017971,0.339821));

INSERT INTO products_openai (title, description) VALUES
('smartphone', 'latest mobile device with advanced features'),
('laptop', 'portable computer for work and gaming');

INSERT INTO products (title, embedding_vector) VALUES
('no embedding item', ());

POST /sql?mode=raw -d "INSERT INTO products (title) VALUES ('machine learning artificial intelligence'),('banana fruit sweet yellow')"

POST /sql?mode=raw -d "INSERT INTO products_openai (title, description) VALUES ('smartphone', 'latest mobile device with advanced features'), ('laptop', 'portable computer for work and gaming')"

POST /sql?mode=raw -d "INSERT INTO products (title, embedding_vector) VALUES ('no embedding item', ())"

SELECT id, knn_dist() FROM products WHERE knn(embedding_vector, 'machine learning');

POST /search
{
    "table": "products",
    "knn": {
        "field": "embedding_vector",
        "query": "machine learning"
    }
}

POST /search
{
    "table": "products",
    "knn": {
        "field": "embedding_vector",
        "query": [0.1, 0.2, 0.3, 0.4]
    }
}

+------+------------+
| id   | knn_dist() |
+------+------------+
|    1 | 0.12345678 |
|    2 | 0.87654321 |
+------+------------+
2 rows in set (0.00 sec)

{
    "took": 0,
    "timed_out": false,
    "hits": {
        "total": 2,
        "total_relation": "eq",
        "hits": [
            {
                "_id": 1,
                "_score": 1,
                "_knn_dist": 0.12345678,
                "_source": {
                    "title": "machine learning artificial intelligence"
                }
            },
            {
                "_id": 2,
                "_score": 1,
                "_knn_dist": 0.87654321,
                "_source": {
                    "title": "banana fruit sweet yellow"
                }
            }
        ]
    }
}

insert into test values ( 1, 'yellow bag', (0.653448,0.192478,0.017971,0.339821) ), ( 2, 'white bag', (-0.148894,0.748278,0.091892,-0.095406) );

POST /insert
{
    "table":"test_vec",
    "id":1,
    "doc":  { "title" : "yellow bag", "image_vector" : [0.653448,0.192478,0.017971,0.339821] }
}
POST /insert
{
    "table":"test_vec",
    "id":2,
    "doc":  { "title" : "white bag", "image_vector" : [-0.148894,0.748278,0.091892,-0.095406] }
}

Query OK, 2 rows affected (0.00 sec)

{
    "table":"test",
    "id":1,
    "created":true,
    "result":"created",
    "status":201
}
{
    "table":"test",
    "id":2,
    "created":true,
    "result":"created",
    "status":201
}

select id, knn_dist() from test where knn ( image_vector, (0.286569,-0.031816,0.066684,0.032926), { ef=2000, oversampling=3.0, rescore=1 } );

POST /search
{
    "table": "test",
    "knn":
    {
        "field": "image_vector",
        "query": [0.286569,-0.031816,0.066684,0.032926],
        "ef": 2000,
        "rescore": true,
        "oversampling": 3.0
    }
}

+------+------------+
| id   | knn_dist() |
+------+------------+
|    1 | 0.28146550 |
|    2 | 0.81527930 |
+------+------------+
2 rows in set (0.00 sec)

{
    "took":0,
    "timed_out":false,
    "hits":
    {
        "total":2,
        "total_relation":"eq",
        "hits":
        [
            {
                "_id": 1,
                "_score":1,
                "_knn_dist":0.28146550,
                "_source":
                {
                    "title":"yellow bag",
                    "image_vector":[0.653448,0.192478,0.017971,0.339821]
                }
            },
            {
                "_id": 2,
                "_score":1,
                "_knn_dist":0.81527930,
                "_source":
                {
                    "title":"white bag",
                    "image_vector":[-0.148894,0.748278,0.091892,-0.095406]
                }
            }
        ]
    }
}

CREATE TABLE articles(title text, chunk_vectors float_vector_array knn_type='hnsw' knn_dims='4' hnsw_similarity='l2');
INSERT INTO articles VALUES
  (1, 'first',  [[1,0,0,0],[0,1,0,0]]),
  (2, 'second', [[0,0,1,0]]);
-- doc 1 owns a vector identical to the query and another far from it,
-- so it is returned once, at distance 0
SELECT id, knn_dist() FROM articles WHERE knn(chunk_vectors, 5, (1,0,0,0));

POST /search
{
  "table": "articles",
  "knn": {
    "field": "chunk_vectors",
    "query_vector": [1,0,0,0],
    "k": 5
  }
}

По умолчанию модель эмбеддингов читает только столько документа, сколько помещается в ее окно ввода (обычно несколько сотен токенов), а остальное молча отбрасывается. Для заголовка или короткого описания этого достаточно. Для длинной статьи - нет: все, что написано после точки отсечения, уже не удастся извлечь, и об этом не сообщается никакой ошибкой.

Стратегия разбиения определяет, как документ превращается в векторы. Задайте ее с помощью CHUNK_STRATEGY в столбце, привязанном к модели:

truncate и mean создают по одному вектору на документ и работают со столбцом float_vector (в float_vector_array они хранят массив из одного элемента). fixed, recursive и sentence создают несколько векторов, поэтому требуют столбца float_vector_array; использование их в обычном float_vector отклоняется.

Разница в том, что именно считается совпадением. Когда на документ приходится один вектор, поиск спрашивает: «похож ли этот документ целиком на запрос?», и один релевантный абзац размывается всем окружающим текстом. Когда на фрагмент приходится один вектор, вопрос другой: «содержит ли этот документ что-то похожее?» Каждый фрагмент соревнуется отдельно, а документ возвращается один раз с оценкой по своему ближайшему фрагменту (см. Несколько векторов на документ).

Параметры, все действительны только вместе с MODEL_NAME и KNN_TYPE='hnsw':

• CHUNK_STRATEGY: один из пяти вариантов выше. По умолчанию truncate.
• MAX_TOKENS: размер фрагмента в токенах. 0 по умолчанию означает собственный предел модели; большее значение будет снижено до него.
• OVERLAP_TOKENS: сколько токенов общих у соседних фрагментов, чтобы идея, разрезанная границей, все равно полностью попадала хотя бы в один из них. Требует явного ненулевого MAX_TOKENS. Большое перекрытие уменьшается так, чтобы фрагменты по-прежнему продвигались по документу: fixed и recursive ограничивают его половиной MAX_TOKENS, а sentence подготавливает следующий фрагмент максимум из OVERLAP_TOKENS завершающих полных предложений и всегда сдвигается хотя бы на одно предложение.
• MAX_CHUNKS: верхняя граница числа векторов на документ. 0 по умолчанию означает без ограничения.

Важные моменты:

• MAX_CHUNKS отбрасывает текст. При переполнении остаток объединяется с последним сохраненным фрагментом, после чего тот превышает MAX_TOKENS и при кодировании обрезается до окна ввода модели. Видимого разрыва не остается, но хвост теряется.
• Локальные и удаленные модели режут текст по-разному. Локальные модели разбивают его по реальным токенам модели. У удаленных API-моделей (OpenAI, Voyage, Jina) нет локального токенизатора, поэтому вместо него используется консервативная оценка по байтам, и тот же текст с теми же настройками даст другое число фрагментов, чем локальная модель.

ALTER TABLE ... ADD COLUMN с привязанным к модели float_vector_array, а также ALTER TABLE ... REBUILD EMBEDDINGS для него пока не поддерживаются; существующие строки нельзя заполнить задним числом, поэтому столбец останется пустым. Объявляйте такой столбец при создании таблицы. Для столбца float_vector оба варианта работают нормально, в том числе с mean.

-- one vector per sentence group, filled automatically from the text
CREATE TABLE articles (
  title text,
  content text,
  chunks float_vector_array knn_type='hnsw' hnsw_similarity='cosine'
     model_name='Xenova/all-MiniLM-L6-v2' from='title,content'
     chunk_strategy='sentence' max_tokens='256' overlap_tokens='32'
);
INSERT INTO articles (id, title, content) VALUES (1, 'Rotating certificates', 'A long guide with many sections ...');
SELECT id, knn_dist() FROM articles WHERE knn(chunks, 5, 'how do I rotate a certificate');

POST /cli -d "CREATE TABLE articles (title text, content text, chunks float_vector_array knn_type='hnsw' hnsw_similarity='cosine' model_name='Xenova/all-MiniLM-L6-v2' from='title,content' chunk_strategy='sentence' max_tokens='256')"
POST /search
{
  "table": "articles",
  "knn": { "field": "chunks", "query": "how do I rotate a certificate", "k": 5 }
}

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

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

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

create table test ( title text, image_vector float_vector knn_type='hnsw' knn_dims='4' hnsw_similarity='l2' quantization='1bit');

Query OK, 0 rows affected (0.01 sec)

POST /sql?mode=raw -d "create table test ( title text, image_vector float_vector knn_type='hnsw' knn_dims='4' hnsw_similarity='l2' quantization='1bit')"

[
  {
    "total": 0,
    "error": "",
    "warning": ""
  }
]

select id, knn_dist() from test where knn ( image_vector, 5, 1 );

POST /search
{
  "table": "test",
  "knn":
  {
    "field": "image_vector",
    "doc_id": 1,
    "k": 5
  }
}

+------+------------+
| id   | knn_dist() |
+------+------------+
|    2 | 0.81527930 |
+------+------------+
1 row in set (0.00 sec)

{
    "took":0,
    "timed_out":false,
    "hits":
    {
        "total":1,
        "total_relation":"eq",
        "hits":
        [
            {
                "_id": 2,
                "_score":1643,
                "_knn_dist":0.81527930,
                "_source":
                {
                    "title":"white bag",
                    "image_vector":[-0.148894,0.748278,0.091892,-0.095406]
                }
            }
        ]
    }
}

select id, knn_dist() from test where knn ( image_vector, 5, (0.286569,-0.031816,0.066684,0.032926) ) and match('white') and id < 10;

POST /search
{
    "table": "test",
    "knn":
    {
        "field": "image_vector",
        "query": [0.286569,-0.031816,0.066684,0.032926],
        "k": 5
    },
    "query":
    {
        "bool":
        {
            "must":
            [
                { "match": {"_all":"white"} },
                { "range": { "id": { "lt": 10 } } }
            ]
        }
    }
}

+------+------------+
| id   | knn_dist() |
+------+------------+
|    2 | 0.81527930 |
+------+------------+
1 row in set (0.00 sec)

{
    "took":0,
    "timed_out":false,
    "hits":
    {
        "total":1,
        "total_relation":"eq",
        "hits":
        [
            {
                "_id": 2,
                "_score":1643,
                "_knn_dist":0.81527930,
                "_source":
                {
                    "title":"white bag",
                    "image_vector":[-0.148894,0.748278,0.091892,-0.095406]
                }
            }
        ]
    }
}

-- prefilter (default): filter applied during HNSW traversal (ACORN-1 used automatically)
SELECT id, knn_dist() FROM test
WHERE knn ( image_vector, (0.286569,-0.031816,0.066684,0.032926) )
AND price < 100;
-- postfilter: KNN runs over full dataset, filter applied to results
SELECT id, knn_dist() FROM test
WHERE knn ( image_vector, (0.286569,-0.031816,0.066684,0.032926), { prefilter=0 } )
AND price < 100;

// prefilter (default): filter applied during HNSW traversal
POST /search
{
    "table": "test",
    "knn": {
        "field": "image_vector",
        "query": [0.286569,-0.031816,0.066684,0.032926]
    },
    "query": {
        "range": { "price": { "lt": 100 } }
    }
}
// postfilter: filter applied after KNN search
POST /search
{
    "table": "test",
    "knn": {
        "field": "image_vector",
        "query": [0.286569,-0.031816,0.066684,0.032926],
        "prefilter": false
    },
    "query": {
        "range": { "price": { "lt": 100 } }
    }
}

По умолчанию Manticore использует адаптивный алгоритм раннего завершения при обходе графа HNSW. Вместо того чтобы всегда исследовать весь набор кандидатов, заданный ef, он отслеживает скорость, с которой новые кандидаты улучшают результирующий набор, и завершает поиск раньше, когда эта скорость стабильно опускается ниже порога. Это уменьшает число вычислений расстояний без заметного ухудшения качества результатов.

Раннее завершение включено по умолчанию и автоматически отключается, когда k равно 10 или меньше, поскольку для таких маленьких наборов результатов накладные расходы алгоритма не оправданы. Выигрыш в производительности масштабируется с k - чем больше набор результатов, тем больше вычислений расстояния можно сэкономить за счет раннего завершения.

Учтите, что oversampling умножает эффективное k, используемое во время обхода HNSW, поэтому раннее завершение тоже выигрывает от oversampling: более высокое эффективное k означает больше кандидатов, которые потенциально можно пропустить.

-- disable early termination
SELECT id, knn_dist() FROM test WHERE knn ( image_vector, (0.286569,-0.031816,0.066684,0.032926), { ef=200, early_termination=0 } );
-- enable early termination explicitly (default)
SELECT id, knn_dist() FROM test WHERE knn ( image_vector, (0.286569,-0.031816,0.066684,0.032926), { ef=200, early_termination=1 } );

POST /search
{
    "table": "test",
    "knn":
    {
        "field": "image_vector",
        "query": [0.286569,-0.031816,0.066684,0.032926],
        "ef": 200,
        "early_termination": false
    }
}

Когда стоит отключить раннее завершение:

• Когда критически важна точность набора результатов и вы не можете позволить себе никакой аппроксимации сверх той, которую уже обеспечивает HNSW.
• Когда используются низкие значения k (примерно 30 или меньше), при которых раннее завершение дает мало выигрыша в производительности, но может снизить точность.

Гибридный поиск объединяет полнотекстовый (BM25) поиск с KNN векторным поиском в одном запросе, объединяя результаты с использованием Reciprocal Rank Fusion (RRF). Это позволяет использовать сильные стороны обоих методов извлечения: точность по ключевым словам от BM25 и семантическое понимание от векторного сходства.

Полнотекстовый поиск отлично справляется с точным соответствием ключевых слов и редкими терминами, но упускает концептуально похожий контент. Векторный поиск улавливает семантическое значение, но может быть зашумленным на неоднозначных запросах. Гибридный поиск объединяет оба подхода, поэтому документы, которые хорошо оцениваются по любому или обоим сигналам, оказываются на поверхности.

RRF — это алгоритм слияния, основанный на рангах. Он работает с позициями рангов, а не с исходными оценками, что позволяет избежать необходимости нормализации несовместимых шкал оценок (оценки BM25 неограничены; расстояния KNN имеют другую шкалу).

RRF_score(d) = SUM over all result sets r:  weight_r / (rank_constant + rank_r(d))

Где:

• d — это документ
• rank_r(d) — это позиция документа (начиная с 1) в наборе результатов r (отсортированном по оценке этого извлекателя)
• rank_constant — это константа сглаживания (по умолчанию: 60, настраивается через опцию rank_constant)
• weight_r — это необязательный вес для каждого извлекателя (по умолчанию: 1.0)

Если документ не появляется в конкретном наборе результатов, его вклад от этого набора равен 0.

• rank_constant=60 используется по умолчанию.
• Меньшие значения (например, 10) усиливают различия между элементами с наивысшим рангом.
• Более высокие значения (например, 100) распределяют влияние более равномерно по всем рангам.

Объедините MATCH(...) и KNN(...) в предложении WHERE с OPTION fusion_method='rrf':

SELECT id, hybrid_score()
FROM t
WHERE match('machine learning')
  AND knn(vec, (0.1, 0.1, 0.1, 0.1))
OPTION fusion_method='rrf';

POST /search
{
  "table": "t",
  "knn": {
    "field": "vec",
    "query_vector": [0.1, 0.1, 0.1, 0.1]
  },
  "query": { "match": { "title": "machine learning" } },
  "options": { "fusion_method": "rrf" }
}

Это запускает текстовый поиск и KNN поиск как независимые параллельные подзапросы, а затем объединяет результаты с помощью RRF. Без fusion_method='rrf' запрос выполняется как обычный KNN поиск, отфильтрованный по текстовому соответствию (поведение до гибридного поиска).

В этом режиме до гибридного поиска ранжирование KNN по-прежнему имеет приоритет. Если knn_dist() доступна и вы не сортируете по ней явно, Manticore добавляет knn_dist() ASC в начало порядка сортировки. На практике ORDER BY weight() DESC становится вторичным критерием разрешения ничьих, а не глобальной сортировкой по BM25.

• hybrid_score() — оценка слияния RRF (доступна только в гибридных запросах)
• weight() — оценка текстового соответствия BM25
• knn_dist() — векторное расстояние (минимум по всем KNN подзапросам, если их несколько)

-- Default rank_constant=60 (gentler ranking)
SELECT id, hybrid_score() FROM t
WHERE match('machine learning') AND knn(vec, (0.1, 0.1, 0.1, 0.1))
OPTION fusion_method='rrf';
-- rank_constant=10 (sharper top-rank differences)
SELECT id, hybrid_score() FROM t
WHERE match('machine learning') AND knn(vec, (0.1, 0.1, 0.1, 0.1))
OPTION fusion_method='rrf', rank_constant=10;

POST /search
{
  "table": "t",
  "knn": { "field": "vec", "query_vector": [0.1, 0.1, 0.1, 0.1] },
  "query": { "match": { "title": "machine learning" } },
  "options": { "fusion_method": "rrf", "rank_constant": 10 }
}

Обычные фильтры атрибутов работают вместе с гибридным поиском и применяются как к текстовому, так и к KNN-подзапросам. Фильтры по weight() и зависящим от него выражениям применяются после объединения результатов, используя итоговый текстовый вес. Текущее ограничение Manticore: эти фильтры веса нельзя использовать в деревьях фильтров с OR.

Например, фильтрация по обычному атрибуту:

SELECT id, category, hybrid_score()
FROM t
WHERE match('machine learning')
  AND knn(vec, (0.1, 0.1, 0.1, 0.1))
  AND category = 1
OPTION fusion_method='rrf';

POST /search
{
  "table": "t",
  "knn": { "field": "vec", "query_vector": [0.1, 0.1, 0.1, 0.1] },
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "machine learning" } },
        { "equals": { "category": 1 } }
      ]
    }
  },
  "options": { "fusion_method": "rrf" }
}

По умолчанию результаты сортируются по hybrid_score() DESC. Вы можете переопределить это:

Этот раздел относится к истинным гибридным запросам, т.е. запросам с использованием OPTION fusion_method='rrf'. Без fusion_method='rrf' запрос, включающий KNN(...), не объединяется и остается с приоритетом KNN, поэтому ORDER BY weight() DESC не дает глобально отсортированного по весу набора результатов.

-- Sort by hybrid score ascending
SELECT id, hybrid_score() FROM t
WHERE match('machine learning') AND knn(vec, (0.1, 0.1, 0.1, 0.1))
ORDER BY hybrid_score() ASC
OPTION fusion_method='rrf';
-- Sort by text weight
SELECT id, weight() FROM t
WHERE match('machine learning') AND knn(vec, (0.1, 0.1, 0.1, 0.1))
ORDER BY weight() DESC, id ASC
OPTION fusion_method='rrf';
-- Sort by KNN distance
SELECT id, knn_dist() FROM t
WHERE match('machine learning') AND knn(vec, (0.1, 0.1, 0.1, 0.1))
ORDER BY knn_dist() ASC
OPTION fusion_method='rrf';

Если текстовый запрос не соответствует ни одному документу, только результаты KNN вносят вклад в оценку RRF:

SELECT id, hybrid_score() FROM t
WHERE match('xyznonexistent') AND knn(vec, (0.1, 0.1, 0.1, 0.1))
OPTION fusion_method='rrf';
-- Returns results ranked purely by KNN rank

Один гибридный запрос может объединять текстовый поиск с несколькими KNN поисками по разным векторным атрибутам. Все они объединяются через RRF:

-- Three-way fusion: text + vec1 KNN + vec2 KNN
SELECT id, hybrid_score()
FROM t
WHERE match('machine learning')
  AND knn(vec1, (0.1, 0.1, 0.1, 0.1))
  AND knn(vec2, (1.0, 0.0, 0.0, 0.0))
OPTION fusion_method='rrf';
-- KNN-only fusion (no text), two vector searches
SELECT id, hybrid_score()
FROM t
WHERE knn(vec1, (0.1, 0.1, 0.1, 0.1))
  AND knn(vec2, (1.0, 0.0, 0.0, 0.0))
OPTION fusion_method='rrf';

POST /search
{
  "table": "t",
  "knn": [
    { "field": "vec1", "query_vector": [0.1, 0.1, 0.1, 0.1] },
    { "field": "vec2", "query_vector": [1.0, 0.0, 0.0, 0.0] }
  ],
  "query": { "match": { "title": "machine learning" } },
  "options": { "fusion_method": "rrf" }
}

Несколько KNN поисков без fusion_method приводят к ошибке.

По умолчанию все подзапросы вносят равный вклад (вес 1.0). Чтобы придать разную важность текстовому и KNN поискам, используйте fusion_weights с явными псевдонимами:

SELECT id, hybrid_score()
FROM t
WHERE match('machine learning') AS text
  AND knn(vec1, (0.1, 0.1, 0.1, 0.1)) AS dense1
  AND knn(vec2, (1.0, 0.0, 0.0, 0.0)) AS dense2
OPTION fusion_method='rrf',
       fusion_weights=(text=0.7, dense1=0.2, dense2=0.1);

POST /search
{
  "table": "t",
  "knn": [
    { "field": "vec1", "query_vector": [0.1, 0.1, 0.1, 0.1], "name": "dense1" },
    { "field": "vec2", "query_vector": [1.0, 0.0, 0.0, 0.0], "name": "dense2" }
  ],
  "query": { "match": { "title": "machine learning" } },
  "options": {
    "fusion_method": "rrf",
    "fusion_weights": { "query": 0.7, "dense1": 0.2, "dense2": 0.1 }
  }
}

SQL:

• Используйте AS alias для MATCH(...) и KNN(...), чтобы дать им имена. Неявных/псевдонимов по умолчанию нет.
• Пропущенные псевдонимы по умолчанию имеют вес 1.0.
• Ссылка на несуществующий псевдоним приводит к ошибке.

JSON:

• "query" — это фиксированный псевдоним для полнотекстового подзапроса.
• Псевдонимы KNN устанавливаются через свойство "name" для каждой записи KNN.
• Запись KNN с именем "query" конфликтует с текстовым псевдонимом и приводит к ошибке.
• Неявные псевдонимы (имена полей без явного "name") не поддерживаются в fusion_weights.

Вы можете указать веса только для некоторых подзапросов; остальные по умолчанию будут иметь вес 1.0:

-- Only boost text, KNN searches default to weight 1.0
SELECT id, hybrid_score()
FROM t
WHERE match('machine learning') AS text
  AND knn(vec1, (0.1, 0.1, 0.1, 0.1)) AS dense1
  AND knn(vec2, (1.0, 0.0, 0.0, 0.0)) AS dense2
OPTION fusion_method='rrf', fusion_weights=(text=2.0);

Для таблиц с настроенными авто-эмбеддингами на атрибуте float_vector, hybrid_match() предоставляет сокращенную запись, которая автоматически запускает как текстовый, так и KNN поиск из одной строки запроса:

-- Explicit vector field
SELECT id, hybrid_score() FROM t WHERE hybrid_match('machine learning', vec);
-- Auto-detect vector field (requires exactly one auto-embedding attribute)
SELECT id, hybrid_score() FROM t WHERE hybrid_match('machine learning');
-- With custom k and rank_constant
SELECT id, hybrid_score() FROM t
WHERE hybrid_match('machine learning', vec, {k=3})
OPTION rank_constant=10;
-- With attribute filter
SELECT id, hybrid_score() FROM t
WHERE hybrid_match('machine learning', vec) AND category=1;

hybrid_match() автоматически:

1. Выполняет текстовый запрос как полнотекстовый поиск BM25
2. Генерирует эмбеддинг из той же текстовой строки
3. Выполняет KNN поиск с использованием этого эмбеддинга
4. Объединяет результаты через RRF

Требование: Векторный атрибут должен иметь настроенные model_name и from для авто-эмбеддингов. Без них hybrid_match() возвращает ошибку.

POST /search
{
  "table": "hj",
  "hybrid": { "query": "machine learning" }
}
POST /search
{
  "table": "hj",
  "hybrid": { "query": "machine learning", "field": "vec" }
}
POST /search
{
  "table": "hj",
  "hybrid": { "query": "machine learning" },
  "options": { "rank_constant": 10 }
}

Свойство "hybrid" не может использоваться вместе с "knn".

Когда векторный атрибут имеет авто-эмбеддинги, вы можете использовать "query" (строка) вместо "query_vector" (массив) в объекте knn:

POST /search
{
  "table": "ht",
  "knn": { "field": "vec", "query": "machine learning", "k": 5 },
  "query": { "match": { "title": "machine learning" } },
  "options": { "fusion_method": "rrf" }
}

Строка автоматически преобразуется в эмбеддинг во время выполнения запроса. Без настроенных авто-эмбеддингов это возвращает ошибку.

Внутренне гибридный запрос разделяется на N+1 параллельных подзапросов:

1. Задача 0: Полнотекстовый (BM25) подзапрос (пропускается, если текстовый запрос пуст, чтобы избежать загрязнения RRF результатами полного сканирования)
2. Задачи 1..N: Один KNN подзапрос на каждую запись knn(...)

Все подзапросы выполняются параллельно. После завершения всех, RRF-слияние:

1. Собирает ранжированные результаты из каждого подзапроса
2. Для каждого документа накапливает вклады в оценку RRF от каждого подзапроса, в котором он появляется
3. Сортирует по объединенной оценке RRF по убыванию
4. Устанавливает knn_dist() равной минимальному расстоянию по всем KNN подзапросам для каждого документа
5. Сохраняет weight() из текстового подзапроса