From a09f70b541aef240e639f0c9b4486e16b2e4166d Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 29 May 2025 14:38:45 +0300 Subject: [PATCH 01/22] Initial commit --- ydb/docs/en/core/reference/ydb-cli/sql.md | 21 +++++++++++++++++++++ ydb/docs/ru/core/reference/ydb-cli/sql.md | 22 ++++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 87dea3e2da05..26458f1e16a6 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -29,6 +29,7 @@ View the description of this command by calling it with `--help` option: || `--explain` | Execute an explain request for the query. Displays the query's logical plan. The query is not actually executed and does not affect database data. || || `--explain-ast` | Same as `--explain`, but in addition to the query's logical plan, an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) is printed. The AST section contains a representation in the internal [miniKQL](../../concepts/glossary.md#minikql) language. || || `--explain-analyze` | Execute the query in `EXPLAIN ANALYZE` mode. Displays the query execution plan. Query results are ignored.
**Important note: The query is actually executed, so any changes will be applied to the database**. || +|| `--diagnostics-file` | Path to file where the diagnostics will be saved. || || `--format` | Output format.
Available options: {% include notitle [format](./_includes/result_format_common.md) %} @@ -38,6 +39,26 @@ View the description of this command by calling it with `--help` option: || |# +### Diagnostics Collection + +The `--diagnostics-file ` option allows you to save extended information about SQL query execution to a separate JSON file. + +Diagnostics are collected when statistics gathering is enabled (`--stats full` or `--stats profile`), as well as during execution of `EXPLAIN` queries. For each query, a file named `.json` will be created with the following fields: + +- **`created_at`** — query start time (timestamp) +- **`query_cluster`** — name of the cluster or provider +- **`query_database`** — path to the database +- **`query_id`** — unique query identifier +- **`query_plan`** — query execution plan +- **`query_syntax`** — query syntax used +- **`query_text`** — text of the SQL query + **Note!** This field may contain sensitive or private user data, including parameter values used in the query. +- **`query_type`** — type of the query +- **`table_metadata`** — schemas, indexes, and table statistics involved in the query (in JSON format) + +> **Important:** +> The diagnostics file may contain confidential data, especially in the **`query_text`** field. Before sharing this file with third parties (e.g., technical support), it is recommended to manually review and edit its contents to remove or replace any sensitive information. + ### Working with parameterized queries {#parameterized-query} For a detailed description with examples on how to use parameterized queries, see [{#T}](parameterized-query-execution.md). diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index 3cd2096364ed..38776428bf76 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -29,6 +29,7 @@ || `--explain` | Выполнить explain-запрос, будет выведен логический план запроса. Сам запрос не будет выполнен, поэтому не затронет данные в базе. || || `--explain-ast` | То же, что и `--explain`, но вдобавок к логическому плану выводит [AST (abstract syntax tree)](https://ru.wikipedia.org/wiki/Абстрактное_синтаксическое_дерево). Раздел с AST содержит представление на внутреннем языке [miniKQL](../../concepts/glossary.md#minikql). || || `--explain-analyze` | Выполнить запрос в режиме `EXPLAIN ANALYZE`. Показывает план выполнения запроса. Возвращаемые в рамках запроса данные игнорируются.
**Важное замечание: Запрос фактически выполняется, поэтому может внести изменения в базу**. || +|| `--diagnostics-file` | Путь для сохранения файла с диагностикой. || || `--format` | Формат вывода.
Возможные значения: {% include notitle [format](./_includes/result_format_common.md) %} @@ -38,6 +39,27 @@ || |# +### Сбор диагностики + +Опция `--diagnostics-file ` позволяет сохранять расширенную информацию о выполнении SQL-запросов в отдельный JSON-файл. + +Диагностика формируется при сборе статистики (`--stats full` или `--stats profile`), а также при выполнении `EXPLAIN`-запросов. Для каждого запроса будет создан файл `.json` со следующими полями: + +- **`created_at`** — время начала запроса (timestamp) +- **`query_cluster`** — название кластера или провайдера +- **`query_database`** — путь к базе данных +- **`query_id`** — уникальный идентификатор запроса +- **`query_plan`** — план выполнения запроса +- **`query_syntax`** — используемый синтаксис запроса +- **`query_text`** — текст SQL-запроса + + **Внимание!** Это поле может содержать чувствительные или личные данные пользователя, включая значения параметров в запросе. +- **`query_type`** — тип запроса +- **`table_metadata`** — схемы, индексы и статистика по таблицам, участвующим в запросе (формат JSON) + +> **Важно:** +> Файл диагностики может содержать конфиденциальные данные, особенно в поле `query_text`. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. + ### Работа с параметризованными запросами {#parameterized-query} Подробное описание работы с параметрами с примерами смотрите в статье [{#T}](parameterized-query-execution.md). From 1ab046651ceba97c486b7ab0cc049972078842a4 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 29 May 2025 15:17:16 +0300 Subject: [PATCH 02/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 31 +++++++++++++---------- ydb/docs/ru/core/reference/ydb-cli/sql.md | 28 +++++++++++--------- 2 files changed, 34 insertions(+), 25 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 26458f1e16a6..5d4c54f8fbd6 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -39,25 +39,30 @@ View the description of this command by calling it with `--help` option: || |# -### Diagnostics Collection +### Diagnostics collection The `--diagnostics-file ` option allows you to save extended information about SQL query execution to a separate JSON file. -Diagnostics are collected when statistics gathering is enabled (`--stats full` or `--stats profile`), as well as during execution of `EXPLAIN` queries. For each query, a file named `.json` will be created with the following fields: +Diagnostics are collected when statistics gathering is enabled (`--stats full` or `--stats profile`), as well as during execution of `EXPLAIN` queries. For each query, a file named `` will be created with the following fields: -- **`created_at`** — query start time (timestamp) -- **`query_cluster`** — name of the cluster or provider -- **`query_database`** — path to the database -- **`query_id`** — unique query identifier -- **`query_plan`** — query execution plan -- **`query_syntax`** — query syntax used -- **`query_text`** — text of the SQL query - **Note!** This field may contain sensitive or private user data, including parameter values used in the query. -- **`query_type`** — type of the query -- **`table_metadata`** — schemas, indexes, and table statistics involved in the query (in JSON format) +- **`plan`** — query execution plan. +- **`stats`** — query execution statistics. +- **`meta`** — additional query information in JSON format, including the following fields: + - **`created_at`** — query start time (timestamp); + - **`query_cluster`** — cluster or provider name; + - **`query_database`** — database path; + - **`query_id`** — unique query identifier; + - **`query_syntax`** — query syntax used; + - **`query_text`** — SQL query text. + + **Note:** This field may contain sensitive or personal data, including parameter values; + + - **`query_type`** — query type; + - **`table_metadata`** — schemas, indexes, and statistics of the tables involved in the query (JSON format). +- **`ast`** — abstract syntax tree (AST) for the query. > **Important:** -> The diagnostics file may contain confidential data, especially in the **`query_text`** field. Before sharing this file with third parties (e.g., technical support), it is recommended to manually review and edit its contents to remove or replace any sensitive information. +> The diagnostics file may contain confidential information, especially in the **`meta.query_text`** field. Before sharing this file with third parties (such as technical support), it is strongly recommended to review and edit the file contents to remove or replace any sensitive data. ### Working with parameterized queries {#parameterized-query} diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index 38776428bf76..90e49fb08614 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -43,22 +43,26 @@ Опция `--diagnostics-file ` позволяет сохранять расширенную информацию о выполнении SQL-запросов в отдельный JSON-файл. -Диагностика формируется при сборе статистики (`--stats full` или `--stats profile`), а также при выполнении `EXPLAIN`-запросов. Для каждого запроса будет создан файл `.json` со следующими полями: +Диагностика формируется при сборе статистики (`--stats full` или `--stats profile`), а также при выполнении `EXPLAIN`-запросов. Для каждого запроса будет создан файл `` со следующими полями: -- **`created_at`** — время начала запроса (timestamp) -- **`query_cluster`** — название кластера или провайдера -- **`query_database`** — путь к базе данных -- **`query_id`** — уникальный идентификатор запроса -- **`query_plan`** — план выполнения запроса -- **`query_syntax`** — используемый синтаксис запроса -- **`query_text`** — текст SQL-запроса +- **`plan`** — план выполнения запроса. +- **`stats`** — статистика выполнения запроса. +- **`meta`** — дополнительная информация о запросе в JSON-формате со следующими полями: + - **`created_at`** — время начала запроса (timestamp). + - **`query_cluster`** — название кластера или провайдера. + - **`query_database`** — путь к базе данных. + - **`query_id`** — уникальный идентификатор запроса. + - **`query_syntax`** — используемый синтаксис запроса. + - **`query_text`** — текст SQL-запроса. - **Внимание!** Это поле может содержать чувствительные или личные данные пользователя, включая значения параметров в запросе. -- **`query_type`** — тип запроса -- **`table_metadata`** — схемы, индексы и статистика по таблицам, участвующим в запросе (формат JSON) + **Внимание!** Это поле может содержать чувствительные или личные данные пользователя, включая значения параметров в запросе. + + - **`query_type`** — тип запроса. + - **`table_metadata`** — схемы, индексы и статистика по таблицам, участвующим в запросе (JSON-формат). +- **`ast`** — абстрактное синтаксическое дерево (AST) запроса. > **Важно:** -> Файл диагностики может содержать конфиденциальные данные, особенно в поле `query_text`. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. +> Файл диагностики может содержать конфиденциальные данные, особенно в поле **`meta.query_text`**. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. ### Работа с параметризованными запросами {#parameterized-query} From f8302eb160964b9b910e830ae81b655914621221 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 29 May 2025 15:50:29 +0300 Subject: [PATCH 03/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 32 ++++++++++++++++++++++- ydb/docs/ru/core/reference/ydb-cli/sql.md | 32 ++++++++++++++++++++++- 2 files changed, 62 insertions(+), 2 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 5d4c54f8fbd6..e9e66f508fac 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -62,7 +62,37 @@ Diagnostics are collected when statistics gathering is enabled (`--stats full` o - **`ast`** — abstract syntax tree (AST) for the query. > **Important:** -> The diagnostics file may contain confidential information, especially in the **`meta.query_text`** field. Before sharing this file with third parties (such as technical support), it is strongly recommended to review and edit the file contents to remove or replace any sensitive data. +> The diagnostics file may contain confidential information in the **`meta.query_text`**, **`plan`**, and **`ast`** fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. + +**Example of a query containing sensitive information:** + +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json +``` +In the `diagnostics.json` file, in the **`meta.query_text`** field, the following string will appear: +```json +"query_text": "INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');" +``` +This contains sensitive information — a user’s email address. + +Before sharing the diagnostics file, it is recommended to replace actual values with placeholders: +```json +"query_text": "SELECT * FROM users WHERE email = '';" +``` +Email addresses can also be found in fields such as **`plan`** and **`ast`**, for example: +```json +"plan": + ... + "Predicate" : "item.emails == \"alice@example.com\"", + ... +``` +Such entries should also be replaced, for example: +```json +"plan": + ... + "Predicate" : "item.emails == \"\"", + ... +``` ### Working with parameterized queries {#parameterized-query} diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index 90e49fb08614..9f38771856a5 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -62,7 +62,37 @@ - **`ast`** — абстрактное синтаксическое дерево (AST) запроса. > **Важно:** -> Файл диагностики может содержать конфиденциальные данные, особенно в поле **`meta.query_text`**. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. +> Файл диагностики может содержать конфиденциальные данные в полях **`meta.query_text`**, **`plan`** и **`ast`**. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. + +**Пример запроса с чувствительной информацией:** + +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json +``` +В диагностическом файле `diagnostics.json` в поле **`meta.query_text`** будет содержаться такая строка: +```json +"query_text": "INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');" +``` +Здесь присутствует чувствительная информация — адрес электронной почты пользователя. + +Перед передачей диагностического файла рекомендуется заменить реальные значения на шаблонные: +```json +"query_text": "SELECT * FROM users WHERE email = '';" +``` +Адрес электронной почты можно обнаружить в полях **`plan`** и **`ast`**, например: +```json +"plan": + ... + "Predicate" : "item.emails == \"alice@example.com\"", + ... +``` +Такие вхождения тоже нужно заменить, например: +```json +"plan": + ... + "Predicate" : "item.emails == \"\"", + ... +``` ### Работа с параметризованными запросами {#parameterized-query} From 64ca1e2bee372b40e5894fc31ae860c96daa5b98 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 29 May 2025 15:54:31 +0300 Subject: [PATCH 04/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 2 +- ydb/docs/ru/core/reference/ydb-cli/sql.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index e9e66f508fac..ca0244f6fc60 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -43,7 +43,7 @@ View the description of this command by calling it with `--help` option: The `--diagnostics-file ` option allows you to save extended information about SQL query execution to a separate JSON file. -Diagnostics are collected when statistics gathering is enabled (`--stats full` or `--stats profile`), as well as during execution of `EXPLAIN` queries. For each query, a file named `` will be created with the following fields: +Diagnostics are collected when statistics gathering is enabled `--stats full`, as well as during execution of `EXPLAIN` queries. For each query, a file named `` will be created with the following fields: - **`plan`** — query execution plan. - **`stats`** — query execution statistics. diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index 9f38771856a5..3f287ee71371 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -43,7 +43,7 @@ Опция `--diagnostics-file ` позволяет сохранять расширенную информацию о выполнении SQL-запросов в отдельный JSON-файл. -Диагностика формируется при сборе статистики (`--stats full` или `--stats profile`), а также при выполнении `EXPLAIN`-запросов. Для каждого запроса будет создан файл `` со следующими полями: +Диагностика формируется при сборе статистики `--stats full`, а также при выполнении `EXPLAIN`-запросов. Для каждого запроса будет создан файл `` со следующими полями: - **`plan`** — план выполнения запроса. - **`stats`** — статистика выполнения запроса. From 94a9af66e54873be276cf88941a4a2bc839babb5 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 29 May 2025 16:23:47 +0300 Subject: [PATCH 05/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 8 ++++++++ ydb/docs/ru/core/reference/ydb-cli/sql.md | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index ca0244f6fc60..6dc54612bcab 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -69,24 +69,32 @@ Diagnostics are collected when statistics gathering is enabled `--stats full`, a ```bash ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json ``` + In the `diagnostics.json` file, in the **`meta.query_text`** field, the following string will appear: + ```json "query_text": "INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');" ``` + This contains sensitive information — a user’s email address. Before sharing the diagnostics file, it is recommended to replace actual values with placeholders: + ```json "query_text": "SELECT * FROM users WHERE email = '';" ``` + Email addresses can also be found in fields such as **`plan`** and **`ast`**, for example: + ```json "plan": ... "Predicate" : "item.emails == \"alice@example.com\"", ... ``` + Such entries should also be replaced, for example: + ```json "plan": ... diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index 3f287ee71371..f9516616b1ae 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -69,24 +69,32 @@ ```bash ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json ``` + В диагностическом файле `diagnostics.json` в поле **`meta.query_text`** будет содержаться такая строка: + ```json "query_text": "INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');" ``` + Здесь присутствует чувствительная информация — адрес электронной почты пользователя. Перед передачей диагностического файла рекомендуется заменить реальные значения на шаблонные: + ```json "query_text": "SELECT * FROM users WHERE email = '';" ``` + Адрес электронной почты можно обнаружить в полях **`plan`** и **`ast`**, например: + ```json "plan": ... "Predicate" : "item.emails == \"alice@example.com\"", ... ``` + Такие вхождения тоже нужно заменить, например: + ```json "plan": ... From ad167447b75ffe5703b1846b2f96063d218b481c Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 29 May 2025 17:11:00 +0300 Subject: [PATCH 06/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 10 +++++++++- ydb/docs/ru/core/reference/ydb-cli/sql.md | 12 +++++++++++- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 6dc54612bcab..11a023d34650 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -64,12 +64,20 @@ Diagnostics are collected when statistics gathering is enabled `--stats full`, a > **Important:** > The diagnostics file may contain confidential information in the **`meta.query_text`**, **`plan`**, and **`ast`** fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. -**Example of a query containing sensitive information:** +**Examples:** + +Example command to collect diagnostics in the `diagnostics.json` file: ```bash ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json ``` +If you want to collect diagnostics related to a query plan without actually executing the query, you can execute an `EXPLAIN` query instead: + +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json +``` + In the `diagnostics.json` file, in the **`meta.query_text`** field, the following string will appear: ```json diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index f9516616b1ae..f2326fe734b2 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -64,12 +64,20 @@ > **Важно:** > Файл диагностики может содержать конфиденциальные данные в полях **`meta.query_text`**, **`plan`** и **`ast`**. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. -**Пример запроса с чувствительной информацией:** +**Примеры:** + +Пример команды, чтобы собрать диагностику в файл `diagnostics.json`: ```bash ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json ``` +Если вы хотите получить диагностические данные, относящиеся к плану запроса, без фактического выполнения запроса, вы можете вместо этого выполнить `EXPLAIN`-запрос: + +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json +``` + В диагностическом файле `diagnostics.json` в поле **`meta.query_text`** будет содержаться такая строка: ```json @@ -102,6 +110,8 @@ ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice ... ``` +Для сбора диагностической информации относительно плана для запроса, + ### Работа с параметризованными запросами {#parameterized-query} Подробное описание работы с параметрами с примерами смотрите в статье [{#T}](parameterized-query-execution.md). From 80d756744a6e6addbecb78364670bc2dac4469a7 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 29 May 2025 17:11:55 +0300 Subject: [PATCH 07/22] Fixes --- ydb/docs/ru/core/reference/ydb-cli/sql.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index f2326fe734b2..98984366e143 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -110,8 +110,6 @@ ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice ... ``` -Для сбора диагностической информации относительно плана для запроса, - ### Работа с параметризованными запросами {#parameterized-query} Подробное описание работы с параметрами с примерами смотрите в статье [{#T}](parameterized-query-execution.md). From 6311e3525fda2e8df97c2b1b36bbf8e3063bd681 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 29 May 2025 20:38:33 +0300 Subject: [PATCH 08/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 25 +++++------------------ ydb/docs/ru/core/reference/ydb-cli/sql.md | 25 +++++------------------ 2 files changed, 10 insertions(+), 40 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 11a023d34650..46ae2834cd13 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -62,14 +62,15 @@ Diagnostics are collected when statistics gathering is enabled `--stats full`, a - **`ast`** — abstract syntax tree (AST) for the query. > **Important:** -> The diagnostics file may contain confidential information in the **`meta.query_text`**, **`plan`**, and **`ast`** fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. +> The diagnostics file may contain confidential information, especially in the **`meta.query_text`**, **`plan`**, and **`ast`** fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. **Examples:** -Example command to collect diagnostics in the `diagnostics.json` file: +Example command to collect diagnostics in the `diagnostics.json` file and check its contents: ```bash ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json +cat diagnostics.json ``` If you want to collect diagnostics related to a query plan without actually executing the query, you can execute an `EXPLAIN` query instead: @@ -81,7 +82,7 @@ ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice In the `diagnostics.json` file, in the **`meta.query_text`** field, the following string will appear: ```json -"query_text": "INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');" +"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" ``` This contains sensitive information — a user’s email address. @@ -92,23 +93,7 @@ Before sharing the diagnostics file, it is recommended to replace actual values "query_text": "SELECT * FROM users WHERE email = '';" ``` -Email addresses can also be found in fields such as **`plan`** and **`ast`**, for example: - -```json -"plan": - ... - "Predicate" : "item.emails == \"alice@example.com\"", - ... -``` - -Such entries should also be replaced, for example: - -```json -"plan": - ... - "Predicate" : "item.emails == \"\"", - ... -``` +In this example, the email address can also be found in fields such as **`plan`** and **`ast`**, such entries should also be replaced. ### Working with parameterized queries {#parameterized-query} diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index 98984366e143..bb131fe18369 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -62,14 +62,15 @@ - **`ast`** — абстрактное синтаксическое дерево (AST) запроса. > **Важно:** -> Файл диагностики может содержать конфиденциальные данные в полях **`meta.query_text`**, **`plan`** и **`ast`**. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. +> Файл диагностики может содержать конфиденциальные данные, особенно в полях **`meta.query_text`**, **`plan`** и **`ast`**. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. **Примеры:** -Пример команды, чтобы собрать диагностику в файл `diagnostics.json`: +Пример команды, чтобы собрать диагностику в файл `diagnostics.json` и проверить его содержимое: ```bash ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json +cat diagnostics.json ``` Если вы хотите получить диагностические данные, относящиеся к плану запроса, без фактического выполнения запроса, вы можете вместо этого выполнить `EXPLAIN`-запрос: @@ -81,7 +82,7 @@ ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice В диагностическом файле `diagnostics.json` в поле **`meta.query_text`** будет содержаться такая строка: ```json -"query_text": "INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');" +"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" ``` Здесь присутствует чувствительная информация — адрес электронной почты пользователя. @@ -92,23 +93,7 @@ ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice "query_text": "SELECT * FROM users WHERE email = '';" ``` -Адрес электронной почты можно обнаружить в полях **`plan`** и **`ast`**, например: - -```json -"plan": - ... - "Predicate" : "item.emails == \"alice@example.com\"", - ... -``` - -Такие вхождения тоже нужно заменить, например: - -```json -"plan": - ... - "Predicate" : "item.emails == \"\"", - ... -``` +В данном примере адрес электронной почты можно обнаружить в полях **`plan`** и **`ast`**, такие вхождения тоже нужно заменить. ### Работа с параметризованными запросами {#parameterized-query} From 11ca1e575b0c8791edec4234b793eea64f60e5be Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 29 May 2025 20:44:09 +0300 Subject: [PATCH 09/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 46ae2834cd13..eb49ddf28394 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -62,7 +62,7 @@ Diagnostics are collected when statistics gathering is enabled `--stats full`, a - **`ast`** — abstract syntax tree (AST) for the query. > **Important:** -> The diagnostics file may contain confidential information, especially in the **`meta.query_text`**, **`plan`**, and **`ast`** fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. +> The diagnostics file may contain confidential information, especially in the **`meta.query_text`**, **`plan`**, and **`ast`** fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. **Examples:** From a44eafa017d42e6f79ce0ddc981cd872b7221935 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 2 Jun 2025 12:25:48 +0300 Subject: [PATCH 10/22] Update ydb/docs/en/core/reference/ydb-cli/sql.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- ydb/docs/en/core/reference/ydb-cli/sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index eb49ddf28394..43f08fe21ec1 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -55,7 +55,7 @@ Diagnostics are collected when statistics gathering is enabled `--stats full`, a - **`query_syntax`** — query syntax used; - **`query_text`** — SQL query text. - **Note:** This field may contain sensitive or personal data, including parameter values; + **Note:** This field may contain sensitive or personal data, including parameter values. - **`query_type`** — query type; - **`table_metadata`** — schemas, indexes, and statistics of the tables involved in the query (JSON format). From 1d0bbad132438d95d6ead81874125f531c57b84d Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 5 Jun 2025 13:41:39 +0300 Subject: [PATCH 11/22] Update ydb/docs/en/core/reference/ydb-cli/sql.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/en/core/reference/ydb-cli/sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 43f08fe21ec1..0f40295392f5 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -66,7 +66,7 @@ Diagnostics are collected when statistics gathering is enabled `--stats full`, a **Examples:** -Example command to collect diagnostics in the `diagnostics.json` file and check its contents: +Сommand to collect diagnostics in the `diagnostics.json` file and check its contents: ```bash ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json From 8daa7d93351eff68bad151d162cf3931c7a508ab Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 9 Jun 2025 15:56:08 +0300 Subject: [PATCH 12/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 108 ++++++++++++---------- ydb/docs/ru/core/reference/ydb-cli/sql.md | 104 +++++++++++---------- 2 files changed, 112 insertions(+), 100 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 0f40295392f5..a26473e930b1 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -43,57 +43,33 @@ View the description of this command by calling it with `--help` option: The `--diagnostics-file ` option allows you to save extended information about SQL query execution to a separate JSON file. -Diagnostics are collected when statistics gathering is enabled `--stats full`, as well as during execution of `EXPLAIN` queries. For each query, a file named `` will be created with the following fields: - -- **`plan`** — query execution plan. -- **`stats`** — query execution statistics. -- **`meta`** — additional query information in JSON format, including the following fields: - - **`created_at`** — query start time (timestamp); - - **`query_cluster`** — cluster or provider name; - - **`query_database`** — database path; - - **`query_id`** — unique query identifier; - - **`query_syntax`** — query syntax used; - - **`query_text`** — SQL query text. - - **Note:** This field may contain sensitive or personal data, including parameter values. - - - **`query_type`** — query type; - - **`table_metadata`** — schemas, indexes, and statistics of the tables involved in the query (JSON format). -- **`ast`** — abstract syntax tree (AST) for the query. - -> **Important:** -> The diagnostics file may contain confidential information, especially in the **`meta.query_text`**, **`plan`**, and **`ast`** fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. - -**Examples:** - -Сommand to collect diagnostics in the `diagnostics.json` file and check its contents: - -```bash -ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json -cat diagnostics.json -``` - -If you want to collect diagnostics related to a query plan without actually executing the query, you can execute an `EXPLAIN` query instead: - -```bash -ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json -``` - -In the `diagnostics.json` file, in the **`meta.query_text`** field, the following string will appear: - -```json -"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" -``` - -This contains sensitive information — a user’s email address. - -Before sharing the diagnostics file, it is recommended to replace actual values with placeholders: - -```json -"query_text": "SELECT * FROM users WHERE email = '';" -``` - -In this example, the email address can also be found in fields such as **`plan`** and **`ast`**, such entries should also be replaced. +For each query, a file named `` will be created with the following fields: + +- `plan` — query execution plan. +- `stats` — query execution statistics. +- `meta` — additional query information in JSON format, including the following fields: + - `created_at` — query start time (timestamp); + - `query_cluster` — cluster or provider name; + - `query_database` — database path; + - `query_id` — unique query identifier; + - `query_syntax` — query syntax used; + - `query_text` — SQL query text. + + {% note info %} + `meta` are collected when statistics gathering is enabled `--stats full`, as well as during execution of queries with `EXPLAIN` mode. + {% endnote %} + + {% note warning %} + This field may contain sensitive or personal data, including parameter values. + {% endnote %} + + - `query_type` — query type; + - `table_metadata` — schemas, indexes, and statistics of the tables involved in the query (JSON format). +- `ast` — abstract syntax tree (AST) for the query. + +{% note tip %} +The diagnostics file may contain confidential information, especially in the `meta.query_text`, `plan`, and `ast` fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. +{% endnote %} ### Working with parameterized queries {#parameterized-query} @@ -138,3 +114,33 @@ Command output: ``` You can find examples of passing parameters to queries in the [article on how to pass parameters to `{{ ydb-cli }} sql`](parameterized-query-execution.md). + +Сommand to collect diagnostics in the `diagnostics.json` file and check its contents: + +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" \ +--stats full --diagnostics-file diagnostics.json +cat diagnostics.json +``` + +If you want to collect diagnostics related to a query plan without actually executing the query, you can execute an query with `EXPLAIN` mode instead by adding the `--explain` option: + +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json +``` + +In the `diagnostics.json` file, in the `meta.query_text` field, the following string will appear: + +```json +"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" +``` + +This contains sensitive information — a user’s email address. + +Before sharing the diagnostics file, it is recommended to replace actual values with placeholders: + +```json +"query_text": "SELECT * FROM users WHERE email = '';" +``` + +In this example, the email address can also be found in fields such as `plan` and `ast`, such entries should also be replaced. diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index bb131fe18369..43b3752edbaf 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -45,55 +45,31 @@ Диагностика формируется при сборе статистики `--stats full`, а также при выполнении `EXPLAIN`-запросов. Для каждого запроса будет создан файл `` со следующими полями: -- **`plan`** — план выполнения запроса. -- **`stats`** — статистика выполнения запроса. -- **`meta`** — дополнительная информация о запросе в JSON-формате со следующими полями: - - **`created_at`** — время начала запроса (timestamp). - - **`query_cluster`** — название кластера или провайдера. - - **`query_database`** — путь к базе данных. - - **`query_id`** — уникальный идентификатор запроса. - - **`query_syntax`** — используемый синтаксис запроса. - - **`query_text`** — текст SQL-запроса. - - **Внимание!** Это поле может содержать чувствительные или личные данные пользователя, включая значения параметров в запросе. - - - **`query_type`** — тип запроса. - - **`table_metadata`** — схемы, индексы и статистика по таблицам, участвующим в запросе (JSON-формат). -- **`ast`** — абстрактное синтаксическое дерево (AST) запроса. - -> **Важно:** -> Файл диагностики может содержать конфиденциальные данные, особенно в полях **`meta.query_text`**, **`plan`** и **`ast`**. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. - -**Примеры:** - -Пример команды, чтобы собрать диагностику в файл `diagnostics.json` и проверить его содержимое: - -```bash -ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --stats full --diagnostics-file diagnostics.json -cat diagnostics.json -``` - -Если вы хотите получить диагностические данные, относящиеся к плану запроса, без фактического выполнения запроса, вы можете вместо этого выполнить `EXPLAIN`-запрос: - -```bash -ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json -``` - -В диагностическом файле `diagnostics.json` в поле **`meta.query_text`** будет содержаться такая строка: - -```json -"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" -``` - -Здесь присутствует чувствительная информация — адрес электронной почты пользователя. - -Перед передачей диагностического файла рекомендуется заменить реальные значения на шаблонные: - -```json -"query_text": "SELECT * FROM users WHERE email = '';" -``` - -В данном примере адрес электронной почты можно обнаружить в полях **`plan`** и **`ast`**, такие вхождения тоже нужно заменить. +- `plan` — план выполнения запроса. +- `stats` — статистика выполнения запроса. +- `meta` — дополнительная информация о запросе в JSON-формате со следующими полями: + - `created_at` — время начала запроса (timestamp). + - `query_cluster` — название кластера или провайдера. + - `query_database` — путь к базе данных. + - `query_id` — уникальный идентификатор запроса. + - `query_syntax` — используемый синтаксис запроса. + - `query_text` — текст SQL-запроса. + + {% note info %} + `meta` формируется при сборе статистики `--stats full`, а также при выполнении `EXPLAIN`-запросов. + {% endnote %} + + {% note warning %} + Это поле может содержать чувствительные или личные данные пользователя, включая значения параметров в запросе. + {% endnote %} + + - `query_type` — тип запроса. + - `table_metadata` — схемы, индексы и статистика по таблицам, участвующим в запросе (JSON-формат). +- `ast` — абстрактное синтаксическое дерево (AST) запроса. + +{% note tip %} +Файл диагностики может содержать конфиденциальные данные, особенно в полях `meta.query_text`, `plan` и `ast`. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. +{% endnote %} ### Работа с параметризованными запросами {#parameterized-query} @@ -138,3 +114,33 @@ ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice ``` Примеры передачи параметров в скрипты приведены в [статье о передаче параметров в команды исполнения запросов](parameterized-query-execution.md). + +Пример команды, чтобы собрать диагностику в файл `diagnostics.json` и проверить его содержимое: + +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" \ +--stats full --diagnostics-file diagnostics.json +cat diagnostics.json +``` + +Если вы хотите получить диагностические данные, относящиеся к плану запроса, без фактического выполнения запроса, вы можете вместо этого выполнить `EXPLAIN`-запрос, добавив опцию `--explain`: + +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json +``` + +В диагностическом файле `diagnostics.json` в поле `meta.query_text` будет содержаться такая строка: + +```json +"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" +``` + +Здесь присутствует чувствительная информация — адрес электронной почты пользователя. + +Перед передачей диагностического файла рекомендуется заменить реальные значения на шаблонные: + +```json +"query_text": "SELECT * FROM users WHERE email = '';" +``` + +В данном примере адрес электронной почты можно обнаружить в полях `plan` и `ast`, такие вхождения тоже нужно заменить. From e86312e40d4057515b9fbebb631db6a3b8dcb1bf Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 10 Jun 2025 01:52:42 +0300 Subject: [PATCH 13/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 6 ++++++ ydb/docs/ru/core/reference/ydb-cli/sql.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index a26473e930b1..479a448bc5f8 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -56,11 +56,15 @@ For each query, a file named `` will be created with the fo - `query_text` — SQL query text. {% note info %} + `meta` are collected when statistics gathering is enabled `--stats full`, as well as during execution of queries with `EXPLAIN` mode. + {% endnote %} {% note warning %} + This field may contain sensitive or personal data, including parameter values. + {% endnote %} - `query_type` — query type; @@ -68,7 +72,9 @@ For each query, a file named `` will be created with the fo - `ast` — abstract syntax tree (AST) for the query. {% note tip %} + The diagnostics file may contain confidential information, especially in the `meta.query_text`, `plan`, and `ast` fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. + {% endnote %} ### Working with parameterized queries {#parameterized-query} diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index 43b3752edbaf..df9dedeafae1 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -56,11 +56,15 @@ - `query_text` — текст SQL-запроса. {% note info %} + `meta` формируется при сборе статистики `--stats full`, а также при выполнении `EXPLAIN`-запросов. + {% endnote %} {% note warning %} + Это поле может содержать чувствительные или личные данные пользователя, включая значения параметров в запросе. + {% endnote %} - `query_type` — тип запроса. @@ -68,7 +72,9 @@ - `ast` — абстрактное синтаксическое дерево (AST) запроса. {% note tip %} + Файл диагностики может содержать конфиденциальные данные, особенно в полях `meta.query_text`, `plan` и `ast`. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. + {% endnote %} ### Работа с параметризованными запросами {#parameterized-query} From abb6043cbc22f6e6b9280d58d3553d347672ff3d Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 17 Jun 2025 21:36:23 +0300 Subject: [PATCH 14/22] Update ydb/docs/en/core/reference/ydb-cli/sql.md Co-authored-by: Ivan Blinkov --- ydb/docs/en/core/reference/ydb-cli/sql.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 479a448bc5f8..263e3d8182aa 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -141,9 +141,7 @@ In the `diagnostics.json` file, in the `meta.query_text` field, the following st "query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" ``` -This contains sensitive information — a user’s email address. - -Before sharing the diagnostics file, it is recommended to replace actual values with placeholders: +This contains sensitive information, such as a user’s email address. Before sharing the diagnostics file, replace actual values with placeholders: ```json "query_text": "SELECT * FROM users WHERE email = '';" From 66e25b111b08f2d6ad59b7511f31ca447d950494 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 17 Jun 2025 21:36:57 +0300 Subject: [PATCH 15/22] Update ydb/docs/en/core/reference/ydb-cli/sql.md Co-authored-by: Ivan Blinkov --- ydb/docs/en/core/reference/ydb-cli/sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 263e3d8182aa..4f89da306830 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -129,7 +129,7 @@ ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice cat diagnostics.json ``` -If you want to collect diagnostics related to a query plan without actually executing the query, you can execute an query with `EXPLAIN` mode instead by adding the `--explain` option: +If you want to collect diagnostics related to a query plan without executing the query, run it in `EXPLAIN` mode by adding the `--explain` option: ```bash ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json From ff5986202bd227b77d0277ff81b4a92714ddcca5 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 17 Jun 2025 21:37:37 +0300 Subject: [PATCH 16/22] Update ydb/docs/en/core/reference/ydb-cli/sql.md Co-authored-by: Ivan Blinkov --- ydb/docs/en/core/reference/ydb-cli/sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 4f89da306830..95b64a5f4443 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -121,7 +121,7 @@ Command output: You can find examples of passing parameters to queries in the [article on how to pass parameters to `{{ ydb-cli }} sql`](parameterized-query-execution.md). -Сommand to collect diagnostics in the `diagnostics.json` file and check its contents: +Command to collect diagnostics in the `diagnostics.json` file and inspect its contents: ```bash ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" \ From 6b55eb9f864ba68071708d3c8579e87b5b44a97a Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 17 Jun 2025 21:38:01 +0300 Subject: [PATCH 17/22] Update ydb/docs/en/core/reference/ydb-cli/sql.md Co-authored-by: Ivan Blinkov --- ydb/docs/en/core/reference/ydb-cli/sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 95b64a5f4443..21530fa4edcb 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -73,7 +73,7 @@ For each query, a file named `` will be created with the fo {% note tip %} -The diagnostics file may contain confidential information, especially in the `meta.query_text`, `plan`, and `ast` fields. Before sharing this file with third parties (e.g., technical support), it is recommended to carefully review and edit its contents to remove or replace any sensitive data. +The diagnostics file may contain confidential information, especially in the `meta.query_text`, `plan`, and `ast` fields. Before sharing it with third parties (for example, technical support), carefully review and edit the file to remove or replace any sensitive data. {% endnote %} From d6fa1d30131b332e25da160c448457fb2dfc21bc Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 17 Jun 2025 21:42:08 +0300 Subject: [PATCH 18/22] Apply suggestions from code review Co-authored-by: Ivan Blinkov --- ydb/docs/en/core/reference/ydb-cli/sql.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 21530fa4edcb..99b29d89ee67 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -29,7 +29,7 @@ View the description of this command by calling it with `--help` option: || `--explain` | Execute an explain request for the query. Displays the query's logical plan. The query is not actually executed and does not affect database data. || || `--explain-ast` | Same as `--explain`, but in addition to the query's logical plan, an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) is printed. The AST section contains a representation in the internal [miniKQL](../../concepts/glossary.md#minikql) language. || || `--explain-analyze` | Execute the query in `EXPLAIN ANALYZE` mode. Displays the query execution plan. Query results are ignored.
**Important note: The query is actually executed, so any changes will be applied to the database**. || -|| `--diagnostics-file` | Path to file where the diagnostics will be saved. || +|| `--diagnostics-file` | Path to a file where the [diagnostics](#diagnostics-collection) will be saved. || || `--format` | Output format.
Available options: {% include notitle [format](./_includes/result_format_common.md) %} @@ -39,11 +39,11 @@ View the description of this command by calling it with `--help` option: || |# -### Diagnostics collection +### Diagnostics collection {#diagnostics-collection} -The `--diagnostics-file ` option allows you to save extended information about SQL query execution to a separate JSON file. +The `--diagnostics-file ` option saves extended information about SQL query execution to a separate JSON file. -For each query, a file named `` will be created with the following fields: +Each query generates a file named `` containing the following fields: - `plan` — query execution plan. - `stats` — query execution statistics. @@ -71,7 +71,7 @@ For each query, a file named `` will be created with the fo - `table_metadata` — schemas, indexes, and statistics of the tables involved in the query (JSON format). - `ast` — abstract syntax tree (AST) for the query. -{% note tip %} +{% note warning %} The diagnostics file may contain confidential information, especially in the `meta.query_text`, `plan`, and `ast` fields. Before sharing it with third parties (for example, technical support), carefully review and edit the file to remove or replace any sensitive data. From 7558cc299de3ea861d05f20fc701f8deef8bc631 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Wed, 25 Jun 2025 03:17:26 +0300 Subject: [PATCH 19/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 85 ++++++++++------------- ydb/docs/ru/core/reference/ydb-cli/sql.md | 83 ++++++++++------------ 2 files changed, 72 insertions(+), 96 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 99b29d89ee67..cb309c26cd20 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -43,39 +43,56 @@ View the description of this command by calling it with `--help` option: The `--diagnostics-file ` option saves extended information about SQL query execution to a separate JSON file. -Each query generates a file named `` containing the following fields: +Diagnostics for each query are saved to ``, overwriting the file if it already exists, and the file includes the following fields: -- `plan` — query execution plan. +- `plan` — query execution [plan](../../yql/query_plans.md). - `stats` — query execution statistics. -- `meta` — additional query information in JSON format, including the following fields: - - `created_at` — query start time (timestamp); - - `query_cluster` — cluster or provider name; - - `query_database` — database path; - - `query_id` — unique query identifier; - - `query_syntax` — query syntax used; +- `meta` — additional query information in JSON format, collected when statistics gathering is enabled with `--stats full` or in `EXPLAIN` queries (with `--explain`, `--explain-ast` or `--explain-analyze`), including the following fields: + - `created_at` — query start time (timestamp in seconds). + - `query_cluster` — cluster or provider name (always a constant). + - `query_database` — database path. + - `query_id` — unique query identifier. + - `query_syntax` — query syntax used, V1 syntax is the default. Experimental PostgreSQL syntax is also available. - `query_text` — SQL query text. + - `query_type` — query type, possible values: `QUERY_TYPE_SQL_GENERIC_QUERY`, `QUERY_TYPE_SQL_GENERIC_CONCURRENT_QUERY`. + - `table_metadata` — a list of Protobuf descriptions (serialized to JSON) for all tables included in the query. Each entry contains the table schema, indexes, and statistics, all originally in Protobuf format. +- `ast` — abstract syntax tree [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) for the query. - {% note info %} +{% note warning %} - `meta` are collected when statistics gathering is enabled `--stats full`, as well as during execution of queries with `EXPLAIN` mode. +The diagnostics file may contain confidential information and sensitive data, especially in the `meta.query_text`, `plan`, and `ast` fields. Before sharing it with third parties (for example, technical support), carefully review and edit the file to remove or replace any sensitive data. - {% endnote %} +{% endnote %} - {% note warning %} +#### Example - This field may contain sensitive or personal data, including parameter values. +Command to collect diagnostics in the `diagnostics.json` file and inspect its contents: - {% endnote %} +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" \ +--stats full --diagnostics-file diagnostics.json +cat diagnostics.json +``` - - `query_type` — query type; - - `table_metadata` — schemas, indexes, and statistics of the tables involved in the query (JSON format). -- `ast` — abstract syntax tree (AST) for the query. +If you want to collect diagnostics related to a query plan without executing the query, run it in `EXPLAIN` mode by adding the `--explain` option: -{% note warning %} +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json +``` -The diagnostics file may contain confidential information, especially in the `meta.query_text`, `plan`, and `ast` fields. Before sharing it with third parties (for example, technical support), carefully review and edit the file to remove or replace any sensitive data. +In the `diagnostics.json` file, in the `meta.query_text` field, the following string will appear: -{% endnote %} +```json +"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" +``` + +This contains sensitive information, such as a user’s email address. Before sharing the diagnostics file, replace actual values with placeholders: + +```json +"query_text": "SELECT * FROM users WHERE email = '';" +``` + +In this example, the email address can also be found in fields such as `plan` and `ast`, such entries should also be replaced. ### Working with parameterized queries {#parameterized-query} @@ -120,31 +137,3 @@ Command output: ``` You can find examples of passing parameters to queries in the [article on how to pass parameters to `{{ ydb-cli }} sql`](parameterized-query-execution.md). - -Command to collect diagnostics in the `diagnostics.json` file and inspect its contents: - -```bash -ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" \ ---stats full --diagnostics-file diagnostics.json -cat diagnostics.json -``` - -If you want to collect diagnostics related to a query plan without executing the query, run it in `EXPLAIN` mode by adding the `--explain` option: - -```bash -ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json -``` - -In the `diagnostics.json` file, in the `meta.query_text` field, the following string will appear: - -```json -"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" -``` - -This contains sensitive information, such as a user’s email address. Before sharing the diagnostics file, replace actual values with placeholders: - -```json -"query_text": "SELECT * FROM users WHERE email = '';" -``` - -In this example, the email address can also be found in fields such as `plan` and `ast`, such entries should also be replaced. diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index df9dedeafae1..fd0a357d6e29 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -39,43 +39,60 @@ || |# -### Сбор диагностики +### Сбор диагностики {#diagnostics-collection} Опция `--diagnostics-file ` позволяет сохранять расширенную информацию о выполнении SQL-запросов в отдельный JSON-файл. Диагностика формируется при сборе статистики `--stats full`, а также при выполнении `EXPLAIN`-запросов. Для каждого запроса будет создан файл `` со следующими полями: -- `plan` — план выполнения запроса. +- `plan` — [план](../../yql/query_plans.md) выполнения запроса. - `stats` — статистика выполнения запроса. -- `meta` — дополнительная информация о запросе в JSON-формате со следующими полями: - - `created_at` — время начала запроса (timestamp). - - `query_cluster` — название кластера или провайдера. +- `meta` — дополнительная информация о запросе в JSON-формате, формируется при сборе статистики `--stats full`, а также при выполнении `EXPLAIN`-запросов (`--explain`, `--explain-ast` или `--explain-analyze`), включает следующие поля: + - `created_at` — время начала запроса (timestamp в секундах). + - `query_cluster` — название кластера или провайдера (всегда константа). - `query_database` — путь к базе данных. - `query_id` — уникальный идентификатор запроса. - - `query_syntax` — используемый синтаксис запроса. + - `query_syntax` — используемый синтаксис запроса; по умолчанию используется синтаксис V1. Также доступен экспериментальный синтаксис PostgreSQL. - `query_text` — текст SQL-запроса. + - `query_type` — тип запроса, возможные значения: `QUERY_TYPE_SQL_GENERIC_QUERY`, `QUERY_TYPE_SQL_GENERIC_CONCURRENT_QUERY`. + - `table_metadata` — список Protobuf-описаний (сериализованных в JSON) для всех таблиц, участвующих в запросе. Каждый элемент списка содержит описание схемы таблицы, индексов и статистики, все эти поля изначально представлены в формате Protobuf. +- `ast` — абстрактное синтаксическое дерево [AST](https://ru.wikipedia.org/wiki/Абстрактное_синтаксическое_дерево) запроса. - {% note info %} +{% note warning %} - `meta` формируется при сборе статистики `--stats full`, а также при выполнении `EXPLAIN`-запросов. +Файл диагностики может содержать конфиденциальные данные и чувствительную информацию, особенно в полях `meta.query_text`, `plan` и `ast`. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. - {% endnote %} +{% endnote %} - {% note warning %} +#### Пример - Это поле может содержать чувствительные или личные данные пользователя, включая значения параметров в запросе. +Команда, чтобы собрать диагностику в файл `diagnostics.json` и проверить его содержимое: - {% endnote %} +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" \ +--stats full --diagnostics-file diagnostics.json +cat diagnostics.json +``` - - `query_type` — тип запроса. - - `table_metadata` — схемы, индексы и статистика по таблицам, участвующим в запросе (JSON-формат). -- `ast` — абстрактное синтаксическое дерево (AST) запроса. +Если вы хотите получить диагностические данные, относящиеся к плану запроса, без фактического выполнения запроса, вы можете вместо этого выполнить `EXPLAIN`-запрос, добавив опцию `--explain`: -{% note tip %} +```bash +ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json +``` -Файл диагностики может содержать конфиденциальные данные, особенно в полях `meta.query_text`, `plan` и `ast`. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. +В диагностическом файле `diagnostics.json` в поле `meta.query_text` будет содержаться такая строка: -{% endnote %} +```json +"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" +``` + +Здесь присутствует чувствительная информация — адрес электронной почты пользователя. Перед передачей диагностического файла рекомендуется заменить реальные значения на шаблонные: + +```json +"query_text": "SELECT * FROM users WHERE email = '';" +``` + +В данном примере адрес электронной почты можно обнаружить в полях `plan` и `ast`, такие вхождения тоже нужно заменить. ### Работа с параметризованными запросами {#parameterized-query} @@ -120,33 +137,3 @@ ``` Примеры передачи параметров в скрипты приведены в [статье о передаче параметров в команды исполнения запросов](parameterized-query-execution.md). - -Пример команды, чтобы собрать диагностику в файл `diagnostics.json` и проверить его содержимое: - -```bash -ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" \ ---stats full --diagnostics-file diagnostics.json -cat diagnostics.json -``` - -Если вы хотите получить диагностические данные, относящиеся к плану запроса, без фактического выполнения запроса, вы можете вместо этого выполнить `EXPLAIN`-запрос, добавив опцию `--explain`: - -```bash -ydb -e -d sql -s "SELECT * FROM users WHERE email = 'alice@example.com';" --explain --diagnostics-file diagnostics.json -``` - -В диагностическом файле `diagnostics.json` в поле `meta.query_text` будет содержаться такая строка: - -```json -"query_text": "SELECT * FROM users WHERE email = 'alice@example.com';" -``` - -Здесь присутствует чувствительная информация — адрес электронной почты пользователя. - -Перед передачей диагностического файла рекомендуется заменить реальные значения на шаблонные: - -```json -"query_text": "SELECT * FROM users WHERE email = '';" -``` - -В данном примере адрес электронной почты можно обнаружить в полях `plan` и `ast`, такие вхождения тоже нужно заменить. From 437252cd0d7f7a89ed6669d6d5077bc4caccc438 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Wed, 25 Jun 2025 21:02:00 +0300 Subject: [PATCH 20/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 92 +++++++++++++++++++++++ ydb/docs/ru/core/reference/ydb-cli/sql.md | 91 ++++++++++++++++++++++ 2 files changed, 183 insertions(+) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index cb309c26cd20..c52190b867c8 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -56,8 +56,100 @@ Diagnostics for each query are saved to ``, overwriting the - `query_text` — SQL query text. - `query_type` — query type, possible values: `QUERY_TYPE_SQL_GENERIC_QUERY`, `QUERY_TYPE_SQL_GENERIC_CONCURRENT_QUERY`. - `table_metadata` — a list of Protobuf descriptions (serialized to JSON) for all tables included in the query. Each entry contains the table schema, indexes, and statistics, all originally in Protobuf format. + + {% cut "Example of table description in table_metadata" %} + + ```json + { + "DoesExist": true, + "Cluster": "db", + "Name": "/local/users", + "SysView": "", + "PathId": { + "OwnerId": 72075186232723360, + "TableId": 33 + }, + "SchemaVersion": 1, + "Kind": 1, + "Columns": [ + { + "Name": "emails", + "Id": 3, + "Type": "Utf8", + "TypeId": 4608, + "NotNull": false, + "DefaultFromSequence": "", + "DefaultKind": 0, + "DefaultFromLiteral": {}, + "IsBuildInProgress": false, + "DefaultFromSequencePathId": { + "OwnerId": 18446744073709551615, + "TableId": 18446744073709551615 + } + }, + { + "Name": "id", + "Id": 1, + "Type": "Int32", + "TypeId": 1, + "NotNull": false, + "DefaultFromSequence": "", + "DefaultKind": 0, + "DefaultFromLiteral": {}, + "IsBuildInProgress": false, + "DefaultFromSequencePathId": { + "OwnerId": 18446744073709551615, + "TableId": 18446744073709551615 + } + }, + { + "Name": "name", + "Id": 2, + "Type": "Utf8", + "TypeId": 4608, + "NotNull": false, + "DefaultFromSequence": "", + "DefaultKind": 0, + "DefaultFromLiteral": {}, + "IsBuildInProgress": false, + "DefaultFromSequencePathId": { + "OwnerId": 18446744073709551615, + "TableId": 18446744073709551615 + } + } + ], + "KeyColunmNames": [ + "id" + ], + "RecordsCount": 0, + "DataSize": 0, + "StatsLoaded": false + } + ``` + + {% endcut %} + - `ast` — abstract syntax tree [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) for the query. + {% cut "Example of ast" %} + + ```json + ( + (let (KqpTable '"/local/users" '"72075186232723360:33" '"" '1)) + (let '('"emails" '"id" '"name")) + (let (KqpRowsSourceSettings '() (Void) '())) + (let (DqPhyStage '((DqSource (DataSource '"KqpReadRangesSource") )) (lambda '() (FromFlow (Filter (ToFlow ) (lambda '(0) (Coalesce (== (Member 0 '"emails") (String '"john@example.com")) (Bool 'false)))))) '('('"_logical_id" '401) '('"_id" '"45d03f9b-f40c98ba-b6705ab-90ee6ea")))) + (let (DqCnUnionAll (TDqOutput '"0"))) + (let (DqPhyStage '() (lambda '(1) 1) '('('"_logical_id" '477) '('"_id" '"28936ac-4af296f3-7afa38af-7dc0798")))) + (let (DqCnResult (TDqOutput '"0") '())) + (let (OptionalType (DataType 'Utf8))) + (return (KqpPhysicalQuery '((KqpPhysicalTx '( ) '() '() '('('"type" '"generic")))) '((KqpTxResultBinding (ListType (StructType '('"emails" ) '('"id" (OptionalType (DataType 'Int32))) '('"name" ))) '"0" '"0")) '('('"type" '"query")))) + ) + ``` + + {% endcut %} + + {% note warning %} The diagnostics file may contain confidential information and sensitive data, especially in the `meta.query_text`, `plan`, and `ast` fields. Before sharing it with third parties (for example, technical support), carefully review and edit the file to remove or replace any sensitive data. diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index fd0a357d6e29..dee6c7d6df80 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -56,8 +56,99 @@ - `query_text` — текст SQL-запроса. - `query_type` — тип запроса, возможные значения: `QUERY_TYPE_SQL_GENERIC_QUERY`, `QUERY_TYPE_SQL_GENERIC_CONCURRENT_QUERY`. - `table_metadata` — список Protobuf-описаний (сериализованных в JSON) для всех таблиц, участвующих в запросе. Каждый элемент списка содержит описание схемы таблицы, индексов и статистики, все эти поля изначально представлены в формате Protobuf. + + {% cut "Пример описания таблицы в table_metadata" %} + + ```json + { + "DoesExist": true, + "Cluster": "db", + "Name": "/local/users", + "SysView": "", + "PathId": { + "OwnerId": 72075186232723360, + "TableId": 33 + }, + "SchemaVersion": 1, + "Kind": 1, + "Columns": [ + { + "Name": "emails", + "Id": 3, + "Type": "Utf8", + "TypeId": 4608, + "NotNull": false, + "DefaultFromSequence": "", + "DefaultKind": 0, + "DefaultFromLiteral": {}, + "IsBuildInProgress": false, + "DefaultFromSequencePathId": { + "OwnerId": 18446744073709551615, + "TableId": 18446744073709551615 + } + }, + { + "Name": "id", + "Id": 1, + "Type": "Int32", + "TypeId": 1, + "NotNull": false, + "DefaultFromSequence": "", + "DefaultKind": 0, + "DefaultFromLiteral": {}, + "IsBuildInProgress": false, + "DefaultFromSequencePathId": { + "OwnerId": 18446744073709551615, + "TableId": 18446744073709551615 + } + }, + { + "Name": "name", + "Id": 2, + "Type": "Utf8", + "TypeId": 4608, + "NotNull": false, + "DefaultFromSequence": "", + "DefaultKind": 0, + "DefaultFromLiteral": {}, + "IsBuildInProgress": false, + "DefaultFromSequencePathId": { + "OwnerId": 18446744073709551615, + "TableId": 18446744073709551615 + } + } + ], + "KeyColunmNames": [ + "id" + ], + "RecordsCount": 0, + "DataSize": 0, + "StatsLoaded": false + } + ``` + + {% endcut %} + - `ast` — абстрактное синтаксическое дерево [AST](https://ru.wikipedia.org/wiki/Абстрактное_синтаксическое_дерево) запроса. + {% cut "Пример ast" %} + + ```json + ( + (let (KqpTable '"/local/users" '"72075186232723360:33" '"" '1)) + (let '('"emails" '"id" '"name")) + (let (KqpRowsSourceSettings '() (Void) '())) + (let (DqPhyStage '((DqSource (DataSource '"KqpReadRangesSource") )) (lambda '() (FromFlow (Filter (ToFlow ) (lambda '(0) (Coalesce (== (Member 0 '"emails") (String '"john@example.com")) (Bool 'false)))))) '('('"_logical_id" '401) '('"_id" '"45d03f9b-f40c98ba-b6705ab-90ee6ea")))) + (let (DqCnUnionAll (TDqOutput '"0"))) + (let (DqPhyStage '() (lambda '(1) 1) '('('"_logical_id" '477) '('"_id" '"28936ac-4af296f3-7afa38af-7dc0798")))) + (let (DqCnResult (TDqOutput '"0") '())) + (let (OptionalType (DataType 'Utf8))) + (return (KqpPhysicalQuery '((KqpPhysicalTx '( ) '() '() '('('"type" '"generic")))) '((KqpTxResultBinding (ListType (StructType '('"emails" ) '('"id" (OptionalType (DataType 'Int32))) '('"name" ))) '"0" '"0")) '('('"type" '"query")))) + ) + ``` + + {% endcut %} + {% note warning %} Файл диагностики может содержать конфиденциальные данные и чувствительную информацию, особенно в полях `meta.query_text`, `plan` и `ast`. Перед передачей такого файла сторонним лицам (например, в техническую поддержку) рекомендуется вручную просмотреть и отредактировать содержимое файла, чтобы удалить или заменить чувствительную информацию. From 39b7f6906853d05686a3ae2756ea29613123a9bf Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 26 Jun 2025 03:35:12 +0300 Subject: [PATCH 21/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 2 +- ydb/docs/ru/core/reference/ydb-cli/sql.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index c52190b867c8..3aa11f4ded41 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -133,7 +133,7 @@ Diagnostics for each query are saved to ``, overwriting the {% cut "Example of ast" %} - ```json + ``` ( (let (KqpTable '"/local/users" '"72075186232723360:33" '"" '1)) (let '('"emails" '"id" '"name")) diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index dee6c7d6df80..ddf123bcd69e 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -133,7 +133,7 @@ {% cut "Пример ast" %} - ```json + ``` ( (let (KqpTable '"/local/users" '"72075186232723360:33" '"" '1)) (let '('"emails" '"id" '"name")) From f044cf2f1e6ed170e65f20e44451cb9579e0a318 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Fri, 27 Jun 2025 13:19:39 +0300 Subject: [PATCH 22/22] Fixes --- ydb/docs/en/core/reference/ydb-cli/sql.md | 2 +- ydb/docs/ru/core/reference/ydb-cli/sql.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/sql.md b/ydb/docs/en/core/reference/ydb-cli/sql.md index 3aa11f4ded41..ac98e83587cb 100644 --- a/ydb/docs/en/core/reference/ydb-cli/sql.md +++ b/ydb/docs/en/core/reference/ydb-cli/sql.md @@ -133,7 +133,7 @@ Diagnostics for each query are saved to ``, overwriting the {% cut "Example of ast" %} - ``` + ```text ( (let (KqpTable '"/local/users" '"72075186232723360:33" '"" '1)) (let '('"emails" '"id" '"name")) diff --git a/ydb/docs/ru/core/reference/ydb-cli/sql.md b/ydb/docs/ru/core/reference/ydb-cli/sql.md index ddf123bcd69e..54040741e8c8 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/sql.md +++ b/ydb/docs/ru/core/reference/ydb-cli/sql.md @@ -133,7 +133,7 @@ {% cut "Пример ast" %} - ``` + ```text ( (let (KqpTable '"/local/users" '"72075186232723360:33" '"" '1)) (let '('"emails" '"id" '"name"))