From 4b526bf954b701b79ed292d41a532a9b5c4f55a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9E=D0=BB=D0=B5=D0=B3?= <150132506+iddqdex@users.noreply.github.com> Date: Thu, 28 Dec 2023 11:36:49 +0300 Subject: [PATCH] YDBDOCS-559 add parquet format to docs (#761) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * YDBDOCS-559 Refactoring. Lists now formated by markdown instead html. Use include for deduplicate text. * YDBDOCS-559 add parquet format to docs * YDBDOCS-559 Добавил описание формата parquet в документацию * fix typo --- .../ydb-cli/_includes/result_format_common.md | 5 +++ .../_includes/result_format_csv_tsv.md | 2 + .../core/reference/ydb-cli/scripting-yql.md | 30 +++++++++----- .../reference/ydb-cli/table-query-execute.md | 40 ++++++++++++++----- ydb/docs/en/core/reference/ydb-cli/yql.md | 28 +++++++++---- .../ydb-cli/_includes/result_format_common.md | 6 +++ .../_includes/result_format_csv_tsv.md | 2 + .../core/reference/ydb-cli/scripting-yql.md | 31 +++++++++----- .../reference/ydb-cli/table-query-execute.md | 39 +++++++++++++----- ydb/docs/ru/core/reference/ydb-cli/yql.md | 27 +++++++++---- 10 files changed, 155 insertions(+), 55 deletions(-) create mode 100644 ydb/docs/en/core/reference/ydb-cli/_includes/result_format_common.md create mode 100644 ydb/docs/en/core/reference/ydb-cli/_includes/result_format_csv_tsv.md create mode 100644 ydb/docs/ru/core/reference/ydb-cli/_includes/result_format_common.md create mode 100644 ydb/docs/ru/core/reference/ydb-cli/_includes/result_format_csv_tsv.md diff --git a/ydb/docs/en/core/reference/ydb-cli/_includes/result_format_common.md b/ydb/docs/en/core/reference/ydb-cli/_includes/result_format_common.md new file mode 100644 index 000000000000..1e333f56dc99 --- /dev/null +++ b/ydb/docs/en/core/reference/ydb-cli/_includes/result_format_common.md @@ -0,0 +1,5 @@ +* `pretty` (default): Human-readable format. +* `json-unicode`: [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} output with binary strings [Unicode]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}-encoded and each JSON string in a separate line. +* `json-unicode-array`: JSON output with binary strings Unicode-encoded and the result output as an array of JSON strings with each JSON string in a separate line.
  • `json-base64`: JSON output with binary strings [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}-encoded and each JSON string in a separate line. +* `json-base64-array`: JSON output with binary strings Base64-encoded and the result output as an array of JSON strings with each JSON string in a separate line; +* `parquet`: Output in [Apache Parquet](https://parquet.apache.org/docs/) format. \ No newline at end of file diff --git a/ydb/docs/en/core/reference/ydb-cli/_includes/result_format_csv_tsv.md b/ydb/docs/en/core/reference/ydb-cli/_includes/result_format_csv_tsv.md new file mode 100644 index 000000000000..250c9b504061 --- /dev/null +++ b/ydb/docs/en/core/reference/ydb-cli/_includes/result_format_csv_tsv.md @@ -0,0 +1,2 @@ +* `csv`: Output in [CSV](https://ru.wikipedia.org/wiki/CSV) format. +* `tsv`: Output in [TSV](https://ru.wikipedia.org/wiki/TSV) format. diff --git a/ydb/docs/en/core/reference/ydb-cli/scripting-yql.md b/ydb/docs/en/core/reference/ydb-cli/scripting-yql.md index e8fd9e32a4ba..e63fbee79251 100644 --- a/ydb/docs/en/core/reference/ydb-cli/scripting-yql.md +++ b/ydb/docs/en/core/reference/ydb-cli/scripting-yql.md @@ -19,15 +19,27 @@ ydb scripting yql --help ## Parameters of the subcommand {#options} -| Name | Description | ----|--- -| `--timeout` | The time within which the operation should be completed on the server. | -| `--stats` | Statistics mode.
    Acceptable values:Defaults to `none`. | -| `-s`, `--script` | Text of the YQL query to be executed. | -| `-f`, `--file` | Path to the text of the YQL query to be executed. | -| `--explain` | Show the query execution plan. | -| `--show-response-metadata` | Show the response metadata. | -| `--format` | Input format.
    Default value: `pretty`.
    Acceptable values: | +#| +|| **Name** | **Description** || +|| `--timeout` | The time within which the operation should be completed on the server. || +|| `--stats` | Statistics mode. +Acceptable values: +* `none`: Do not collect statistics. +* `basic`: Collect statistics for basic events. +* `full`: Collect statistics for all events. + Defaults to `none`. || +|| `-s`, `--script` | Text of the YQL query to be executed. || +|| `-f`, `--file` | Path to the text of the YQL query to be executed. || +|| `--explain` | Show the query execution plan. || +|| `--show-response-metadata` | Show the response metadata. || +|| `--format` | Result format. +Default value: `pretty`. +Acceptable values: + +{% include notitle [format](./_includes/result_format_common.md) %} + +|| +|# ### Working with parameterized queries {#parameterized-query} diff --git a/ydb/docs/en/core/reference/ydb-cli/table-query-execute.md b/ydb/docs/en/core/reference/ydb-cli/table-query-execute.md index 0ba3e2a197c4..0acdba1b019a 100644 --- a/ydb/docs/en/core/reference/ydb-cli/table-query-execute.md +++ b/ydb/docs/en/core/reference/ydb-cli/table-query-execute.md @@ -19,17 +19,35 @@ View the description of the YQL query command: ## Parameters of the subcommand {#options} -| Name | Description | ----|--- -| `--timeout` | The time within which the operation should be completed on the server. | -| `-t`, `--type` | Query type.
    Acceptable values:The default value is `data`. | -| `--stats` | Statistics mode.
    Acceptable values:Defaults to `none`. | -| `-s` | Enable statistics collection in the `basic` mode. | -| `--tx-mode` | [Transaction mode](../../concepts/transactions.md#modes) (for `data` queries).
    Acceptable values:Default value: `serializable-rw`. | -| `-q`, `--query` | Text of the YQL query to be executed. | -| `-f,` `--file` | Path to the text of the YQL query to be executed. | -| `--format` | Result format.
    Possible values: | - +#| +|| **Name** | **Description** || +|| `--timeout` | The time within which the operation should be completed on the server. || +|| `-t`, `--type` | Query type. +Acceptable values: +* `data`: A YQL query that includes [DML]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Data_Manipulation_Language){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Data_Manipulation_Language){% endif %} operations; it can be used both to update data in the database and fetch several selections limited to 1,000 rows per selection. +* `scan`: A YQL query of the [scan](../../concepts/scan_query.md) type. It can only be used to read data from the database. It returns a single selection, but without a limit on the number of records in it. The algorithm of executing a `scan` query on the server is more sophisticated compared to a `data` query. Hence, if you don't need to return more than 1,000 rows, `data` queries are more effective. +* `scheme`: A YQL query that includes [DDL]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Data_Definition_Language){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Data_Definition_Language){% endif %} operations. + The default value is `data`. || +|| `--stats` | Statistics mode. +Acceptable values: +* `none`: Do not collect statistics. +* `basic`: Collect statistics for basic events. +* `full`: Collect statistics for all events. + Defaults to `none`. || +|| `-s` | Enable statistics collection in the `basic` mode. || +|| `--tx-mode` | [Transaction mode](../../concepts/transactions.md#modes) (for `data` queries). +Acceptable values:
  • `serializable-rw`: The result of parallel transactions is equivalent to their serial execution.
  • `online-ro`: Each of the reads in the transaction reads data that is most recent at the time of its execution.
  • `stale-ro`: Data reads in a transaction return results with a possible delay (fractions of a second).Default value: `serializable-rw`. || +|| `-q`, `--query` | Text of the YQL query to be executed. || +|| `-f,` `--file` | Path to the text of the YQL query to be executed. || +|| `--format` | Result format. +Possible values: + +{% include notitle [format](./_includes/result_format_common.md) %} + +{% include notitle [format](./_includes/result_format_csv_tsv.md) %} + +|| +|# ### Working with parameterized queries {#parameterized-query} {% include [parameterized-query](../../_includes/parameterized-query.md) %} diff --git a/ydb/docs/en/core/reference/ydb-cli/yql.md b/ydb/docs/en/core/reference/ydb-cli/yql.md index 4d3714a84df3..6ba120d5eaf4 100644 --- a/ydb/docs/en/core/reference/ydb-cli/yql.md +++ b/ydb/docs/en/core/reference/ydb-cli/yql.md @@ -19,14 +19,26 @@ View the description of the YQL script command: ## Parameters of the subcommand {#options} -| Name | Description | ----|--- -| `--timeout` | The time within which the operation should be completed on the server. | -| `--stats` | Statistics mode.
    Acceptable values: | -| `-s`, `--script` | Text of the YQL query to be executed. | -| `-f`, `--file` | Path to the text of the YQL query to be executed. | -| `--format` | Result format.
    Possible values: | - +#| +|| **Name** | **Description** || +|| `--timeout` | The time within which the operation should be completed on the server. || +|| `--stats` | Statistics mode. +Acceptable values: +* `none` (default): Do not collect. +* `basic`: Collect statistics for basic events. +* `full`: Collect statistics for all events. + || +|| `-s`, `--script` | Text of the YQL query to be executed. || +|| `-f`, `--file` | Path to the text of the YQL query to be executed. || +|| `--format` | Result format. +Possible values: + +{% include notitle [format](./_includes/result_format_common.md) %} + +{% include notitle [format](./_includes/result_format_csv_tsv.md) %} + +|| +|# ### Working with parameterized queries {#parameterized-query} {% include [parameterized-query](../../_includes/parameterized-query.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/result_format_common.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/result_format_common.md new file mode 100644 index 000000000000..41d49192a9f4 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/result_format_common.md @@ -0,0 +1,6 @@ +* `pretty` (по умолчанию) — человекочитаемый формат; +* `json-unicode` — вывод в формате [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}, бинарные строки закодированы в [Юникод]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Юникод){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Unicode){% endif %}, каждая строка JSON выводится в отдельной строке; +* `json-unicode-array` — вывод в формате JSON, бинарные строки закодированы в Юникод, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке; +* `json-base64` — вывод в формате JSON, бинарные строки закодированы в [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}, каждая строка JSON выводится в отдельной строке; +* `json-base64-array` — вывод в формате JSON, бинарные строки закодированы в Base64, результат выводится в виде массива строк JSON, каждая строка JSON выводится в отдельной строке; +* `parquet`: вывод в формате [Apache Parquet](https://parquet.apache.org/docs/). \ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/result_format_csv_tsv.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/result_format_csv_tsv.md new file mode 100644 index 000000000000..25133d2c0239 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/result_format_csv_tsv.md @@ -0,0 +1,2 @@ +* `csv` — вывод в формате [CSV](https://ru.wikipedia.org/wiki/CSV); +* `tsv` — вывод в формате [TSV](https://ru.wikipedia.org/wiki/TSV). diff --git a/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md b/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md index 7186d4510830..511cc98e9428 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/scripting-yql.md @@ -19,16 +19,27 @@ ydb scripting yql --help ## Параметры подкоманды {#options} -Имя | Описание ----|--- -`--timeout` | Время, в течение которого должна быть выполнена операция на сервере. -`--stats` | Режим сбора статистики.
    Возможные значения:Значение по умолчанию — `none`. -`-s`, `--script` | Текст YQL-скрипта для выполнения. -`-f`, `--file` | Путь к файлу с текстом YQL-скрипта для выполнения. -`--explain` | Показать план выполнения запроса. -`--show-response-metadata` | Показать метаданные ответа. -`--format` | Формат вывода.
    Значение по умолчанию — `pretty`.
    Возможные значения: - +#| +|| **Имя** | **Описание** || +||`--timeout` | Время, в течение которого должна быть выполнена операция на сервере.|| +||`--stats` | Режим сбора статистики. +Возможные значения: +* `none` — не собирать; +* `basic` — собирать по основным событиям; +* `full` — собирать по всем событиям. +Значение по умолчанию — `none`.|| +||`-s`, `--script` | Текст YQL-скрипта для выполнения.|| +||`-f`, `--file` | Путь к файлу с текстом YQL-скрипта для выполнения.|| +||`--explain` | Показать план выполнения запроса.|| +||`--show-response-metadata` | Показать метаданные ответа.|| +||`--format` | Формат вывода. +Значение по умолчанию — `pretty`. +Возможные значения: + +{% include notitle [format](./_includes/result_format_common.md) %} + +|| +|# ### Работа с параметризованными запросами {#parameterized-query} {% include [parameterized-query](../../_includes/parameterized-query.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/table-query-execute.md b/ydb/docs/ru/core/reference/ydb-cli/table-query-execute.md index 81491ff3e767..8a9271672aff 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/table-query-execute.md +++ b/ydb/docs/ru/core/reference/ydb-cli/table-query-execute.md @@ -19,16 +19,35 @@ ## Параметры подкоманды {#options} -Имя | Описание ----|--- -`--timeout` | Время, в течение которого должна быть выполнена операция на сервере. -`-t`, `--type` | Тип запроса.
    Возможные значения:Значение по умолчанию — `data`. -`--stats` | Режим сбора статистики.
    Возможные значения:Значение по умолчанию — `none`. -`-s` | Включить сбор статистики в режиме `basic`. -`--tx-mode` | [Режим транзакций](../../concepts/transactions.md#modes) (для запросов типа `data`).
    Возможные значения:Значение по умолчанию — `serializable-rw`. -`-q`, `--query` | Текст YQL-запроса для выполнения. -`-f,` `--file` | Путь к файлу с текстом YQL-запроса для выполнения. -`--format` | Формат вывода.
    Возможные значения: +#| +|| **Имя** | **Описание** || +||`--timeout` | Время, в течение которого должна быть выполнена операция на сервере.|| +||`-t`, `--type` | Тип запроса. +Возможные значения: +* `data` — YQL-запрос, содержащий [DML]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Data_Manipulation_Language){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Data_Manipulation_Language){% endif %} операции, допускает как изменение данных в базе, так и получение нескольких выборок с ограничением в 1000 строк в каждой выборке. +* `scan` — YQL-запрос типа [скан](../../concepts/scan_query.md), допускает только чтение данных из базы, может вернуть только одну выборку, но без ограничения на количество записей в ней. Алгоритм исполнения запроса типа `scan` на сервере более сложный по сравнению с `data`, поэтому в отсутствие требований по возврату более 1000 строк эффективнее использовать тип запроса `data`. +* `scheme` — YQL-запрос, содержащий [DDL]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Data_Definition_Language){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Data_Definition_Language){% endif %} операции. +Значение по умолчанию — `data`.|| +||`--stats` | Режим сбора статистики. +Возможные значения: +* `none` — не собирать; +* `basic` — собирать по основным событиям; +* `full` — собирать по всем событиям. +Значение по умолчанию — `none`.|| +||`-s` | Включить сбор статистики в режиме `basic`.|| +||`--tx-mode` | [Режим транзакций](../../concepts/transactions.md#modes) (для запросов типа `data`). +Возможные значения:
  • `serializable-rw` — результат успешно выполненных параллельных транзакций эквивалентен определенному последовательному порядку их выполнения;
  • `online-ro` — каждое из чтений в транзакции читает последние на момент своего выполнения данные;
  • `stale-ro` — чтения данных в транзакции возвращают результаты с возможным отставанием от актуальных (доли секунды).Значение по умолчанию — `serializable-rw`.|| +||`-q`, `--query` | Текст YQL-запроса для выполнения.|| +||`-f,` `--file` | Путь к файлу с текстом YQL-запроса для выполнения.|| +||`--format` | Формат вывода. +Возможные значения: + +{% include notitle [format](./_includes/result_format_common.md) %} + +{% include notitle [format](./_includes/result_format_csv_tsv.md) %} + +|| +|# ### Работа с параметризованными запросами {#parameterized-query} diff --git a/ydb/docs/ru/core/reference/ydb-cli/yql.md b/ydb/docs/ru/core/reference/ydb-cli/yql.md index 971f3efe27a3..5c35e1d665bf 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/yql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/yql.md @@ -19,13 +19,26 @@ ## Параметры подкоманды {#options} -Имя | Описание ----|--- -`--timeout` | Время, в течение которого должна быть выполнена операция на сервере. -`--stats` | Режим сбора статистики.
    Возможные значения: -`-s`, `--script` | Текст YQL-скрипта для выполнения. -`-f`, `--file` | Путь к файлу с текстом YQL-скрипта для выполнения. -`--format` | Формат вывода.
    Возможные значения: +#| +|| **Имя** | **Описание** || +|| `--timeout` | Время, в течение которого должна быть выполнена операция на сервере. || +|| `--stats` | Режим сбора статистики. +Возможные значения: +* `none` (по умолчанию) — не собирать; +* `basic` — собирать по основным событиям; +* `full` — собирать по всем событиям. +|| +|| `-s`, `--script` | Текст YQL-скрипта для выполнения. || +|| `-f`, `--file` | Путь к файлу с текстом YQL-скрипта для выполнения. || +|| `--format` | Формат вывода. +Возможные значения: + +{% include notitle [format](./_includes/result_format_common.md) %} + +{% include notitle [format](./_includes/result_format_csv_tsv.md) %} + +|| +|# ### Работа с параметризованными запросами {#parameterized-query}