---
metadata:
  - name: generator
    content: Diplodoc Platform v5.59.0
alternate:
  - https://ydb.tech/docs/en/reference/ydb-cli/export-import/import-nfs.md
  - https://ydb.tech/docs/ru/reference/ydb-cli/export-import/import-nfs.md
  - href: https://ydb.tech/docs/ru/reference/ydb-cli/export-import/import-nfs.md
    type: text/markdown
    title: Markdown version
  - href: https://ydb.tech/docs/ru/llms.txt
    rel: describedby
sourcePath: ru/core/reference/ydb-cli/export-import/import-nfs.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt

# Загрузка из NFS

Команда `import nfs` запускает на стороне сервера процесс загрузки из сетевой файловой системы ([Network File System](https://ru.wikipedia.org/wiki/Network_File_System), NFS) хостов кластера YDB данных и информации об объектах схемы, в описанном в статье [Файловая структура](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/file-structure.md) формате:

```bash
ydb [connection options] import nfs [options]
```

<!-- source: ru/reference/ydb-cli/commands/_includes/conn_options_ref.md -->
, где `[connection options]` — опции [соединения с БД](https://ydb.tech/docs/ru/reference/ydb-cli/connect.md#command-line-pars)
<!-- endsource: ru/reference/ydb-cli/commands/_includes/conn_options_ref.md -->

В отличие от [команды `tools restore`](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/tools-restore.md), команда `import nfs` всегда создает объекты целиком, поэтому для её успешного выполнения ни один из загружаемых объектов (ни директорий, ни таблиц) не должен существовать.

При необходимости догрузки данных в существующие таблицы воспользуйтесь [командой `tools restore`](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/tools-restore.md) непосредственно на смонтированной NFS-директории.

## Параметры командной строки {#pars}

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

### Параметры NFS {#nfs-params}

Команда загрузки из NFS требует указания монтированной директории (или поддиректории) общей для всех объектов, участвующих в загрузке. Так как загрузка производится в асинхронном режиме на всех хостах YDB, указанная директория должна быть на каждом хосте YDB и смонтирована в NFS.

`--fs-path PATH`: путь до монтированной директории (или поддиректории).

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

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-objects-params.md -->
`--destination-path PATH`: Целевая директория для загружаемых объектов; значением по умолчанию является корень базы данных.

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

`--exclude STRING`: Шаблон ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) для исключения путей из импорта. Данный параметр может быть указан несколько раз для разных шаблонов.
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-objects-params.md -->

{% cut "Альтернативный способ" %}

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-alternative-syntax.md -->
В целях обратной совместимости поддерживается альтернативный способ указания перечня объектов:

`--item STRING`: Описание объекта загрузки. Параметр `--item` может быть указан несколько раз, если необходимо выполнить загрузку нескольких объектов. Если параметры `--item` или `--include` не указаны, будут загружены все объекты, присутствующие в указанной выгрузке. `STRING` задаётся в формате `<свойство>=<значение>,...` со следующими обязательными свойствами:
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-alternative-syntax.md -->

- `source`, `src` или `s` — путь в NFS (относительно `fs-path`) с загружаемой директорией или таблицей.
- `destination`, `dst`, или `d` —  путь в базе данных для размещения загружаемой директории или таблицы. Конечный элемент пути не должен существовать. Все директории на пути будут созданы, если не существуют.

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-alternative-syntax-warning.md -->
Некоторые возможности могут быть недоступны при использовании альтернативного синтаксиса (в частности, шифрованные резервные копии или перечисление объектов выгрузки).
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-alternative-syntax-warning.md -->

{% endcut %}

### Дополнительные параметры {#aux}

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-additional-params.md -->
- `--description STRING`: Текстовое описание операции, сохраняемое в истории операций.
- `--retries NUM`: Количество повторных попыток загрузки, которые будет предпринимать сервер. Значение по умолчанию: `10`.
- `--skip-checksum-validation`: Пропустить этап валидации [контрольных сумм](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/file-structure.md#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).
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-additional-params.md -->

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-resource-broker-note.md -->
{% note info %}

Использование режима `--index-population-mode=import` позволяет максимально задействовать ресурсы и быстро восстановить индексы, либо наоборот — ограничить ресурсы и скопировать индексные таблицы с минимальным влиянием на пользовательскую нагрузку. Для ограничения ресурсов импорта используется [очередь `queue_restore`](https://ydb.tech/docs/ru/reference/configuration/resource_broker_config.md) брокера ресурсов.

{% endnote %}
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-resource-broker-note.md -->

## Выполнение загрузки {#exec}

<!-- source: ru/reference/ydb-cli/export-import/_includes/server-import-workflow.md -->
### Ход серверной операции загрузки {#server-import-workflow}

1. Создаётся серверная асинхронная операция импорта.
2. Сервер считывает метаданные объектов из файлов (`scheme.pb`, `metadata.json` и т.д.) из хранилища.
3. Для каждого объекта создаётся новая таблица в базе данных. Целевые пути **не должны существовать** — импорт не может перезаписать существующие таблицы.
4. Данные загружаются из файлов параллельно на всех узлах кластера.
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/server-import-workflow.md -->

### Результат запуска {#result}

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

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-operation-result-pretty-intro.md -->
- В режиме вывода `pretty` (по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id:
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-operation-result-pretty-intro.md -->

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

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-operation-result-json-intro.md -->
- В режиме вывода `proto-json-base64` идентификатор находится в атрибуте "id":
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-operation-result-json-intro.md -->

  ```json
  {"id":"ydb://import/8?id=281474976788395&kind=fs","ready":true, ... }
  ```

### Статус загрузки {#status}

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-operation-status-intro.md -->
Загрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе загрузки можно вызовом команды `operation get`, параметром которой должен быть передан **заключенный в кавычки** идентификатор операции, например:
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-operation-status-intro.md -->

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

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-operation-status-after-get.md -->
Формат вывода `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",... }
  ```
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-operation-status-after-get.md -->

### Завершение операции загрузки {#forget}

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-operation-forget-intro.md -->
После выполнения загрузки воспользуйтесь командой `operation forget` для того, чтобы загрузка была удалена из перечня операций:
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-operation-forget-intro.md -->

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

### Список операций загрузки {#list}

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

```bash
ydb -p quickstart operation list import/nfs
```

<!-- source: ru/reference/ydb-cli/export-import/_includes/import-operation-list-tail.md -->
Формат вывода `operation list` также устанавливается опцией `--format`.
<!-- endsource: ru/reference/ydb-cli/export-import/_includes/import-operation-list-tail.md -->

## Примеры {#examples}

<!-- source: ru/_includes/ydb-cli-profile.md -->
{% note info %}

В примерах используется профиль `quickstart`, подробнее смотрите в [Создание профиля для соединения с тестовой БД](https://ydb.tech/docs/ru/reference/ydb-cli/profile/create.md#quickstart).

{% endnote %}
<!-- endsource: ru/_includes/ydb-cli-profile.md -->

### Загрузка в корень базы данных {#example-full-db}

Загрузка в корень базы данных содержимого директории `/mnt/nfs/backups/export1` на файловой системе:

```bash
ydb -p quickstart import nfs \
  --fs-path /mnt/nfs/backups/export1
```

### Загрузка нескольких директорий {#example-specific-dirs}

Загрузка объектов из директорий `dir1` и `dir2` выгрузки, расположенной в `/mnt/nfs/backups/export1` на файловой системе, в одноименные директории базы данных:

```bash
ydb -p quickstart import nfs \
  --fs-path /mnt/nfs/backups/export1 \
  --include dir1 --include dir2
```

### Загрузка зашифрованной выгрузки {#example-encryption}

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

```bash
ydb -p quickstart import nfs \
  --fs-path /mnt/nfs/backups/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/nfs --format proto-json-base64 | jq -r ".operations[].id"
```

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

```text
ydb://import/8?id=281474976789577&kind=fs
ydb://import/8?id=281474976789526&kind=fs
ydb://import/8?id=281474976788779&kind=fs
```

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

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