Merge 179be64 into a6070b7

Author: jepett0

ydb/docs/en/core/reference/ydb-cli/export-import/_includes/file_structure.md

@@ -43,24 +43,33 @@ Each database directory has a corresponding directory in the file structure. Eac
 
 ## Tables {#tables}
 
-For each table in the database, there's a same-name directory in the file structure's directory hierarchy that includes:
+For each table in the database, there is a same-named directory in the file structure of the backup that includes:
 
 - The `scheme.pb` file describing the table structure and parameters in the [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format) format
-- The `permissions.pb` file describes the table ACL and owner in the [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format) format
+- The `permissions.pb` file specifying the table owner and ACL in the [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format) format
 - One or more `data_XX.csv` files with the table data in `csv` format, where `XX` is the file's sequence number. The export starts with the `data_00.csv` file, with a next file created whenever the current file exceeds 100 MB
 - Directories describing the [changefeeds](https://ydb.tech/docs/en/concepts/cdc). Directory names match the names of the changefeeds. Each directory contains the following files:
   - The `changefeed_description.pb` file describing the changefeed in the [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format) format
   - The `topic_description.pb` file describing the underlying topic in the [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format) format
 
 
-## Files with data {#datafiles}
+### Files with data {#datafiles}
 
 The format of data files is `.csv`, where each row corresponds to a record in the table (except the row with column headings). The urlencoded format is used for rows. For example, the file row for the table with the uint64 and utf8 columns that includes the number 1 and the Russian string "Привет" (translates to English as "Hi"), would look like this:
 
 ```text
 1,"%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82"
 ```
 
+## Views {#views}
+
+For each [view](../../../../concepts/datamodel/view.md) in the database, there is a same-named directory in the file structure of the backup that includes:
+
+- The `create_view.sql` file containing the view's definition in plain-text YQL format (as a [CREATE VIEW](../../../../yql/reference/syntax/create-view.md) query)
+- The `permissions.pb` file specifying the view owner and ACL in the [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format) format
+
+The relative positioning of views and the objects they reference is preserved during restoration. For more details, see the article [{#T}](../view-backup.md).
+
 ## Checksums {#checksums}
 
 {% note info %}

ydb/docs/en/core/reference/ydb-cli/export-import/toc_i.yaml

@@ -1,5 +1,5 @@
 items:
-- name: File structure of data export
+- name: File structure of an export
   href: file-structure.md
 - name: Exporting data to the file system
   href: tools-dump.md
@@ -12,4 +12,6 @@ items:
 - name: Importing data from S3
   href: import-s3.md
 - name: Importing data from a file to an existing table
-  href: import-file.md
+  href: import-file.md
+- name: Considerations for restoring views
+  href: view-backup.md

ydb/docs/en/core/reference/ydb-cli/export-import/view-backup.md

@@ -0,0 +1,139 @@
+# Considerations for restoring views from backups
+
+During the restoration of [views](../../../concepts/datamodel/view.md) from a backup, the system may automatically adjust the underlying query to ensure object references remain valid. Restored views will reference the restored tables rather than the previously existing tables in the target environment, preserving the relative positioning between views and their referenced objects as they existed at backup time.
+
+## Examples
+
+### Restoring the database root to the same path
+
+Let's consider the following scenario:
+
+1. A view is created using the following query:
+
+    ```sql
+    CREATE VIEW root_view WITH security_invoker = TRUE AS
+        SELECT * FROM root_table;
+    ```
+
+2. The database is backed up:
+
+    ```bash
+    ydb tools dump --path . --output ./my_backup
+    ```
+
+3. The database is cleared:
+
+    ```bash
+    ydb scheme rmdir --force --recursive .
+    ```
+
+4. The database is restored:
+
+    ```bash
+    ydb tools dump --path . --input ./my_backup
+    ```
+
+As the result of the steps described above, the `root_view` view is restored and selects from the `root_table` table:
+
+```bash
+ydb sql --script 'select * from root_view' --explain
+```
+
+The output of the command includes: `TableFullScan (Table: root_table, ...`
+
+### Restoring the database root to a subfolder
+
+Let's consider the following scenario:
+
+1. A view is created using the following query:
+
+    ```sql
+    CREATE VIEW my_view WITH security_invoker = TRUE AS
+        SELECT * FROM my_table;
+    ```
+
+2. The database is backed up:
+
+    ```bash
+    ydb tools dump --path . --output ./my_backup
+    ```
+
+3. The database is restored to the `a/b/c` subfolder:
+
+    ```bash
+    ydb tools restore --path a/b/c --input ./my_backup
+    ```
+
+As the result of the steps described above, the `a/b/c/my_view` view is restored and selects from the `a/b/c/my_table` table:
+
+```bash
+ydb sql --script 'select * from `a/b/c/my_view`' --explain
+```
+
+The output of the command includes: `TableFullScan (Table: a/b/c/my_table, ...`
+
+### Restoring a subfolder to the database root
+
+Let's consider the following scenario:
+
+1. The steps 1 to 3 of the previous scenario [{#T}](#restoring-the-database-root-to-a-subfolder) are repeated.
+2. The `a/b/c` subfolder of the database is backed up:
+
+    ```bash
+    ydb tools dump --path a/b/c --output ./subfolder_backup
+    ```
+
+3. The database is cleared:
+
+    ```bash
+    ydb scheme rmdir --force --recursive .
+    ```
+
+4. The subfolder backup is restored to the root of the database:
+
+    ```bash
+    ydb tools restore --path . --input ./subfolder_backup
+    ```
+
+As the result of the steps described above, the `my_view` view is restored and selects from the `my_table` table:
+
+```bash
+ydb sql --script 'select * from my_view' --explain
+```
+
+The output of the command includes: `TableFullScan (Table: my_table, ...`
+
+### Restoring the database root to the root of a different database
+
+Let's consider the following scenario:
+
+1. A view is created using the following query:
+
+    ```sql
+    CREATE VIEW root_view WITH security_invoker = TRUE AS
+        SELECT * FROM root_table;
+    ```
+
+2. The database is backed up:
+
+    ```bash
+    ydb --endpoint <endpoint> --database /my_database tools dump --path . --output ./my_backup
+    ```
+
+    Note the `--database /my_database` option in the connection string.
+
+3. The database backup is restored to a different database:
+
+    ```bash
+    ydb --endpoint <endpoint> --database /restored_database tools dump --path . --input ./my_backup
+    ```
+
+    Note the `--database /restored_database` option in the connection string.
+
+As the result of the steps described above, the `root_view` view is restored and selects from the `root_table` table located in the `/restored_database`:
+
+```bash
+ydb --endpoint <endpoint> --database /restored_database sql --script 'select * from root_view' --explain
+```
+
+The output of the command includes: `TableFullScan (Table: root_table, ...`

ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/file-structure.md

@@ -43,7 +43,7 @@
 
 ## Таблицы {#tables}
 
-Каждой таблице в базе данных также соответствует одноименная директория в иерархии директорий файловой структуры, в которой находятся:
+Каждой таблице в базе данных соответствует одноимённая директория в файловой структуре, в которой находятся:
 
 - Файл `scheme.pb`, содержащий информацию о структуре таблицы и её параметрах в формате [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format)
 - Файл `permissions.pb`, содержащий информацию об ACL таблицы и её владельце в формате [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format)
@@ -52,14 +52,23 @@
   - Файл `changefeed_description.pb`, содержащий информацию о потоке изменений в формате [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format)
   - Файл `topic_description.pb`, содержащий информацию о нижележащем топике в формате [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format)
 
-## Файлы с данными {#datafiles}
+### Файлы с данными {#datafiles}
 
 Формат файлов с данными - `.csv`, одна строка соответствует одной записи в таблице, без строки с заголовками колонок. Для строк применяется  представление в urlencoded формате. Например, строка файла для таблицы с колонками uint64 и utf8, содержащая число 1 и строку "Привет" соответственно, выглядит таким образом:
 
 ```text
 1,"%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82"
 ```
 
+## Представления (views) {#views}
+
+Каждому [представлению](../../../../concepts/datamodel/view.md) в базе данных соответствует одноимённая директория в файловой структуре, в которой находятся:
+
+- Файл `create_view.sql`, содержащий определение представления в виде текста YQL-запроса [CREATE VIEW](../../../../yql/reference/syntax/create-view.md)
+- Файл `permissions.pb`, содержащий информацию об ACL представления и его владельце в формате [text protobuf](https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.text_format)
+
+Взаимное расположение представлений и объектов, на которые они ссылаются, сохраняется при восстановлении. Подробнее читайте в статье [{#T}](../view-backup.md).
+
 ## Контрольные суммы {#checksums}
 
 {% note info %}

ydb/docs/ru/core/reference/ydb-cli/export-import/toc_i.yaml

@@ -13,3 +13,5 @@ items:
   href: import-s3.md
 - name: Импорт данных из файла в существующую таблицу
   href: import-file.md
+- name: Особенности восстановления представлений
+  href: view-backup.md

ydb/docs/ru/core/reference/ydb-cli/export-import/view-backup.md

@@ -0,0 +1,139 @@
+# Особенности восстановления представлений из резервных копий
+
+При восстановлении [представлений](../../../concepts/datamodel/view.md) из резервной копии запрос представления может быть автоматически изменён для сохранения корректности ссылок на объекты схемы. Восстановленные из резервной копии представления будут ссылаться на восстановленные таблицы, а не на ранее существовавшие в целевой базе таблицы. Взаимное расположение представлений и объектов, на которые они ссылаются, сохраняется таким, каким оно было во время создания резервной копии.
+
+## Примеры
+
+### Восстановление корня базы данных по тому же пути {#example-root-root}
+
+Рассмотрим следующий сценарий:
+
+1. Создаётся представление:
+
+    ```sql
+    CREATE VIEW root_view WITH security_invoker = TRUE AS
+        SELECT * FROM root_table;
+    ```
+
+2. Создаётся резервная копия базы:
+
+    ```bash
+    ydb tools dump --path . --output ./my_backup
+    ```
+
+3. Выполняется очистка базы данных:
+
+    ```bash
+    ydb scheme rmdir --force --recursive .
+    ```
+
+4. База данных восстанавливается:
+
+    ```bash
+    ydb tools dump --path . --input ./my_backup
+    ```
+
+В результате описанных выше шагов представление `root_view` восстанавливается и читает из таблицы `root_table`:
+
+```bash
+ydb sql --script 'select * from root_view' --explain
+```
+
+В выводе выполненной команды отображается: `TableFullScan (Table: root_table, ...`
+
+### Восстановление корня базы данных в подпапку {#example-root-subfolder}
+
+Рассмотрим следующий сценарий:
+
+1. Создаётся представление:
+
+    ```sql
+    CREATE VIEW my_view WITH security_invoker = TRUE AS
+        SELECT * FROM my_table;
+    ```
+
+2. Создаётся резервная копия базы:
+
+    ```bash
+    ydb tools dump --path . --output ./my_backup
+    ```
+
+3. База данных восстанавливается в подпапку `a/b/c`:
+
+    ```bash
+    ydb tools restore --path a/b/c --input ./my_backup
+    ```
+
+В результате описанных выше шагов представление `a/b/c/my_view` восстанавливается и читает из таблицы `a/b/c/my_table`:
+
+```bash
+ydb sql --script 'select * from `a/b/c/my_view`' --explain
+```
+
+В выводе выполненной команды отображается: `TableFullScan (Table: a/b/c/my_table, ...`
+
+### Восстановление подпапки в корень базы данных {#example-subfolder-root}
+
+Рассмотрим следующий сценарий:
+
+1. Повторяются шаги 1-3 предыдущего сценария [{#T}](#example-root-subfolder).
+2. Создаётся резервная копия подпапки `a/b/c` базы данных:
+
+    ```bash
+    ydb tools dump --path a/b/c --output ./subfolder_backup
+    ```
+
+3. Выполняется очистка базы данных:
+
+    ```bash
+    ydb scheme rmdir --force --recursive .
+    ```
+
+4. Резервная копия подпапки восстанавливается в корень базы данных:
+
+    ```bash
+    ydb tools restore --path . --input ./subfolder_backup
+    ```
+
+В результате описанных выше шагов представление `my_view` восстанавливается и читает из таблицы `my_table`:
+
+```bash
+ydb sql --script 'select * from my_view' --explain
+```
+
+В выводе выполненной команды отображается: `TableFullScan (Table: my_table, ...`
+
+### Восстановление корня базы данных в корень другой базы данных {#example-root-different-root}
+
+Рассмотрим следующий сценарий:
+
+1. Создаётся представление:
+
+    ```sql
+    CREATE VIEW root_view WITH security_invoker = TRUE AS
+        SELECT * FROM root_table;
+    ```
+
+2. Создаётся резервная копия базы:
+
+    ```bash
+    ydb --endpoint <endpoint> --database /my_database tools dump --path . --output ./my_backup
+    ```
+
+    Обратите внимание на `--database /my_database` в строке подключения.
+
+3. Резервная копия базы данных восстанавливается в другую базу данных:
+
+    ```bash
+    ydb --endpoint <endpoint> --database /restored_database tools dump --path . --input ./my_backup
+    ```
+
+    Обратите внимание на `--database /restored_database` в строке подключения.
+
+В результате описанных выше шагов представление `root_view` восстанавливается и читает из таблицы `root_table`, расположенной в `/restored_database`:
+
+```bash
+ydb --endpoint <endpoint> --database /restored_database sql --script 'select * from root_view' --explain
+```
+
+В выводе выполненной команды отображается: `TableFullScan (Table: root_table, ...`