Загрузить много товаров

Когда товаров много (тысячи или миллионы), их нужно загружать не вручную, а пакетами.

Массовая загрузка

CSV файл (самый простой)

1. Подготовьте таблицу Excel:

2. Сохраните как CSV
3. В панели управления нажмите Загрузить CSV

AACsearch загружает товары в фоне. Вы увидите прогресс.

JSON файл

1. Подготовьте JSON:

[
  {"id": "1", "title": "Красная рубашка", "price": 1500},
  {"id": "2", "title": "Синие брюки", "price": 2500}
]

2. В панели управления нажмите Загрузить JSON

API (для программистов)

curl -X POST https://api.aacsearch.com/api/ingest \
  -H "Authorization: Bearer ss_ingest_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "товары",
    "documents": [
      {"id": "1", "title": "Красная рубашка", "price": 1500},
      {"id": "2", "title": "Синие брюки", "price": 2500}
    ]
  }'

Как часто обновлять

Рекомендации:

• Маленький магазин (до 1000 товаров) — раз в день ночью
• Средний магазин (1000-50000 товаров) — раз в 6 часов
• Крупный магазин (50000+ товаров) — раз в 1-2 часа

Частота не должна быть чаще 1 раза в 5 минут (может нагрузить сервер).

Что происходит при загрузке

1. Товары добавляются в очередь — они не теряются, даже если сервер упадёт
2. Фоновый процесс их обрабатывает — обычно это занимает 1-5 секунд
3. Товары появляются в поиске — покупатели сразу видят новые товары

Переиндексация

Переиндексация нужна, если вы хотите изменить параметры поиска. Например:

• Изменить вес слова (например, название должно быть важнее описания)
• Добавить новое поле (например, цвет)
• Изменить язык поиска

Как это работает

1. AACsearch создаёт новую версию индекса (v2)
2. Загружает товары в новую версию
3. Тестирует, что поиск работает
4. Переключает поиск на новую версию (атомарно, за миллисекунды)

Во время переиндексации:

• Поиск не прерывается — покупатели ищут как обычно
• Новые товары могут не появиться на несколько минут
• Когда индексация закончится, всё обновится

Запустить переиндексацию

1. В панели управления перейдите Поиск → Индексы
2. Выберите индекс
3. Нажмите Переиндексировать
4. Смотрите прогресс

Обычно переиндексация занимает от 1 до 30 минут (в зависимости от количества товаров).

Что если что-то пошло не так

Товары не появляются в поиске

• Подождите 5-10 секунд (индексирование занимает время)
• Проверьте, что товары в индексе (в панели управления)
• Проверьте формат — может быть, цена как текст вместо числа

Индексирование очень долго

Это нормально для большого каталога. Индексирование на 1 млн товаров может занять 30-60 минут.

Можно:

• Загружать товары частями (по 10 000 за раз)
• Напишите в поддержку — подберём оптимальный размер батча

Потеряны все товары

Не переживайте! Ищите в истории (панель управления → История загрузок). Товары можно восстановить.

Ваш код / модуль CMS
    │
    ▼
POST /api/connector/sync/full (или upsertDocument oRPC)
    │
    ▼
enqueueManySearchIngest()  ←  запись в SearchIngestBuffer (Postgres)
    │
    ▼
Фоновый воркер  ←  дренирует буфер пакетами
    │
    ▼
bulkUpsert() → AACSearch
    │
    ▼
markIngestRowsSuccess() / markIngestRowsFailure() (экспоненциальная задержка)

Ключевой инвариант: bulkUpsert() вызывается только из фонового воркера. Никогда не вызывайте его напрямую из обработчика запроса — это нарушит буфер и гарантии надёжности.

Добавление одного документа

await orpc.search.upsertDocument.call({
	organizationId: "org_...",
	indexSlug: "products",
	document: {
		id: "product-456",
		title: "Running Shoes",
		sku: "RS-001",
		brand: "SpeedCo",
		categories: ["Sports", "Footwear"],
		price: 79.99,
		availability: "in_stock",
		locale: "en",
		created_at: Math.floor(Date.now() / 1000),
	},
});

Процедура oRPC вызывает enqueueManySearchIngest() с массивом из одного элемента.

Массовый импорт через панель управления

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

1. Перейдите в Поиск → Импорт заданий
2. Нажмите Импорт документов
3. Загрузите файл CSV или JSON
4. Сопоставьте столбцы с полями документа
5. Нажмите Начать импорт

Задания импорта отслеживаются в базе данных со статусом (pending, processing, success, failed) и счётчиками элементов. Неудавшиеся строки отображаются в детальном представлении задания импорта.

Массовый приём через Connector API

Модули CMS отправляют массовые данные через Connector API:

curl -X POST https://your-app.com/api/connector/sync/full \
  -H "Authorization: Bearer ss_connector_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "indexSlug": "products",
    "documents": [
      { "id": "1", "title": "Product A", "price": 29.99, ... },
      { "id": "2", "title": "Product B", "price": 49.99, ... }
    ]
  }'

Рекомендуемый размер пакета — 200 документов. Большие пакеты увеличивают задержку импорта AACSearch и создают риск таймаута при медленном соединении. Модули CMS используют настраиваемый размер пакета (по умолчанию: 200).

Обработка частичных сбоев

Воркер независимо помечает каждую строку как успешную или неудавшуюся. При частичном сбое пакета:

1. Успешные документы фиксируются через markIngestRowsSuccess()
2. Неудавшиеся документы помечаются через markIngestRowsFailure(), и запланирована повторная попытка
3. Повторные попытки используют экспоненциальную задержку: 1 с → 2 с → 4 с → 8 с → отказ после настраиваемого максимального числа попыток

Постоянно неудавшиеся строки отображаются в панели Импорт заданий с сообщениями об ошибках.

Переиндексация (без простоя)

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

Как это работает

Текущее состояние:
  псевдоним: org123_products  →  org123_products_v1  (обслуживает трафик)

Во время переиндексации:
  1. Создание: org123_products_v2 (новая схема)
  2. Массовый импорт всех документов в v2
  3. Проверка работоспособности v2 (количество документов совпадает)
  4. Атомарная замена псевдонима: org123_products  →  org123_products_v2
  5. Сохранение v1 до следующей переиндексации (вариант отката)

После переиндексации:
  псевдоним: org123_products  →  org123_products_v2  (обслуживает трафик)
  org123_products_v1  остаётся (но не обслуживает трафик)

Запуск переиндексации через панель управления

Перейдите в Поиск → Индексы → выберите индекс → Переиндексировать.

Запуск переиндексации через oRPC

const job = await orpc.search.reindex.call({
	organizationId: "org_...",
	indexSlug: "products",
});
// job.status: "queued" | "running" | "succeeded" | "failed"

Когда требуется переиндексация

Переиндексация и квота

Переиндексация засчитывает проиндексированные документы в квоту вашего плана. Для больших каталогов на бесплатном плане (10 000 единиц) переиндексация израсходует месячную квоту. Планируйте соответственно.

Повтор неудавшихся пакетов

Неудавшиеся пакеты приёма данных можно повторить из панели управления в Импорт заданий → выберите неудавшееся задание → Повторить, или через oRPC:

await orpc.search.retryFailedBatches.call({
	organizationId: "org_...",
	indexSlug: "products",
});

Это повторно ставит в очередь все строки со статусом failed для данного индекса.