--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ydb.tech/docs/en/reference/ydb-cli/export-import/import-s3.md?version=main - https://ydb.tech/docs/ru/reference/ydb-cli/export-import/import-s3.md?version=main sourcePath: ru/core/reference/ydb-cli/export-import/import-s3.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Загрузка из S3-совместимого хранилища Команда `import s3` запускает на стороне сервера процесс загрузки из S3-совместимого хранилища данных и информации об объектах схемы, в описанном в статье [Файловая структура](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/file-structure.md?version=main) формате: ```bash ydb [connection options] import s3 [options] ``` {% note info %} Импорт таблиц из S3-совместимого хранилища данных в других форматах возможен с использованием [внешних таблиц](https://ydb.tech/docs/ru/concepts/query_execution/federated_query/s3/external_table.md?version=main), подробнее см. в статье [Импорт данных](https://ydb.tech/docs/ru/concepts/query_execution/federated_query/import_and_export.md?version=main#import). {% endnote %} , где `[connection options]` — опции [соединения с БД](https://ydb.tech/docs/ru/reference/ydb-cli/connect.md?version=main#command-line-pars) В отличие от [команды `tools restore`](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/tools-restore.md?version=main), команда `import s3` всегда создает объекты целиком, поэтому для её успешного выполнения ни один из загружаемых объектов (ни директорий, ни таблиц) не должен существовать. При необходимости догрузки данных в существующие таблицы из S3 вы можете скопировать содержимое S3 в файловую систему (например, с помощью [S3cmd](https://s3tools.org/s3cmd)) и воспользоваться [командой `tools restore`](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/tools-restore.md?version=main). ## Параметры командной строки {#pars} `[options]` - параметры команды: ### Параметры S3 {#s3-params} Команда загрузки из S3 требует указания [параметров соединения с S3](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/auth-s3.md?version=main). Так как загрузка производится в асинхронном режиме сервером YDB, указанный эндпоинт должен быть доступен для установки соединения со стороны сервера. `--source-prefix PREFIX`: Префикс загрузки в бакете S3. ### Загружаемые объекты схемы базы данных {#objects} `--destination-path PATH`: Целевая директория для загружаемых объектов; значением по умолчанию является корень базы данных. `--include PATH`: Объекты схемы данных для включения в импорт. Директории обходятся рекурсивно. Для включения нескольких объектов допускается указание параметра несколько раз. Если не указан, выполняется загрузка всех объектов выгрузки. `--exclude STRING`: Шаблон ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) для исключения путей из импорта. Данный параметр может быть указан несколько раз для разных шаблонов. {% cut "Альтернативный способ" %} В целях обратной совместимости поддерживается альтернативный способ указания перечня объектов: `--item STRING`: Описание объекта загрузки. Параметр `--item` может быть указан несколько раз, если необходимо выполнить загрузку нескольких объектов. Если параметры `--item` или `--include` не указаны, будут загружены все объекты, присутствующие в указанной выгрузке. `STRING` задаётся в формате `<свойство>=<значение>,...` со следующими обязательными свойствами: - `source`, `src` или `s` — префикс ключа в S3 с загружаемой директорией или таблицей. - `destination`, `dst`, или `d` — путь в базе данных для размещения загружаемой директории или таблицы. Конечный элемент пути не должен существовать. Все директории на пути будут созданы, если не существуют. Некоторые возможности могут быть недоступны при использовании альтернативного синтаксиса (в частности, шифрованные резервные копии или перечисление объектов выгрузки). {% endcut %} ### Дополнительные параметры {#aux} - `--description STRING`: Текстовое описание операции, сохраняемое в истории операций. - `--retries NUM`: Количество повторных попыток загрузки, которые будет предпринимать сервер. Значение по умолчанию: `10`. - `--skip-checksum-validation`: Пропустить этап валидации [контрольных сумм](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/file-structure.md?version=main#checksums) загружаемых объектов. - `--index-population-mode STRING`: Режим наполнения индексов при импорте. Допустимые значения: - `build` — построить индексы с нуля (значение по умолчанию); - `import` — загрузить данные индексных таблиц (если выгрузка была выполнена с опцией `--include-index-data`); - `auto` — попытаться загрузить данные индексных таблиц, при отсутствии данных построить индексы. - `--encryption-key-file PATH`: Путь к файлу, содержащему ключ шифрования (только для зашифрованных выгрузок). Данный файл является бинарным и должен содержать точное количество байт, соответствующее длине ключа в выбранном алгоритме шифрования (16 байт для `AES-128-GCM`, 32 байта для `AES-256-GCM` и `ChaCha20-Poly1305`). Ключ также может быть передан через переменную окружения `YDB_ENCRYPTION_KEY`, в шестнадцатеричном строковом представлении. - `--format STRING`: Формат вывода результата. Допустимые значения: - `pretty` — человекочитаемый формат (по умолчанию); - `proto-json-base64` — [Protocol Buffers](https://ru.wikipedia.org/wiki/Protocol_Buffers) в формате [JSON](https://ru.wikipedia.org/wiki/JSON), бинарные строки закодированы в [Base64](https://ru.wikipedia.org/wiki/Base64). - `--list`: Перечислить объекты в существующей выгрузке. {% note info %} Использование режима `--index-population-mode=import` позволяет максимально задействовать ресурсы и быстро восстановить индексы, либо наоборот — ограничить ресурсы и скопировать индексные таблицы с минимальным влиянием на пользовательскую нагрузку. Для ограничения ресурсов импорта используется [очередь `queue_restore`](https://ydb.tech/docs/ru/reference/configuration/resource_broker_config.md?version=main) брокера ресурсов. {% endnote %} ## Выполнение загрузки {#exec} ### Ход серверной операции загрузки {#server-import-workflow} 1. Создаётся серверная асинхронная операция импорта. 2. Сервер считывает метаданные объектов из файлов (`scheme.pb`, `metadata.json` и т.д.) из хранилища. 3. Для каждого объекта создаётся новая таблица в базе данных. Целевые пути **не должны существовать** — импорт не может перезаписать существующие таблицы. 4. Данные загружаются из файлов параллельно на всех узлах кластера. ### Результат запуска {#result} При успешном исполнении команда `import s3` выводит сводную информацию о поставленной в очередь операции загрузки из S3, в заданном опцией `--format` формате. Фактическая загрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией: - В режиме вывода `pretty` (по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id: ```text ┌───────────────────────────────────────────┬───────┬─────... | id | ready | stat... ├───────────────────────────────────────────┼───────┼─────... | ydb://import/8?id=281474976788395&kind=s3 | true | SUCC... ├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴... | Items: ... ``` - В режиме вывода `proto-json-base64` идентификатор находится в атрибуте "id": ```json {"id":"ydb://import/8?id=281474976788395&kind=s3","ready":true, ... } ``` ### Статус загрузки {#status} Загрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе загрузки можно вызовом команды `operation get`, параметром которой должен быть передан **заключенный в кавычки** идентификатор операции, например: ```bash ydb -p quickstart operation get "ydb://import/8?id=281474976788395&kind=s3" ``` Формат вывода `operation get` также устанавливается опцией `--format`. Несмотря на то, что идентификатор операции имеет формат URL, не гарантируется, что он будет сохранен в дальнейшем. Его нужно интерпретировать только как строку. Завершение загрузки отслеживается по изменению атрибута "progress": - В режиме вывода `pretty` (по умолчанию) успешно завершенная операция отражается значением "Done" в выделенном псевдографикой поле `progress`: ```text ┌───── ... ──┬───────┬─────────┬──────────┬─... | id | ready | status | progress | ... ├──────... ──┼───────┼─────────┼──────────┼─... | ydb://... | true | SUCCESS | Done | ... ├╴╴╴╴╴ ... ╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴╴┴╴... ... ``` - В режиме вывода `proto-json-base64` завершенная операция отражается значением `PROGRESS_DONE` атрибута `progress`: ```json {"id":"ydb://...", ...,"progress":"PROGRESS_DONE",... } ``` ### Завершение операции загрузки {#forget} После выполнения загрузки воспользуйтесь командой `operation forget` для того, чтобы загрузка была удалена из перечня операций: ```bash ydb -p quickstart operation forget "ydb://import/8?id=281474976788395&kind=s3" ``` ### Список операций загрузки {#list} Для получения списка операций загрузки воспользуйтесь командой `operation list import/s3`: ```bash ydb -p quickstart operation list import/s3 ``` Формат вывода `operation list` также устанавливается опцией `--format`. ## Примеры {#examples} {% note info %} В примерах используется профиль `quickstart`, подробнее смотрите в [Создание профиля для соединения с тестовой БД](https://ydb.tech/docs/ru/reference/ydb-cli/profile/create.md?version=main#quickstart). {% endnote %} ### Загрузка в корень базы данных {#example-full-db} Загрузка в корень базы данных содержимого директории `export1` в бакете `mybucket` с использованием параметров аутентификации S3 из переменных окружения или файла `~/.aws/credentials`: ```bash ydb -p quickstart import s3 \ --s3-endpoint storage.yandexcloud.net --bucket mybucket \ --source-prefix export1 ``` ### Загрузка нескольких директорий {#example-specific-dirs} Загрузка объектов из директорий `dir1` и `dir2` выгрузки, которая находится в директории `export1` в бакете `mybucket`, в одноименные директории базы данных с использованием явно заданных параметров аутентификации в S3: ```bash ydb -p quickstart import s3 \ --s3-endpoint storage.yandexcloud.net --bucket mybucket \ --access-key --secret-key \ --source-prefix export1 --include dir1 --include dir2 ``` ### Перечисление объектов в существующей зашифрованной выгрузке {#example-list} Перечисление путей всех объектов в существующей зашифрованной выгрузке, которая находится в директории `export1` в бакете `mybucket`, с использованием секретного ключа из файла `~/my_secret_key`. ```bash ydb -p quickstart import s3 \ --s3-endpoint storage.yandexcloud.net --bucket mybucket \ --access-key --secret-key \ --source-prefix export1 --encryption-key-file ~/my_secret_key --list ``` ### Загрузка зашифрованной выгрузки {#example-encryption} Загрузка одной таблицы, которая была выгружена по пути `dir/my_table`, в путь `dir1/dir/my_table` из зашифрованной выгрузки, расположенной по префиксу `export1` в бакете `mybucket`, с использованием секретного ключа из файла `~/my_secret_key`. ```bash ydb -p quickstart import s3 \ --s3-endpoint storage.yandexcloud.net --bucket mybucket \ --access-key --secret-key \ --source-prefix export1 --destination-path dir1 \ --include dir/my_table \ --encryption-key-file ~/my_secret_key ``` ### Получение идентификаторов операций {#example-list-oneline} Для получения перечня идентификаторов операций загрузки в удобном для обработки в скриптах bash формате вы можете применить утилиту [jq](https://stedolan.github.io/jq/download/): ```bash ydb -p quickstart operation list import/s3 --format proto-json-base64 | jq -r ".operations[].id" ``` Вы получите вывод, где в каждой новой строке находится идентификатор операции, например: ```text ydb://import/8?id=281474976789577&kind=s3 ydb://import/8?id=281474976789526&kind=s3 ydb://import/8?id=281474976788779&kind=s3 ``` По этим идентификаторам может быть, например, запущен цикл для завершения всех текущих операций: ```bash 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 ```