Введение

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

Эта статья — практическое руководство по созданию автодополнения с Manticore Search. Вы узнаете, как использовать:

• CALL AUTOCOMPLETE и HTTP‑endpoint /autocomplete
• быстрые словарные запросы с CALL KEYWORDS
• завершение предложений с использованием инфикс‑поиска и подсветки
• практические советы по запуску автодополнения в продакшн

Кому это следует читать

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

Краткое руководство по выбору

• Используйте CALL AUTOCOMPLETE (или POST /autocomplete) когда вам нужны опечатко‑устойчивые, многословные предложения из проиндексированных данных.
• Используйте CALL KEYWORDS когда вам нужны молниеносные, словарные завершения для отдельных слов или очень коротких фраз.
• Используйте инфикс‑поиск с подсветкой когда вам нужны предложения уровня фразы или предложения (например, показать оставшуюся часть предложения документа).
• Включите bigram_index если вам нужны предсказания двух слов (предсказание «следующего слова»).

Требования и предостережения

• Buddy требуется для CALL AUTOCOMPLETE и HTTP‑endpoint /autocomplete. Если Buddy не установлен, эти вызовы не будут работать.
• Целевая таблица должна иметь включённые инфиксы (min_infix_len). Manticore кэширует проверку min_infix_len примерно на 30 секунд для повышения производительности; если вы измените min_infix_len (например, при настройке производительности поиска или включении автодополнения в существующей таблице), вы можете увидеть небольшую несогласованность в течение этого периода.
• CALL AUTOCOMPLETE кэширует только успешные проверки. Если вы отключите min_infix_len или удалите таблицу, последующие вызовы автодополнения могут работать со старыми данными, пока кэш не обновится или не появится ошибка.

## CALL AUTOCOMPLETE — быстрый пример (SQL)

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

CALL AUTOCOMPLETE('ice', 'products');

Типичный набор результатов содержит строки с единственным столбцом под названием query:

+---------------+
| query         |
+---------------+
| ice           |
| ice cream     |
| iceberg       |
| iceland       |
+---------------+

### Как работает CALL AUTOCOMPLETE (кратко)

CALL AUTOCOMPLETE — это удобный высокоуровневый интерфейс, который оркестрирует несколько низкоуровневых примитивов внутри Manticore для создания быстрых, релевантных предложений. На практике он объединяет:

• CALL KEYWORDS: быстрые словарные запросы, которые возвращают кандидаты токенов с префиксом/инфиксом и статистику (docs/hits). Это то, что даёт автодополнению сильные, низколатентные варианты из словаря индекса.
• Рутины предложений (исторически доступные через CALL SUGGEST / CALL QSUGGEST): процедуры, которые создают нечеткие варианты токенов (особенно последнего слова) и помогают генерировать опечатко‑устойчивые альтернативы.
• Логика нечеткого поиска: тот же расчёт расстояния редактирования (Levenshtein) и эвристики ранжирования, введённые для нечеткого поиска, которые поток автодополнения переиспользует для ранжирования и фильтрации кандидатов.

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

### Когда не следует вызывать CALL KEYWORDS напрямую

CALL KEYWORDS — отличный, чрезвычайно быстрый инструмент, когда нужны строгие словарные завершения (точные совпадения префикса/инфикса). Однако он не обеспечивает опечатко‑устойчивость или составление многословных предложений. Для многословных, опечатко‑устойчивых предложений предпочтительнее CALL AUTOCOMPLETE; используйте CALL KEYWORDS для очень коротких префиксов, горячих списков или когда явно нужны только словарные результаты.

### Сопоставление опций (высокоуровневое)

• fuzziness в CALL AUTOCOMPLETE соответствует ограничению расстояния редактирования, аналогично max_edits в API предложений.
• preserve управляет тем, сохраняются ли нефаззи токены рядом с фаззи совпадениями.
• layouts включает предположение раскладки клавиатуры перед фаззи‑оценкой.

Примечание: внутреннее сочетание примитивов, описанное здесь, отражает подход к реализации, но должно рассматриваться как деталь реализации — полагайтесь на документированный API CALL AUTOCOMPLETE и его опции, а не на внутреннее поведение при проектировании вашего приложения.

Эти внутренние комбинации объясняют, почему CALL AUTOCOMPLETE часто дает более качественные и удобные предложения, чем отдельный запуск CALL KEYWORDS.
### Пример HTTP/JSON (Buddy)

Если вы предпочитаете HTTP или у вас есть фронтенд, работающий с JSON, используйте endpoint /autocomplete, предоставляемый Buddy:

POST /autocomplete
{
  "table": "products",
  "query": "ice"
}

JSON‑ответ возвращает массив предложенных завершений (и метаданных), которые можно отобразить в пользовательском интерфейсе.

## Опции CALL AUTOCOMPLETE объяснены

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

• layouts: Коды раскладок клавиатуры, разделённые запятыми (us, ru, ua, de, fr и т.д.). Используйте это для обнаружения ввода с ошибочной раскладкой (например, ввод «ghbdtn» на английской раскладке, когда вы хотели набрать «привет» — русское слово «hello»). Требуется как минимум две раскладки для сравнения позиций символов.
• fuzziness: 0, 1 или 2 (по умолчанию 2). Максимальное расстояние Левенштейна для сопоставления опечаток. Установите 0, чтобы отключить нечёткость.
• preserve: 0 или 1 (по умолчанию 0). Если 1, предложения будут включать слова, которые не получили нечёткие совпадения (полезно для сохранения имён собственных или коротких токенов).
• prepend / append: Булево (0/1). Если true, перед/после последнего слова добавляется звёздочка для расширения префиксов/суффиксов (например, prepend → *word, append → word*).
• expansion_len: Количество символов для расширения последнего токена (по умолчанию 10). Определяет, сколько символов будет учитываться при расширении.

