Импорт больших архивов

Команда import split предназначена для импорта больших архивов данных, которые невозможно загрузить целиком из-за ограничений сервера или сети. Архив автоматически разбивается на части (чанки), которые загружаются и обрабатываются последовательно.

warning

Функция находится в стадии активной разработки и тестирования. При возникновении ошибок обращайтесь в поддержку и прикладывайте файл manifest.json из рабочей директории.

Подготовка

Перед началом работы:

1. Установите и настройте timectl согласно инструкции
2. Авторизуйтесь под учетной записью с правами администратора

1. Основной сценарий

Рекомендуемый способ импорта большого архива — одной командой выполнить разбиение, загрузку и обработку:

timectl import split upload ./data.zip \
  --chunk-size=45 \
  --workers-count=3 \
  --process

Параметры:

• --chunk-size=45 — максимальный размер чанка в мегабайтах
• --workers-count=3 — количество параллельных загрузок
• --process — автоматически запустить обработку после загрузки

2. Возобновление после сбоя

Если выполнение прервалось (сбой сети, ошибка, ручная остановка), можно возобновить процесс:

timectl import split upload ./data.zip \
  --work-dir=./import_chunks \
  --resume \
  --process

примечание

Флаг --work-dir должен указывать на директорию с файлом manifest.json, созданную при первом запуске.

Повторная обработка проблемных чанков

Если часть чанков завершилась с ошибкой, можно повторно обработать только их:

timectl import split upload ./data.zip \
  --work-dir=./import_chunks \
  --resume \
  --process \
  --retry-failed

3. Проверка разбиения без загрузки

Чтобы посмотреть, как архив будет разбит на чанки, без фактической загрузки на сервер:

timectl import split ./data.zip --chunk-size=45

В директории import_chunks/ будут созданы:

• manifest.json — метаданные о разбиении
• chunk_0001.zip, chunk_0002.zip, ... — файлы чанков

Проверка размеров:

ls -lh ./import_chunks/chunk_*.zip

Dry-run режим

Альтернативный способ — использовать флаг --dry-run:

timectl import split upload ./data.zip --chunk-size=150 --dry-run

Чанки будут созданы, но загрузка на сервер не выполнится.

Параметры команд

timectl import split

Разбивает архив на чанки без загрузки.

timectl import split <archive.zip> [flags]

Флаг	Описание	По умолчанию
--chunk-size	Максимальный размер чанка в МБ	100

timectl import split upload

Разбивает архив, загружает чанки на сервер и опционально запускает обработку.

timectl import split upload <archive.zip> [flags]

Флаг	Описание	По умолчанию
--chunk-size	Максимальный размер чанка в МБ	100
--work-dir	Рабочая директория для чанков и manifest.json	автогенерация
--workers-count	Количество параллельных загрузок	1
--upload-retries	Число попыток повторной загрузки при ошибке	3
--process	Запустить обработку после загрузки	false
--resume	Возобновить по существующему manifest.json	false
--dry-run	Создать чанки без загрузки на сервер	false
--retry-failed	Повторно обработать чанки со статусом error	false
--continue-on-error	Продолжать при ошибках в отдельных чанках	false

Флаг --continue-on-error

warning

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

При использовании --continue-on-error обработка продолжится даже если некоторые чанки завершатся с ошибкой. Это может привести к:

• ответам на сообщения без исходных сообщений
• реакциям на отсутствующие объекты
• вложениям без родительских постов

Когда использовать:

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

Пример:

timectl import split upload ./data.zip \
  --work-dir=./import_chunks \
  --resume \
  --process \
  --continue-on-error

Проверка статуса импорта

Файл manifest.json содержит информацию о состоянии каждого чанка.

Общая статистика

cat ./import_chunks/manifest.json | jq '{
  total: .chunks | length,
  success: [.chunks[] | select(.status == "success")] | length,
  uploaded: [.chunks[] | select(.status == "uploaded")] | length,
  failed: [.chunks[] | select(.status == "error")] | length
}'

Просмотр проблемных чанков

cat ./import_chunks/manifest.json | jq '.chunks[] | select(.status == "error") | {
  index,
  zip_name,
  error: .process.error_details
}'

Статусы чанков

Статус	Описание
built	Чанк создан
uploaded	Загружен на сервер, ожидает обработки
success	Успешно обработан
error	Ошибка при загрузке или обработке