Сделать поиск по каталогу легко. Гораздо сложнее — сделать каталог, который полезен не только на первом запросе.

Это демо как раз об этом. Здесь мы используем небольшой каталог настольных игр, но сам сценарий знаком многим: пользователь вводит что-то полузабытое, ошибается в написании, сужает выдачу по ограничениям, листает дальше, открывает карточку, а потом хочет увидеть «что-то похожее», не начиная всё заново. Если в вашем продукте есть такой сценарий, основная работа — не в полировке интерфейса. Важнее добиться правильного поведения поиска и не переусложнить весь стек.

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

Сначала можно попробовать уже развёрнутую версию:

https://catalog.manticoresearch.com

Приложение написано на PHP, но здесь важен не столько сам язык. Важнее то, как без лишней возни перейти от простой поисковой строки к каталогу, в котором всё уже работает как надо: поиск, фильтры, фасеты и блок похожих документов появляются довольно быстро.

Запускаем локально

Чтобы запустить это демо локально, вам нужны только PHP 8.1+, Composer и Docker (или любой другой способ запустить Manticore).

Здесь Manticore отвечает за поиск в каталоге: индексацию, фильтрацию, фасетирование и семантический поиск. В репозитории уже есть Docker-конфигурация, поэтому быстрее всего клонировать проект и поднять Manticore из каталога проекта:

git clone https://github.com/manticoresoftware/php-catalog-demo
cd php-catalog-demo
docker compose up -d

docker compose ps должен показать, что контейнер запущен.

В клонированном репозитории создайте файл окружения приложения:

cp app/.env.example app/.env

Для локального запуска важно только то, как приложение подключается к Manticore:

MANTICORE_HOST=127.0.0.1
MANTICORE_PORT=9308

Установите зависимости:

cd app
composer install

Демо читает эти настройки и создаёт клиента Manticore:

$settings = require $root . '/config/settings.php';

$client = new Client([
    'host' => $settings['manticore']['host'],
    'port' => $settings['manticore']['port'],
    'transport' => 'Http',
]);

Затем загрузите демонстрационный набор данных:

php bin/bootstrap-demo.php

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

Запустите приложение:

php -S localhost:8081 -t public

Откройте http://localhost:8081/ — и у вас сразу будет каталог, в котором можно искать.

Не самая эффектная часть. Но она важна. Многие демо поиска теряют читателя ещё до первого запроса, потому что старт получается слишком громоздким. Здесь этого нет.

Почему этим приложением удобно пользоваться

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

Начните с автодополнения

Обычно пользователь вводит запрос не целиком. Иногда он помнит точное название игры. Чаще — нет.

Поэтому первый шаг здесь — автодополнение:

$payload = [
    'body' => [
        'query' => $term,
        'table' => $this->tableName,
        'options' => ['limit' => $limit, 'force_bigrams' => 1],
    ],
];
$suggestions = $this->client->autocomplete($payload);

force_bigrams здесь помогает точнее сопоставлять короткие или слегка неверные запросы с учётом опечаток — как раз там, где автодополнение иначе быстро начинает шуметь.

Это небольшая функция, но она сразу меняет восприятие приложения. Пользователь перестаёт гадать, как именно каталог называет нужные вещи.

Сделайте первую страницу результатов терпимее к ошибкам

После отправки запроса первая страница должна оставаться полезной, даже если в написании есть небольшая ошибка.

$search = (new Search($this->client))
    ->setTable($this->tableName)
    ->limit($limit);

if ($query !== '') {
    $search->search($query);
    if ($fuzzy) {
        $search->option('fuzzy', 1)->option('force_bigrams', 1);
    }
} else {
    $search->search('*');
}

Режим нечёткого поиска решает очень практичную задачу: находит близкие совпадения, когда пользователь вводит название не совсем точно.

Если хотите изучить эту тему детальнее, смотрите Исправление орфографии и нечеткий поиск .

Дайте пользователю отфильтровать результаты без переписывания запроса

Именно здесь многие поисковые интерфейсы начинают раздражать. Запрос уже достаточно близок к нужному, но результатов всё ещё слишком много, и пользователю приходится переформулировать его с нуля.

Проще дать ему отфильтровать результаты прямо на месте.

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

$attributeFilters = [
    'price_min' => $priceMin,
    'price_max' => $priceMax,
    'play_time_min' => $playTimeMin,
    'play_time_max' => $playTimeMax,
    'player_count_min' => $playerCountMin,
    'player_count_max' => $playerCountMax,
    'release_year_min' => $yearMin,
    'release_year_max' => $yearMax,
];

