Загрузка из S3-совместимого хранилища

Команда import s3 запускает на стороне сервера процесс загрузки из S3-совместимого хранилища данных и информации об объектах схемы, в описанном в статье Файловая структура формате:

ydb [connection options] import s3 [options]

, где [connection options] — опции соединения с БД

В отличие от команды tools restore, команда import s3 всегда создает объекты целиком, поэтому для её успешного выполнения ни один из загружаемых объектов (ни директорий, ни таблиц) не должен существовать.

При необходимости догрузки данных в существующие таблицы из S3 вы можете скопировать содержимое S3 в файловую систему (например, с помощью S3cmd) и воспользоваться командой tools restore.

Параметры командной строки

[options] - параметры команды:

Параметры S3

Команда загрузки из S3 требует указания параметров соединения с S3. Так как загрузка производится в асинхронном режиме сервером YDB, указанный эндпоинт должен быть доступен для установки соединения со стороны сервера.

--source-prefix PREFIX: Префикс загрузки в бакете S3.

Загружаемые объекты схемы базы данных

--destination-path PATH: Целевая директория для загружаемых объектов; значением по умолчанию является корень базы данных.

--include PATH: Объекты схемы данных для включения в импорт. Директории обходятся рекурсивно. Для включения нескольких объектов допускается указание параметра несколько раз. Если не указан, выполняется загрузка всех объектов выгрузки.

--exclude STRING: Шаблон (PCRE) для исключения путей из импорта. Пути указываются относительно root-path. Данный параметр может быть указан несколько раз для разных шаблонов.

Дополнительные параметры

Выполнение загрузки

Результат запуска

При успешном исполнении команда import s3 выводит сводную информацию о поставленной в очередь операции загрузки из S3, в заданном опцией --format формате. Фактическая загрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией:

• В режиме вывода pretty (по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id:

  ┌───────────────────────────────────────────┬───────┬─────...
  | id                                        | ready | stat...
  ├───────────────────────────────────────────┼───────┼─────...
  | ydb://import/8?id=281474976788395&kind=s3 | true  | SUCC...
  ├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴...
  | Items:
  ...
  

• В режиме вывода proto-json-base64 идентификатор находится в атрибуте "id":

  {"id":"ydb://export/8?id=281474976788395&kind=s3","ready":true, ... }
  

Статус загрузки

Загрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе загрузки можно вызовом команды operation get, параметром которой должен быть передан заключенный в кавычки идентификатор операции, например:

ydb -p quickstart operation get "ydb://import/8?id=281474976788395&kind=s3"

Формат вывода operation get также устанавливается опцией --format.

Несмотря на то, что идентификатор операции имеет формат URL, не гарантируется, что он будет сохранен в дальнейшем. Его нужно интерпретировать только как строку.

Завершение загрузки отслеживается по изменению атрибута "progress":

• В режиме вывода pretty (по умолчанию) успешно завершенная операция отражается значением "Done" в выделенном псевдографикой поле progress:

  ┌───── ... ──┬───────┬─────────┬──────────┬─...
  | id         | ready | status  | progress | ...
  ├──────... ──┼───────┼─────────┼──────────┼─...
  | ydb:/...   | true  | SUCCESS | Done     | ...
  ├╴╴╴╴╴ ... ╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴╴┴╴...
  ...
  

• В режиме вывода proto-json-base64 завершенная операция отражается значением PROGRESS_DONE атрибута progress:

  {"id":"ydb://...", ...,"progress":"PROGRESS_DONE",... }
  

Завершение операции загрузки

После выполнения загрузки воспользуйтесь командой operation forget для того, чтобы загрузка была удалена из перечня операций:

ydb -p quickstart operation forget "ydb://import/8?id=281474976788395&kind=s3"

Список операций загрузки

Для получения списка операций загрузки воспользуйтесь командой operation list import/s3:

ydb -p quickstart operation list import/s3

Формат вывода operation list также устанавливается опцией --format.

Примеры

Загрузка в корень базы данных

Загрузка в корень базы данных содержимого директории export1 в бакете mybucket с использованием параметров аутентификации S3 из переменных окружения или файла ~/.aws/credentials:

ydb -p quickstart import s3 \
  --s3-endpoint storage.yandexcloud.net --bucket mybucket \
  --source-prefix export1

Загрузка нескольких директорий

Загрузка объектов из директорий dir1 и dir2 выгрузки, которая находится в директории export1 в бакете mybucket, в одноименные директории базы данных с использованием явно заданных параметров аутентификации в S3:

ydb -p quickstart import s3 \
  --s3-endpoint storage.yandexcloud.net --bucket mybucket \
  --access-key <access-key> --secret-key <secret-key> \
  --source-prefix export1
  --include dir1 --include dir2

Перечисление объектов в существующей загифрованной выгрузке

Перечисление путей всех объектов в существующей зашифрованной выгрузке, которая находится в директории export1 в бакете mybucket, с использованием секретного ключа из файла ~/my_secret_key.

ydb -p quickstart import s3 \
  --s3-endpoint storage.yandexcloud.net --bucket mybucket \
  --access-key <access-key> --secret-key <secret-key> \
  --source-prefix export1
  --encryption-key-file ~/my_secret_key
  --list

Загрузка зашифрованной выгрузки

Загрузка одной таблицы, которая была выгружена по пути dir/my_table, в путь dir1/dir/my_table из зашифрованной выгрузки, расположенной по префиксу export1 в бакете mybucket, с использованием секретного ключа из файла ~/my_secret_key.

ydb -p quickstart import s3 \
  --s3-endpoint storage.yandexcloud.net --bucket mybucket \
  --access-key <access-key> --secret-key <secret-key> \
  --source-prefix export1 --destination-path dir1 \
  --include dir/my_table \
  --encryption-key-file ~/my_secret_key

Получение идентификаторов операций

Для получения перечня идентификаторов операций загрузки в удобном для обработки в скриптах bash формате вы можете применить утилиту jq:

ydb -p quickstart operation list import/s3 --format proto-json-base64 | jq -r ".operations[].id"

Вы получите вывод, где в каждой новой строке находится идентификатор операции, например:

ydb://import/8?id=281474976789577&kind=s3
ydb://import/8?id=281474976789526&kind=s3
ydb://import/8?id=281474976788779&kind=s3

По этим идентификаторам может быть, например, запущен цикл для завершения всех текущих операций:

ydb -p quickstart operation list import/s3 --format proto-json-base64 | jq -r ".operations[].id" | while read line; do ydb -p quickstart operation forget $line;done