Загрузка из 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, указанный эндпоинт должен быть доступен для установки соединения со стороны сервера.
Перечень загружаемых объектов
--item STRING: Описание объекта загрузки. Параметр --item может быть указан несколько раз, если необходимо выполнить загрузку нескольких объектов. STRING задается в формате <свойство>=<значение>,..., со следующими обязательными свойствами:
source,srcилиs— путь (префикс ключа) в S3 с загружаемой директорией или таблицейdestination,dst, илиd— путь в базе данных для размещения загружаемой директории или таблицы. Конечный элемент пути не должен существовать. Все директории на пути будут созданы, если не существуют.
Дополнительные параметры
--description STRING: Текстовое описание операции, сохраняемое в истории операций
--retries NUM: Количество повторных попыток загрузки, которые будет предпринимать сервер. По умолчанию 10.
--format STRING: Формат вывода результата
pretty: Человекочитаемый формат (по умолчанию)proto-json-base64: Protobuf в формате json, бинарные строки закодированы в base64
Выполнение загрузки
Результат запуска
При успешном исполнении команда 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.
Примеры
Примечание
В примерах используется профиль quickstart, подробнее смотрите в Создание профиля для соединения с тестовой БД.
Загрузка в корень базы данных
Загрузка в корень базы данных содержимого директории export1 в бакете mybucket с использованием параметров аутентификации S3 из переменных окружения или файла ~/.aws/credentials:
ydb -p quickstart import s3 \
--s3-endpoint storage.yandexcloud.net --bucket mybucket \
--item src=export1,dst=.
Загрузка нескольких директорий
Загрузка объектов из директорий dir1 и dir2 бакета S3 mybucket в одноименные директории базы данных с использованием явно заданных параметров аутентификации в S3:
ydb -p quickstart import s3 \
--s3-endpoint storage.yandexcloud.net --bucket mybucket \
--access-key VJGSOScgs-5kDGeo2hO9 --secret-key fZ_VB1Wi5-fdKSqH6074a7w0J4X0 \
--item src=export/dir1,dst=dir1 --item src=export/dir2,dst=dir2
Получение идентификаторов операций
Для получения перечня идентификаторов операций загрузки в удобном для обработки в скриптах 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