Scroll и Batch операции

Вам нужно обновить модель embeddings для 5 миллионов точек. Наивный подход: getPoint → generate embedding → upsert (с payload!) для каждой точки. Правильный подход: scroll → updateVectors (payload не трогаем). Разница: в 3 раза меньше данных по сети и вдвое быстрее.

• **Full collection export:** scroll по всей коллекции для создания дампа данных или верификации после восстановления snapshot
• **Bulk re-embedding:** смена embedding модели без пересоздания коллекции — scroll + updateVectors сохраняет payload и минимизирует трафик
• **Batch payload updates:** массовое обновление статусов, меток, метаданных через batch set_payload без трогания векторов

Предварительные знания

• Points, Vectors, Payloads

Scroll API: итерация по всей коллекции

**Scroll API** - это полный перебор точек коллекции страницами. В отличие от `search` (ANN поиск), scroll не требует вектора запроса и возвращает точки в порядке их ID. Используется когда нужны *все* точки, а не топ-N похожих: - Экспорт всей коллекции - Верификация после восстановления snapshot - Batch re-embedding (обновить векторы всех точек) - Аналитика по payload полям Pagination в scroll работает через **offset** (ID последней полученной точки), не через `skip`/`page`.

**Scroll vs Search:** `search` использует HNSW индекс (ANN) - быстро, но только топ-N близких векторов. `scroll` делает полный перебор - медленнее, но гарантированно возвращает все точки. Scroll нельзя сортировать по score - только по ID. Для сортировки по payload полю используйте фильтр + scroll с клиентской сортировкой, или `order_by` параметр (Qdrant 1.8+).

Batch API: несколько операций в одном запросе

**Batch API** позволяет объединить несколько операций модификации точек в одном HTTP запросе. Вместо 10 отдельных запросов - один batch. Qdrant поддерживает следующие типы операций в batch: - `upsert` - создать или обновить точки полностью - `delete` - удалить точки по ID или filter - `set_payload` - добавить/обновить поля payload (merge) - `overwrite_payload` - заменить весь payload целиком - `delete_payload` - удалить конкретные ключи payload - `clear_payload` - очистить весь payload - `update_vectors` - обновить векторы без пересоздания точки - `delete_vectors` - удалить named vectors

**Batch != транзакция.** Операции в batch выполняются последовательно на сервере, но не атомарно. Если вторая операция в batch упадёт, первая уже применена. Для атомарного обновления нескольких точек используйте один `upsert` с массивом - он является атомарным (либо все точки записаны, либо ни одна).

Update Vectors: обновить вектор без пересоздания точки

**Update Vectors API** позволяет обновить только вектор(ы) точки, не трогая payload. Это важно для: 1. **Re-embedding** - смена модели (text-embedding-ada-002 → text-embedding-3-small) 2. **Named vectors** - обновить только один вектор из нескольких (например, только `title_vector`, не трогая `body_vector`) 3. **Производительность** - upsert полностью заменяет точку (требует передать все данные), update_vectors обновляет только вектор

**Re-embedding в production:** при смене модели нужно пересоздать коллекцию с новым vector size (text-embedding-3-small = 1536 dims, ada-002 = 1536 dims совпадают, но семантика разная). Стратегия zero-downtime: создать новую коллекцию → re-embed все точки → атомарно переключить алиас (Qdrant Collection Aliases API) → удалить старую коллекцию.

Итоги

• **Scroll API** — полный перебор коллекции постранично через offset (point ID). Поддерживает фильтры. Scroll vs Search: scroll = все точки, search = топ-N по сходству.
• **Batch API** — несколько операций в одном HTTP запросе: upsert, delete, set_payload, overwrite_payload, delete_payload, clear_payload, update_vectors, delete_vectors.
• **Batch != транзакция** — операции выполняются последовательно, не атомарно. Один upsert массива — атомарен.
• **Update Vectors API** — обновить только вектор(ы), payload сохраняется. Для named vectors: обновить только нужный вектор из нескольких.
• **Re-embedding flow:** scroll(with_payload) → generate new embeddings → updateVectors (только ID + vector). Нет необходимости передавать payload.

Что дальше

Научились работать с данными в bulk. Следующий шаг - безопасность: API keys, JWT и TLS для production деплоя.

• Security & Auth — Закрыть Scroll и Batch API от неавторизованного доступа через API keys и JWT
• Snapshots — Scroll + snapshot - комбинация для backup и верификации данных
• Points и Vectors — Базовые концепции точек и векторов которые Scroll и Batch оперируют

Вопросы для размышления

• Как реализовать zero-downtime re-embedding: старая коллекция продолжает обслуживать запросы пока новая заполняется. Когда переключить?
• Scroll с limit: 1000 возвращает данные медленнее чем limit: 100 × 10 страниц. Почему? Как выбрать оптимальный размер страницы?
• Batch set_payload обновляет 10000 точек. Как убедиться что все обновления применились? Как написать верификацию?

Связанные уроки

• db-09-indexes-btree