Перевод новых функций YDB CLI v. 1.9

5 files changed, 228 insertions, 158 deletions

diff --git a/ydb/docs/en/core/changelog.md b/ydb/docs/en/core/changelog.md
new file mode 100644
index 00000000000..ac3b2333dc3
--- /dev/null
+++ b/ydb/docs/en/core/changelog.md
@@ -0,0 +1,8 @@
+# Releases

+

+## 25.06.2022 {#25-06-2022}

+

+{{ ydb-short-name }} CLI 1.9.1:

+

+* Added the ability to compress data when exporting it to S3-compatible storage (see the `--compression` parameter of the [ydb export s3](reference/ydb-cli/export_import/s3_export.md) command).

+* Added the ability to manage new {{ ydb-short-name }} CLI version availability auto checks (see the `--disable-checks` and `--enable-checks` parameters of the [ydb version](reference/ydb-cli/version.md) command).
\ No newline at end of file
diff --git a/ydb/docs/en/core/reference/ydb-cli/export_import/_includes/s3_export.md b/ydb/docs/en/core/reference/ydb-cli/export_import/_includes/s3_export.md
index 3651e7e986c..7574f4a7788 100644
--- a/ydb/docs/en/core/reference/ydb-cli/export_import/_includes/s3_export.md
+++ b/ydb/docs/en/core/reference/ydb-cli/export_import/_includes/s3_export.md
@@ -1,158 +1,157 @@
-# Exporting data to S3-compatible storage
-
-Running the `export s3` command starts, on the server side, exporting data and information about data schema objects to S3-compatible storage in the format described in the [File structure](../file_structure.md) article:
-
-```bash
-{{ ydb-cli }} [connection options] export s3 [options]
-```
-
-{% include [conn_options_ref.md](../../commands/_includes/conn_options_ref.md) %}
-
-## Command line parameters {#pars}
-
-`[options]`: Command parameters:
-
-### S3 connection parameters {#s3-conn}
-
-To run the command to export data to S3, make sure to specify the [S3 connection parameters](../s3_conn.md). Since data export is performed asynchronously by the YDB server, the specified endpoint must be available to establish a server-side connection.
-
-### List of exported objects {#items}
-
-`--item STRING`: Description of the object to export. The `--item` parameter can be specified several times if you need to export multiple objects. The `STRING` format is `<property>=<value>,...`, with the following properties required:
-
-- `source`, `src`, or `s`: Path to the directory or table to be exported, where `.` indicates the DB root directory. In the specified directory, the following are exported: any objects whose names do not begin with a dot and, recursively, any subdirectories whose names do not begin with a dot.
-- `destination`, `dst`, or `d`: Path to S3 (key prefix) to store the exported objects to.
-
-`--exclude STRING`: Pattern ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) for excluding paths from the export destination. This parameter can be specified several times for different patterns.
-
-### Additional parameters {#aux}
-
-`--description STRING`: Operation text description stored in the history of operations. `--retries NUM`: Number of import retries the server will make. Defaults to 10.
-`--format STRING`: Result output format.
-
-- `pretty`: Human-readable format (default).
-- `proto-json-base64`: Protobuf that supports JSON values encoded as binary strings using base64 encoding.
-
-## Exporting data {#exec}
-
-### Export result {#result}
-
-If successful , the `export s3` command outputs summary information about the enqueued operation for exporting data to S3 in the format specified in the `--format` option. The actual export operation is performed by the server asynchronously. The summary displays the operation ID that can be used later to check the status and actions with the operation:
-
-- In the `pretty` output mode used by default, the operation identifier is output in the id field with semigraphics formatting:
-
-  ```
-  ┌───────────────────────────────────────────┬───────┬─────...
-  | id                                        | ready | stat...
-  ├───────────────────────────────────────────┼───────┼─────...
-  | ydb://export/6?id=281474976788395&kind=s3 | true  | SUCC...
-  ├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴...
-  | StorageClass: NOT_SET                                      
-  | Items:
-  ...                                                   
-  ```
-
-- In proto-json-base64 output mode, the ID is in the "id" attribute:
-
-  ```
-  {"id":"ydb://export/6?id=281474976788395&kind=s3","ready":true, ... }
-  ```
-
-### Export status {#status}
-
-Data is exported in the background. You can get information about the status and progress of the export operation by running the `operation get` command with the **quoted** operation ID passed as the command parameter. For example:
-
-```bash
-{{ ydb-cli }} -p db1 operation get "ydb://export/6?id=281474976788395&kind=s3"
-```
-
-The format of the `operation get` command output is also specified in the `--format` option.
-
-Although the operation ID format is URL, there is no guarantee that it's retained later. It should only be interpreted as a string.
-
-You can track the completion of the export operation by changes in the "progress" attribute:
-
-- In the `pretty` output mode used by default, a successful operation is indicated by the "Done" value in the `progress` field with semigraphics formatting:
-
-  ```
-  ┌───── ... ──┬───────┬─────────┬──────────┬─...
-  | id         | ready | status  | progress | ...
-  ├──────... ──┼───────┼─────────┼──────────┼─...
-  | ydb:/...   | true  | SUCCESS | Done     | ...
-  ├╴╴╴╴╴ ... ╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴╴┴╴...
-  ...
-  ```
-
-- In proto-json-base64 output mode, a completed operation is indicated by the `PROGRESS_DONE` value of the `progress` attribute:
-
-  ```
-  {"id":"ydb://...", ...,"progress":"PROGRESS_DONE",... }
-  ```
-
-### Ending the export operation {#forget}
-
-When exporting data, a directory named `export_*` is created in the DB root directory, where `*` is the numeric part of the export ID. This directory stores tables containing a consistent snapshot of the exported data as of the start of the export operation.
-
-Once the data is exported, use the `operation forget` command to make sure the export operation is ended, that is, removed from the list of operations along with deleting all the files created for it:
-
-```bash
-{{ ydb-cli }} -p db1 operation forget "ydb://export/6?id=281474976788395&kind=s3"
-```
-
-### List of export operations {#list}
-
-To get a list of export operations, run the `operation list export/s3` command:
-
-```bash
-{{ ydb-cli }} -p db1 operation list export/s3
-```
-
-The format of the `operation list` command output is also specified in the `--format` option.
-
-## Examples {#examples}
-
-{% include [example_db1.md](../../_includes/example_db1.md) %}
-
-### Exporting a database {#example-full-db}
-
-Exporting all DB objects whose names do not begin with a dot and are not placed inside directories whose names begin with a dot to the `export1` directory in the `mybucket` bucket, using S3 authentication parameters from environment variables or the `~/.aws/credentials` file:
-
-```
-ydb -p db1 export s3 \
-  --s3-endpoint storage.yandexcloud.net --bucket mybucket \
-  --item src=.,dst=export1
-```
-
-### Exporting multiple directories {#example-specific-dirs}
-
-Exporting objects from DB directories named dir1 and dir2 to the `export1` directory in the `mybucket` bucket using explicitly specified S3 authentication parameters:
-
-```
-ydb -p db1 export s3 \
-  --s3-endpoint storage.yandexcloud.net --bucket mybucket \
-  --access-key VJGSOScgs-5kDGeo2hO9 --secret-key fZ_VB1Wi5-fdKSqH6074a7w0J4X0 \
-  --item src=dir1,dst=export1/dir1 --item src=dir2,dst=export1/dir2
-```
-
-### Getting operation IDs {#example-list-oneline}
-
-To get a list of export operation IDs in a format that is convenient for processing in bash scripts, use [jq](https://stedolan.github.io/jq/download/):
-
-```bash
-{{ ydb-cli }} -p db1 operation list export/s3 --format proto-json-base64 | jq -r ".operations[].id"
-```
-
-You'll get an output where each new line contains the operation ID. For example:
-
-```
-ydb://export/6?id=281474976789577&kind=s3
-ydb://export/6?id=281474976789526&kind=s3
-ydb://export/6?id=281474976788779&kind=s3
-```
-
-These IDs can be used, for example, to run a loop that will end all current operations:
-
-```bash
-{{ ydb-cli }} -p db1 operation list export/s3 --format proto-json-base64 | jq -r ".operations[].id" | while read line; do {{ ydb-cli }} -p db1 operation forget $line;done
-```
-
+# Exporting data to S3-compatible storage

+

+The `export s3` command starts exporting data and information on the server side about data schema objects to S3-compatible storage, in the format described under [File structure](../file_structure.md):

+

+```bash

+{{ ydb-cli }} [connection options] export s3 [options]

+```

+

+{% include [conn_options_ref.md](../../commands/_includes/conn_options_ref.md) %}

+

+## Command line parameters {#pars}

+

+`[options]`: Command parameters:

+

+### S3 connection parameters {#s3-conn}

+

+To run the command to export data to S3 storage, specify the [S3 connection parameters](../s3_conn.md). Since data is exported by the YDB server asynchronously, the specified endpoint must be available to establish a connection on the server side.

+

+### List of exported items {#items}

+

+`--item STRING`: Description of the item to export. You can specify the `--item` parameter multiple times if you need to export multiple items. `STRING` is set in `<property>=<value>,...` format with the following mandatory properties:

+- `source`, `src`, or `s`: Path to the exported directory or table, `.` indicates the DB root directory. If you specify a directory, all of its items whose names do not start with a dot and, recursively, all subdirectories whose names do not start with a dot are exported.

+- `destination`, `dst`, or `d`: Path (key prefix) in S3 storage to store exported items.

+

+`--exclude STRING`: Template ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) to exclude paths from export. Specify this parameter multiple times for different templates.