Пример с опциями (SQL)

CALL AUTOCOMPLETE('ghbdtn', 'comments', 'us,ru' as layouts, 1 as fuzziness);

Это обнаружит, что «ghbdtn» является версией с ошибочной раскладкой слова «привет» (русское слово «hello») и применит нечёткое сопоставление для поиска правильных предложений.

CALL KEYWORDS — завершения на основе токенов

Когда вам нужно предлагать только отдельные слова (или окончания) и требуется максимальная скорость, CALL KEYWORDS является отличной альтернативой. Он использует словарь индекса вместо сканирования документов, что делает его очень эффективным.

Базовый синтаксис:

CALL KEYWORDS('ca*', 'products', 1 AS stats, 'hits' AS sort_mode);

Это возвращает строки с tokenized и normalized формами и необязательной статистикой (docs, hits). Сортировка по hits выводит самые популярные завершения.

Пример результата (иллюстративный):

+------+-----------+------------+------+------+
| qpos | tokenized | normalized | docs | hits |
+------+-----------+------------+------+------+
| 1    | ca*       | cat        | 1    | 2    |
| 1    | ca*       | carnivorous| 1    | 1    |
+------+-----------+------------+------+------+

Приём bigram_index

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

Завершение предложений с инфиксным поиском и подсветкой

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

• Примеры запросов, которые вы можете выполнять по мере ввода пользователем:
  • ^"m*"
  • ^"my *"
  • ^"my c*"
  • ^"my ca*"

Используйте якорь ^ для совпадения с начала и * для расширения остального. При включённой подсветке вы можете извлечь совпавшую часть и представить её как предложение (например: «My cat loves ...»).

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

Шаблон интеграции (frontend → backend)

Минимальный, готовый к продакшену поток выглядит так:

1. Дебаунс ввода пользователя (150–300 мс), чтобы избежать слишком большого количества запросов.
2. Для 1–2 символов используйте CALL KEYWORDS или горячий список.
3. Для 3 и более символов вызывайте /autocomplete или CALL AUTOCOMPLETE. Включайте соответствующие опции (layouts, fuzziness) в зависимости от ваших пользователей.
4. Показывайте предложения с подсвеченными совпадениями.
5. Отслеживайте клики и переупорядочивайте предложения по популярности или бизнес‑правилам.

Советы по UX

• Показывайте 6–10 предложений на десктопе, 3–5 на мобильных устройствах.
• Группируйте по типу (например, товары, документы, люди), если это уместно.
• Всегда предлагайте запасной вариант: например, «Search for {query}».

Советы по продакшену

• min_infix_len: Убедитесь, что значение установлено корректно для вашего языка и сценария использования. Очень маленькие значения увеличивают размер индекса и нагрузку на CPU; очень большие значения снижают гибкость сопоставления.
• Кеширование: дайте ~30 с для применения изменений, таких как min_infix_len.
• Ограничение скорости: используйте дросселирование запросов или кеширование в памяти для высокой нагрузки.
• Обслуживание индекса: рассмотрите предвычисление таблицы «top suggestions» для самых популярных префиксов.

Чек‑лист по устранению неполадок

Если автодополнение работает неожиданно:

1. Убедитесь, что Buddy установлен (если используется /autocomplete).
2. Проверьте, что в таблице установлен min_infix_len и включены инфиксы.
3. Повторите попытку через 30 секунд, чтобы внутренний кеш успел обновиться, если вы недавно изменили настройки таблицы.
4. Попробуйте CALL KEYWORDS для того же префикса, чтобы убедиться, что токены присутствуют в словаре.
5. Проверьте настройки кодировки и токенизации (morphology, stopwords), которые могут влиять на результаты.

Пример: полный поток (пример)

Пользователь вводит: "ice c"

Клиент (с дебаунсом) отправляет:

POST /autocomplete
{
  "table": "products",
  "query": "ice c",
  "options": { "fuzziness": 1 }
}

Сервер возвращает предложения, такие как «ice cream», «ice coffee», «ice cold». UI отображает их; при выборе клиент переходит по поисковому URL вроде /search?q=ice+cream или получает детали продукта, используя выбранное предложение.

Заключение

Автодополнение — небольшая функция UX, которая приносит непропорционально большую ценность: более быстрый поиск, меньше тупиков и более высокая удовлетворённость пользователей. С Manticore Search у вас есть практические варианты реализации предложений — от быстрого, словарного CALL KEYWORDS до более гибкого, устойчивого к опечаткам CALL AUTOCOMPLETE (и HTTP‑эндпоинта /autocomplete через Buddy). Используйте описанные здесь подходы, чтобы сбалансировать задержку, точность и затраты ресурсов для вашего приложения.

Попробуйте примеры из этой статьи на вашем индексе, следите за качеством предложений и настраивайте такие параметры, как fuzziness и min_infix_len, чтобы они соответствовали вашим данным и пользователям. Если вам нужен лёгкий стартовый вариант … (продолжение)

Создавайте более умный и быстрый поиск с автодополнением.