Загрузка из файловой системы
Команда tools restore создает в базе данных объекты схемы данных и загружает в них данные из файловой системы, ранее выгруженные туда командой tools dump, или подготовленные вручную в соответствии с правилами, описанными в статье Файловая структура:
ydb [connection options] tools restore -p PATH -i PATH [options]
, где [connection options] — опции соединения с БД
Если таблица или директория уже существует в базе данных, изменения в её схему или ACL внесены не будут. Это может привести к тому, что операция загрузки данных окажется невозможной, если не все колонки из загружаемых файлов присутствуют в таблице или если есть несоответствия по типам данных.
Для загрузки данных в таблицу применяется команда YQL REPLACE. Если до момента загрузки в таблице существовали записи, то те из них, ключи которых существуют в загружаемых файлах, будут заменены данными из файлов; записи с теми ключами, которых не существует в загружаемых файлах, останутся без изменений.
Обязательные параметры
-p PATH или --path PATH: Путь к директории в базе данных, внутрь которой будет выполняться загрузка. Для загрузки в корневой каталог укажите .. Все отсутствующие директории на пути будут созданы.
-i PATH или --input PATH: Путь к директории в клиентской файловой системе, откуда будет выполняться загрузка.
Необязательные параметры
[options] - необязательные параметры команды:
--restore-data VAL: Флаг загрузки данных, 1 (да) или 0 (нет), по умолчанию 1. Если флаг установлен в 0, то при загрузке будут только созданы объекты в схеме, а данные в них загружены не будут. Если в файловой системе нет данных (выгружена только схема), то изменение флага не имеет значения.
--restore-indexes VAL: Флаг загрузки индексов, 1 (да) или 0 (нет), по умолчанию 1. Если флаг установлен в 0, то при загрузке вторичные индексы не будут ни зарегистрированы в схеме данных, ни заполнены данными.
--restore-acl VAL: Флаг загрузки ACL, 1 (да) или 0 (нет), по умолчанию 1. Если флаг установлен в 0, то при загрузке объекты будут созданы в схеме с пустым ACL, а их владельцем станет пользователь, запустивший загрузку.
--dry-run: Режим проверки соответствия схемы данных в базе данных и файловой системе без внесения изменений в базу данных, 1 (да) или 0 (нет), по умолчанию 0. При включении данного режима проверяется, что:
- Все таблицы в файловой системе присутствуют в базе данных
- Схема данных объектов в файловой системе и базе данных одинаковая
--save-partial-result: Сохранять результат неполной загрузки. Без включения данной опции ошибка в процессе выполнения загрузки приведет к восстановлению состояния базы данных на момент перед началом загрузки.
--import-data: Использовать ImportData – более эффективный способ загрузки данных, чем применяется по умолчанию. Этот способ передает на сервер данные, нужным образом разделённые на партиции, и в более легковесном формате. Однако ImportData вернёт ошибку при попытке импорта таблицы, имеющей вторичные индексы или находящейся в процессе их построения, в существующую таблицу. Поэтому перед импортом таблицы со вторичными индексами необходимо убедиться в том, что они отсутствуют в схеме (например, используя команду ydb scheme ls). По умолчанию ImportData не используется.
Параметры ограничения нагрузки
Приведенные ниже параметры позволяют ограничить нагрузку на базу данных, создаваемую в процессе загрузки данных.
Важно
Некоторые из перечисленных ниже параметров имеют действующие значения по умолчанию . Это значит, что если даже ни один из них не задан в команде вызова tools restore, нагрузка все равно будет ограничена.
--rps VAL: Ограничение количества запросов на загрузку пакетов данных в базу данных в секунду, по умолчанию 30.
--bandwidth VAL: Ограничение объема загрузки в секунду, по умолчанию 0 (не установлено). VAL определяет объем, задается в виде числа с приставкой, например 2MiB. Если определено значение --bandwidth ограничение на --rps (см. выше) не применяется.
--in-flight VAL: Ограничения количество запросов, одновременно находящихся в состоянии исполнения, по умолчанию 10. Для достижения максимального параллелизма следует использовать значение, равное количеству ядер процессора, отведённых под операцию восстановления.
--upload-batch-rows VAL: Ограничение количества записей в пакете загружаемых данных, по умолчанию 0 (не ограничено). VAL определяет количество записей, задается в виде числа с необязательной десятичной приставкой, например 1K.
--upload-batch-bytes VAL: Ограничение объема пакета загружаемых данных, по умолчанию 512KB. VAL определяет объем, задается в виде числа с приставкой, например 1MiB. Максимальное значение — 16MiB.
--upload-batch-rus VAL: Применимо только для Serverless баз данных, ограничивает потребление Request Units (RU) на загрузку одного пакета, по умолчанию 30 RU. Размер пакета подбирается под указанное значение. VAL определяет количество RU, задается в виде числа с необязательной десятичной приставкой, например 100 или 1K.
Примеры
Примечание
В примерах используется профиль quickstart, подробнее смотрите в Создание профиля для соединения с тестовой БД.
Загрузка в корень базы данных
Из текущей директории файловой системы:
ydb -p quickstart tools restore -p . -i .
Из заданной директории файловой системы:
ydb -p quickstart tools restore -p . -i ~/backup_quickstart
Загрузка в заданную директорию в базе данных
Из текущей директории файловой системы:
ydb -p quickstart tools restore -p dir1/dir2 -i .
Из заданной директории файловой системы:
ydb -p quickstart tools restore -p dir1/dir2 -i ~/backup_quickstart
Проверка соответствия схемы данных в базе данных и файловой системе:
ydb -p quickstart tools restore -p dir1/dir2 -i ~/backup_quickstart --dry-run
Пример вызова команды для оптимизации скорости загрузки
ydb -p quickstart tools restore -p . -i . --import-data --bandwidth=10GiB --in-flight=16 --upload-batch-bytes=16MiB