+

+### Additional parameters {#aux}

+

+| Parameter | Description |

+--- | ---

+| `--description STRING` | Operation text description saved to the history of operations. |

+| `--retries NUM` | Number of export retries to be made by the server.</br>Defaults to `10`. |

+| `--compression STRING` | Compress exported data.</br>If the default compression level is used for the [Zstandard](https://en.wikipedia.org/wiki/Zstd) algorithm, data can be compressed by 5-10 times. Compressing data uses the CPU and may affect the speed of performing other DB operations.</br>Possible values:</br><ul><li>`zstd`: Compression using the Zstandard algorithm with the default compression level (`3`).</li><li>`zstd-N`: Compression using the Zstandard algorithm, where `N` stands for the compression level (`1` — `22`).</li></ul> |

+| `--format STRING` | Result format.</br>Possible values:</br><ul><li>`pretty`: Human-readable format (default).</li><li>`proto-json-base64`: [Protocol Buffers](https://en.wikipedia.org/wiki/Protocol_Buffers) in [JSON](https://en.wikipedia.org/wiki/JSON) format, binary strings are [Base64](https://en.wikipedia.org/wiki/Base64)-encoded.</li></ul> |

+

+## Running the export command {#exec}

+

+### Export result {#result}

+

+If successful, the `export s3` command outputs summary information about the enqueued operation to export data to S3, in the format specified in the `--format` option. The export itself is performed by the server asynchronously. The output summary shows the operation ID that you can use later to check the operation status and perform actions on it:

+

+- In the default `pretty` output mode, the operation ID is displayed in the id field with semigraphics formatting:

+

+   ```

+   ┌───────────────────────────────────────────┬───────┬─────...

+   | id                                        | ready | stat...

+   ├───────────────────────────────────────────┼───────┼─────...

+   | ydb://export/6?id=281474976788395&kind=s3 | true  | SUCC...

+   ├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴...

+   | StorageClass: NOT_SET                                      

+   | Items:

+   ...                                                   

+   ```

+

+- In the proto-json-base64 output mode, the operation ID is in the "id" attribute:

+

+   ```

+   {"id":"ydb://export/6?id=281474976788395&kind=s3","ready":true, ... }

+   ```

+

+### Export status {#status}

+

+Data is exported in the background. To find out the export status and progress, use the `operation get` command with the operation ID **enclosed in quotation marks** and passed as a command parameter. For example:

+

+```bash

+{{ ydb-cli }} -p db1 operation get "ydb://export/6?id=281474976788395&kind=s3"

+```

+

+The `operation get` output format is also set by the `--format` option.

+

+Although the operation ID is in URL format, there is no guarantee that it is maintained in the future. It should only be interpreted as a string.

+

+You can track the export progress by changes in the "progress" attribute:

+

+- In the default `pretty` output mode, an export operation that completed successfully is displayed as "Done" in the `progress` field with semigraphics formatting:

+

+   ```

+   ┌───── ... ──┬───────┬─────────┬──────────┬─...

+   | id         | ready | status  | progress | ...

+   ├──────... ──┼───────┼─────────┼──────────┼─...

+   | ydb:/...   | true  | SUCCESS | Done     | ...

+   ├╴╴╴╴╴ ... ╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴╴┴╴...

+   ...

+   ```

+

+- In the proto-json-base64 output mode, the completed export operation is indicated with the `PROGRESS_DONE` value of the `progress` attribute:

+

+   ```

+   {"id":"ydb://...", ...,"progress":"PROGRESS_DONE",... }

+   ```

+

+### Completing the export operation {#forget}

+

+When running the export operation, a directory named `export_*` is created in the root directory, where `*` is the numeric part of the export ID. This directory stores tables with a consistent snapshot of exported data as of the export start time.

+

+Once the export is done, use the `operation forget` command to make sure the export is completed: the operation is removed from the list of operations and all files created for it are deleted:

+

+```bash

+{{ ydb-cli }} -p db1 operation forget "ydb://export/6?id=281474976788395&kind=s3"

+```

+

+### List of export operations {#list}

+

+To get a list of export operations, run the `operation list export/s3` command:

+

+```bash

+{{ ydb-cli }} -p db1 operation list export/s3

+```

+

+The `operation list` output format is also set by the `--format` option.

+

+## Examples {#examples}

+

+{% include [example_db1.md](../../_includes/example_db1.md) %}

+

+### Exporting a database {#example-full-db}

+

+Exporting all DB objects whose names do not start with a dot and that are not stored in directories whose names start with a dot to the `export1` directory in `mybucket` using the S3 authentication parameters from environment variables or the `~/.aws/credentials` file:

+

+```

+ydb -p db1 export s3 \

+  --s3-endpoint storage.yandexcloud.net --bucket mybucket \

+  --item src=.,dst=export1

+```

+

+### Exporting multiple directories {#example-specific-dirs}

+

+Exporting items from DB directories named dir1 and dir2 to the `export1` directory in `mybucket` using the explicitly set S3 authentication parameters:

+

+```

+ydb -p db1 export s3 \

+  --s3-endpoint storage.yandexcloud.net --bucket mybucket \

+  --access-key VJGSOScgs-5kDGeo2hO9 --secret-key fZ_VB1Wi5-fdKSqH6074a7w0J4X0 \

+  --item src=dir1,dst=export1/dir1 --item src=dir2,dst=export1/dir2

+```

+

+### Getting operation IDs {#example-list-oneline}

+

+To get a list of export operation IDs in a format suitable for handling in bash scripts, use the [jq](https://stedolan.github.io/jq/download/) utility:

+

+```bash

+{{ ydb-cli }} -p db1 operation list export/s3 --format proto-json-base64 | jq -r ".operations[].id"

+```

+

+You'll get an output where each new line shows an operation's ID. For example:

+

+```

+ydb://export/6?id=281474976789577&kind=s3

+ydb://export/6?id=281474976789526&kind=s3

+ydb://export/6?id=281474976788779&kind=s3

+```

+

+You can use these IDs, for example, to run a loop to end all the current operations:

+

+```bash

+{{ ydb-cli }} -p db1 operation list export/s3 --format proto-json-base64 | jq -r ".operations[].id" | while read line; do {{ ydb-cli }} -p db1 operation forget $line;done

+```

diff --git a/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
index 3711ef8244b..93b858516a1 100644
--- a/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
@@ -49,6 +49,8 @@ items:
       href: commands/discovery-list.md
     - name: Authentication
       href: commands/discovery-whoami.md
+    - name: YDB CLI version output
+      href: version.md
   - name: Load testing
     items:
     - name: Overview
diff --git a/ydb/docs/en/core/reference/ydb-cli/version.md b/ydb/docs/en/core/reference/ydb-cli/version.md
new file mode 100644
index 00000000000..699db4a3f2d
--- /dev/null
+++ b/ydb/docs/en/core/reference/ydb-cli/version.md
@@ -0,0 +1,59 @@
+# Getting {{ ydb-short-name }} CLI version

+

+Use the `version` subcommand to find out the version of the {{ ydb-short-name }} CLI installed and manage new version availability auto checks.

+

+New version availability auto checks are made when you run any {{ ydb-short-name }} CLI command, except `ydb version --enable-checks` and `ydb version --disable-checks`, but only once in 24 hours. The result and time of the last check are saved to the {{ ydb-short-name }} CLI configuration file.

+

+General format of the command:

+

+```bash

+{{ ydb-cli }} [global options...] version [options...]

+```

+

+* `global options`: [Global parameters](commands/global-options.md).

+* `options`: [Parameters of the subcommand](#options).

+

+View a description of the command:

+

+```bash

+{{ ydb-cli }} version --help

+```

+

+## Parameters of the subcommand {#options}

+

+| Parameter | Description |

+---|---

+| `--semantic` | Get only the version number. |

+| `--check` | Check if a new version is available. |

+| `--disable-checks` | Disable new version availability checks. |

+| `--enable-checks` | Enable new version availability checks. |

+

+## Examples {#examples}

+

+### Disable new version availability checks {#disable-checks}

+

+When running {{ ydb-short-name }} CLI commands, the system automatically checks if a new version is available. If the host where the command is run doesn't have internet access, this causes a delay and the corresponding warning appears during command execution. To disable auto checks for updates, run:

+

+```bash

+{{ ydb-cli }} version --disable-checks

+```

+

+Result:

+

+```text

+Latest version checks disabled

+```

+

+### Getting only the version number {#semantic}

+

+To facilitate data handling in scripts, you can limit result to the {{ ydb-short-name }} CLI version number:

+

+```bash

+{{ ydb-cli }} version --semantic

+```

+

+Result:

+

+```text

+1.9.1

+```

diff --git a/ydb/docs/en/core/toc_i.yaml b/ydb/docs/en/core/toc_i.yaml
index 4726271448a..1b7b87de71a 100644
--- a/ydb/docs/en/core/toc_i.yaml
+++ b/ydb/docs/en/core/toc_i.yaml
@@ -27,3 +27,5 @@ items:
 - include: { mode: link, path: downloads/toc_p.yaml }
 - name: Public talks
   href: public-talks.md
+- name: Revision history
+  href: changelog.md
\ No newline at end of file