Подсказки и автодополнение

Suggestions — короткие варианты запроса, которые показываются во время ввода: автокомплит в поисковой строке, «возможно вы имели в виду…» на no-results, тренды на пустом состоянии. Это слой UX над теми же индексами, не отдельный движок.

Что значит «suggestions» здесь

Три разных источника, у каждого свой эндпоинт:

Виджет совмещает все три в одном дропдауне; интегратору API можно взять любое подмножество.

Статус

Title-prefix автокомплит

Самый аккуратный паттерн — два поиска в одном round-trip через multi-search: основной поиск для списка и маленький — для дропдауна.

const [main, suggestions] = await client.multiSearch([
  {
    indexSlug: "products",
    q: "wireless head",
    queryBy: "title,brand,description",
    perPage: 20,
    facetBy: "brand,categories",
  },
  {
    indexSlug: "products",
    q: "wireless head",
    queryBy: "title",
    perPage: 5,
    includeFields: "id,title",
    highlightFields: "title",
  },
]);

Советы:

• Suggestion-поиск делайте дешёвым: queryBy только title, perPage ≤ 5, includeFields только колонки, которые отображаете.
• highlightFields: "title" — чтобы выделить совпавший префикс жирным.
• Debounce 150–300 мс. Без него каждый keystroke — round-trip, быстро, но дорого.

Полная схема multi-search — Multi-search and querying.

Популярные запросы

Откуда брать:

Analytics API

const popular = await orpc.search.topQueries.call({
  organizationId,
  period: "30d",
  limit: 10,
});

Возвращает { query, searches, clicks, ctr, zeroResults }[] из SearchUsageEvent. Подходит для админ-панели или «trending»-виджета.

Пустое состояние

Покажите топ-5–10 популярных запросов при фокусе на пустой строке. На клиенте кэшируйте 5–15 минут — данные меняются медленно.

Did-you-mean / spell-check

POST /v1/projects/{projectId}/spell-check

Вход — строка запроса. Выход — список исправленных кандидатов по убыванию confidence, из словаря индексов org. Используйте, когда основной поиск отдал < 3 хитов:

const main = await search({ q: "iphine" });

if (main.found < 3) {
  const corrections = await spellCheck({ q: "iphine" });
  // → ["iphone", "iphone 15", …]
}

Важно: spell-check не перезапускает поиск — он отдаёт кандидатов. UI решает, авто-запустить топ или показать ссылку «Возможно вы имели в виду: iphone?».

Аутентификация

Все три источника используют ту же auth/квоту, что и keyword search:

• Bearer search-key (ss_search_*) — origin-restricted, rate-limited.
• Scoped tokens (HMAC) — сужают видимые документы; их scopedFilter AND-комбинируется и в основной, и в suggestion поиск (Инвариант 4).
• Per-org лимиты из SearchRateLimitBucket.

Scoped token с indexSlug: "products" отклонит suggestion-вызов в другом индексе.

Группировка в аналитике

Suggestion-вызовы и последующий клик связаны через query_id из multi-search response. Передайте query_id в click-event, чтобы аналитика связала impression и клик в одном фанеле:

trackClick({
  query_id: main.queryId,
  document_id: clickedHit.id,
});

Схема событий — Обзор Analytics.

Кэширование и debounce

Прижатый виджет (packages/widget/src/index.ts) идёт с debounce = 200 мс и 30-entry LRU; держите свои интеграции в тех же цифрах.

Когда suggestions не нужны

• Голосовой/сканер-ввод — пользователь уже фиксировал строку.
• Mobile-флоу без набора с заходом по deep link.
• Внутренний админский поиск, где норма — точные ID.

В этих случаях рендерите сразу список, suggestion-панель пропустите.

Связанные страницы

• Обзор AI Search
• Multi-search and querying
• Обзор Analytics — измерение suggestion-driven трафика
• Обзор виджета