if ($categoryIds !== []) {
    $search->filter('category_id', 'in', $categoryIds);
}
if ($tagIds !== []) {
    $search->filter('tag_id', 'in', $tagIds);
}
$this->applyNumericFilters($search, $attributeFilters);
$search->facet('category_id')->facet('tag_id');

Это сочетание важнее, чем может показаться по описанию. На практике именно здесь каталог становится удобнее: широкий запрос быстро сужается после клика по категории или тегу, а исходный смысл поиска не теряется.

Чтобы глубокая пагинация оставалась стабильной

Если листать результаты дальше, offset-пагинация довольно быстро показывает свои слабые места. Данные меняются между запросами, offset растёт, и в какой-то момент кнопка «показать ещё» становится менее надёжной, чем должна быть.

В этом демо вместо этого используются scroll-токены:

// Page 1 starts a fresh scroll session; next pages continue with returned token.
$effectiveScrollToken = $page > 1 ? $scrollToken : null;
$search->option('scroll', $effectiveScrollToken ?? true);

$resultSet = new ResultSet($this->client->search(['body' => $body], true));
$nextScroll = $resultSet->getScroll();
$hasMore = $nextScroll !== null && (string) $nextScroll !== '';

Это даёт приложению более устойчивую основу для глубокой пагинации: каждый запрос продолжается с возвращённого токена, а не всё глубже уходит в offset.

С точки зрения эксплуатации это как раз тот случай, который пользователи не замечают, пока всё работает, и сразу замечают, когда что-то идёт не так. Подробнее о механике — в статье Пагинация на основе прокрутки .

Добавьте семантический поиск там, где ключевых слов уже не хватает

Поиск по ключевым словам помогает во многих случаях. Но этого всё равно недостаточно для всех сценариев.

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

Используйте гибридный поиск на странице результатов

В этом демо один запрос включает и лексический блок query, и семантический блок knn, а затем объединяет их через RRF в options.fusion_method = rrf:

$body = [
    'query' => ['bool' => ['must' => [['query_string' => ['query' => $query]]]]],
    'knn' => [
        'field' => 'description_vector',
        'query' => $query,
    ],
    'options' => ['fusion_method' => 'rrf'],
    'limit' => $limit,
];

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

'description_vector' => [
    'type' => 'float_vector',
    'options' => [
        'MODEL_NAME' => 'sentence-transformers/all-MiniLM-L6-v2',
        'FROM' => 'description',
    ],
],

Поскольку блок knn напрямую указывает векторное поле ('field' => 'description_vector'), Manticore может автоматически строить эмбеддинг для текста запроса при KNN-поиске.

Это заметно упрощает логику приложения по сравнению с тем, чего многие ожидают, впервые услышав про «семантический поиск». И заодно позволяет оставить всё в одной выдаче на странице результатов, а не прикручивать семантику отдельным слоем.

Показывайте похожие документы на странице карточки

То же векторное поле решает другую задачу уже на карточке: «покажи похожие игры», не заставляя пользователя придумывать новый запрос. Здесь KNN работает напрямую от текущего документа.

$search = new Search($this->client);
$search->setTable($this->tableName)
    ->knn('description_vector', $source->getId(), self::SIMILAR_KNN_LIMIT)
    ->notFilter('id', 'in', [$source->getId()])
    ->limit(self::SIMILAR_RESULT_LIMIT);

$resultSet = $search->get();
$hits = $this->formatResultSet($resultSet)['hits'];
return array_slice($hits, 0, self::SIMILAR_RESULT_LIMIT);

Здесь поиск перестаёт быть просто утилитой и начинает помогать с выбором. На живой карточке именно этот блок позволяет продолжать изучать каталог, а не возвращаться каждый раз обратно к строке поиска.

Для справки: Автоэмбеддинги и Поиск KNN .

Синхронизация записей и результатов поиска

Пока данные не меняются, демо-приложению легко доверять. В реальном приложении так почти не бывает.

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

Для пакетного импорта используются batch-операции записи через клиента:

$table = $this->client->table($this->indexConfig['name']);

if ($appendAsNewIds) {
    $table->addDocuments($batch);
} else {
    $table->replaceDocuments($batch);
}

Для изменений отдельных элементов приложение использует API таблицы напрямую:

if ($id > 0) {
    $this->table->replaceDocument($document, $id);
} else {
    $this->table->addDocument($document);
}

$this->table->deleteDocument($id);

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

$baseMaxId = $this->resolveBaseMaxId();

$this->table->deleteDocuments([
    'range' => [
        'id' => ['gt' => $baseMaxId],
    ],
]);

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

Что в итоге

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

Этого уже достаточно, чтобы поиск ощущался частью продукта, а не просто внешней надстройкой.