YQ-4704 External data source config docs (#25934)

Co-authored-by: Vitaly Isaev <[email protected]>
Co-authored-by: orange13 <[email protected]>
Co-authored-by: Ilnaz Nizametdinov <[email protected]>

7 files changed, 137 insertions, 19 deletions

diff --git a/ydb/docs/en/core/concepts/federated_query/_includes/connector_deployment.md b/ydb/docs/en/core/concepts/federated_query/_includes/connector_deployment.md
index 94925ba4d01..ffbb371f1d0 100644
--- a/ydb/docs/en/core/concepts/federated_query/_includes/connector_deployment.md
+++ b/ydb/docs/en/core/concepts/federated_query/_includes/connector_deployment.md
@@ -1 +1 @@
-{% if oss == "true" %}Deploy the [connector](../architecture.md#connectors) {% else %}Deploy the connector{% endif %} and {% if oss == "true" %}[configure](../../../devops/deployment-options/manual/federated-queries/index.md) {% else %}configure{% endif %} the {{ ydb-short-name }} dynamic nodes to interact with it. Additionally, ensure network access from the {{ ydb-short-name }} dynamic nodes to the external data source (at the address specified in the `LOCATION` parameter of the `CREATE EXTERNAL DATA SOURCE` request). If network connection encryption to the external source was enabled in the previous step, the connector will use the system's root certificates. More details on TLS configuration can be found in the [guide](../../../devops/deployment-options/manual/federated-queries/connector-deployment.md) on deploying the connector.
+{% if oss == true %}Deploy the [connector](../architecture.md#connectors) {% else %}Deploy the connector{% endif %} and {% if oss == true %}[configure](../../../devops/deployment-options/manual/federated-queries/index.md) {% else %}configure{% endif %} the {{ ydb-short-name }} dynamic nodes to interact with it. Additionally, ensure network access from the {{ ydb-short-name }} dynamic nodes to the external data source (at the address specified in the `LOCATION` parameter of the `CREATE EXTERNAL DATA SOURCE` request). If network connection encryption to the external source was enabled in the previous step, the connector will use the system's root certificates. More details on TLS configuration can be found in the [guide](../../../devops/deployment-options/manual/federated-queries/connector-deployment.md) on deploying the connector.
diff --git a/ydb/docs/ru/core/concepts/federated_query/_includes/connector_deployment.md b/ydb/docs/ru/core/concepts/federated_query/_includes/connector_deployment.md
index bf6f3bf2cde..7c6a3e0fcc4 100644
--- a/ydb/docs/ru/core/concepts/federated_query/_includes/connector_deployment.md
+++ b/ydb/docs/ru/core/concepts/federated_query/_includes/connector_deployment.md
@@ -1 +1 @@
- {% if oss == "true" %}Развернуть [коннектор](../architecture.md#connectors) {% else %}Развернуть коннектор{% endif %} и {% if oss == "true" %}[настроить](../../../devops/deployment-options/manual/federated-queries/index.md) {% else %}настроить{% endif %} динамические узлы {{ ydb-short-name }} на взаимодействие с ним. Также необходимо обеспечить сетевой доступ с динамических узлов {{ ydb-short-name }} к внешнему источнику данных (по адресу, указанному в параметре `LOCATION` запроса `CREATE EXTERNAL DATA SOURCE`). В случае, если на предыдущем шаге было включено шифрование сетевых соединений к внешнему источнику, коннектор будет использовать системные корневые сертификаты (более подробно о настройке TLS можно узнать в [инструкции](../../../devops/deployment-options/manual/federated-queries/connector-deployment.md) по разворачиванию коннектора).
+ {% if oss == true %}Развернуть [коннектор](../architecture.md#connectors) {% else %}Развернуть коннектор{% endif %} и {% if oss == true %}[настроить](../../../devops/deployment-options/manual/federated-queries/index.md) {% else %}настроить{% endif %} динамические узлы {{ ydb-short-name }} на взаимодействие с ним. Также необходимо обеспечить сетевой доступ с динамических узлов {{ ydb-short-name }} к внешнему источнику данных (по адресу, указанному в параметре `LOCATION` запроса `CREATE EXTERNAL DATA SOURCE`). В случае, если на предыдущем шаге было включено шифрование сетевых соединений к внешнему источнику, коннектор будет использовать системные корневые сертификаты (более подробно о настройке TLS можно узнать в [инструкции](../../../devops/deployment-options/manual/federated-queries/connector-deployment.md) по разворачиванию коннектора).
diff --git a/ydb/docs/ru/core/devops/deployment-options/manual/federated-queries/index.md b/ydb/docs/ru/core/devops/deployment-options/manual/federated-queries/index.md
index 51e8267d02c..8892e6f9533 100644
--- a/ydb/docs/ru/core/devops/deployment-options/manual/federated-queries/index.md
+++ b/ydb/docs/ru/core/devops/deployment-options/manual/federated-queries/index.md
@@ -35,30 +35,50 @@
 
 1. Выполните шаги инструкции по развёртыванию динамического узла {{ ydb-short-name }} до [подготовки конфигурационных файлов](../initial-deployment.md#config) включительно.
 2. Если для доступа к нужному вам источнику требуется развернуть коннектор, сделайте это [согласно инструкции](./connector-deployment.md).
-3. Если для доступа к нужному вам источнику трубуется развернуть коннектор, в конфигурационном файле {{ ydb-short-name }} в секции `query_service_config` добавьте подсекцию `generic` по приведённому ниже образцу. В полях `connector.endpoint.host` и `connector.endpoint.port` укажите сетевой адрес коннектора (по умолчанию `localhost` и `2130`). При совместном размещении коннектора и динамического узла {{ ydb-short-name }} на одном сервере установка шифрованных соединений между ними *не требуется*, но в случае необходимости вы можете включить шифрование, передав значение `true` в поле `connector.use_ssl` и указав путь до сертификата CA, использованного для подписи TLS-ключей коннектора, в `connector.ssl_ca_crt`:
+3. [В конфигурационном файле](../../../../reference/configuration/index.md) {{ ydb-short-name }} в секции `feature_flags` включите флаг `enable_external_data_sources`:
+
+```yaml
+feature_flags:
+  enable_external_data_sources: true
+```
+
+4. [В конфигурационный файл](../../../../reference/configuration/index.md) {{ ydb-short-name }} добавьте [настройки внешних источников данных](../../../../reference/configuration/query_service_config.md).
+
+{% list tabs %}
+
+- Без использования коннектора
 
     ```yaml
     query_service_config:
-        generic:
-            connector:
-                endpoint:
-                    host: localhost                 # имя хоста, где развернут коннектор
-                    port: 2130                      # номер порта для слушающего сокета коннектора
-                use_ssl: false                      # флаг, включающий шифрование соединений
-                ssl_ca_crt: "/opt/ydb/certs/ca.crt" # (опционально) путь к сертификату CA
-            default_settings:
-                - name: DateTimeFormat
-                  value: string
-                - name: UsePredicatePushdown
-                  value: "true"
+      generic:
+        default_settings:
+        - name: UsePredicatePushdown
+          value: "true"
+      all_external_data_sources_are_available: false
+      available_external_data_sources:
+      - ObjectStorage
     ```
 
-4. В конфигурационном файле {{ ydb-short-name }} добавьте секцию `feature_flags` следующего содержания:
+- С использованием коннектора
 
     ```yaml
-    feature_flags:
-        enable_external_data_sources: true
-        enable_script_execution_operations: true
+    query_service_config:
+      generic:
+        connector:
+          endpoint:
+            host: localhost                   # имя хоста, где развернут коннектор
+            port: 2130                        # номер порта коннектора
+          use_ssl: false                      # флаг, включающий шифрование соединений
+          ssl_ca_crt: "/opt/ydb/certs/ca.crt" # путь к сертификату CA
+        default_settings:
+        - name: UsePredicatePushdown
+          value: "true"
+      all_external_data_sources_are_available: false
+      available_external_data_sources:
+      - ClickHouse
+      - MySQL
     ```
 
+{% endlist %}
+
 5. Продолжайте развёртывание динамического узла {{ ydb-short-name }} по [инструкции](../initial-deployment.md).
diff --git a/ydb/docs/ru/core/reference/configuration/feature_flags.md b/ydb/docs/ru/core/reference/configuration/feature_flags.md
index 1d6b4b999a8..562c77e89b3 100644
--- a/ydb/docs/ru/core/reference/configuration/feature_flags.md
+++ b/ydb/docs/ru/core/reference/configuration/feature_flags.md
@@ -26,3 +26,5 @@ feature_flags:
 | `enable_kafka_native_balancing`                          | Клиентская балансировка партиций при чтении по [протоколу Kafka](https://kafka.apache.org/documentation/#consumerconfigs_partition.assignment.strategy) |
 | `enable_topic_compactification_by_key`                   | Включение компактификации топиков в [YDB Topics Kafka API](../../reference/kafka-api/index.md)|
 | `enable_kafka_transactions`                              | Включение транзакций в [YDB Topics Kafka API](../../reference/kafka-api/index.md)|
+| `enable_external_data_sources`                           | Включение [внешних источников данных](../../concepts/datamodel/external_data_source.md)|
+
diff --git a/ydb/docs/ru/core/reference/configuration/index.md b/ydb/docs/ru/core/reference/configuration/index.md
index 57987606294..d82bf566200 100644
--- a/ydb/docs/ru/core/reference/configuration/index.md
+++ b/ydb/docs/ru/core/reference/configuration/index.md
@@ -23,6 +23,7 @@
 || [{#T}](log_config.md) | Нет | Конфигурация и параметры логирования ||
 || [{#T}](memory_controller_config.md) | Нет | Распределение памяти и лимиты для компонентов базы данных ||
 || [{#T}](node_broker_config.md) | Нет | Конфигурация стабильных имен узлов ||
+|| [{#T}](query_service_config.md) | Нет | Конфигурация внешних источников для федеративных запросов ||
 || [{#T}](resource_broker_config.md) | Нет | Брокер ресурсов для контроля потребления CPU и памяти ||
 || [{#T}](security_config.md) | Нет | Настройки конфигурации безопасности ||
 || [{#T}](table_service_config.md) | Нет | Настройки конфигурации выполнения запросов||
diff --git a/ydb/docs/ru/core/reference/configuration/query_service_config.md b/ydb/docs/ru/core/reference/configuration/query_service_config.md
new file mode 100644
index 00000000000..49a16840a9b
--- /dev/null
+++ b/ydb/docs/ru/core/reference/configuration/query_service_config.md
@@ -0,0 +1,93 @@
+# query_service_config
+
+Секция `query_service_config` описывает параметры работы {{ ydb-short-name }} с внешними источниками данных с использованием [федеративных запросов](../../concepts/federated_query/index.md).
+
+Если для доступа к нужному вам источнику требуется развернуть [коннектор](../../concepts/federated_query/architecture.md#connectors), его необходимо также настроить по [инструкции](../../devops/deployment-options/manual/federated-queries/connector-deployment.md).
+
+## Описание параметров
+
+#|
+|| **Параметр** | **Значение по умолчанию** | **Описание**  ||
+|| `generic.connector.endpoint.host`
+| `localhost`
+|  Имя хоста коннектора.
+||
+|| `generic.connector.endpoint.port`
+| `2130`
+| TCP порт коннектора.
+||
+|| `generic.connector.use_ssl`
+| `false`
+| Использовать ли шифрование соединения. При размещении коннектора и динамического узла {{ ydb-short-name }} на одном сервере шифрованное соединение между ними не требуется, но при необходимости его можно включить.
+||
+|| `generic.connector.ssl_ca_crt`
+| пустая строка
+| Путь к сертификату CA, который используется для шифрования.
+||
+|| `generic.default_settings.name.UsePredicatePushdown`
+| `false`
+| Включает пушдаун предикатов во внешние источники данных: некоторые части SQL-запросов (например, фильтры) будут переданы на исполнение во внешний источник. Это позволит существенно снизить объёмы данных, передаваемых по сети источником данных в сторону федеративной {{ ydb-short-name }}, сэкономить её вычислительные ресурсы и значительно уменьшить время обработки федеративного запроса.
+||
+|| `available_external_data_sources`
+| пустой список
+| Список с разрешенными типами внешних источников. Применяется при `all_external_data_sources_are_available: false`. 
+
+Возможные значения:
+
+* `ObjectStorage`;
+* `ClickHouse`;
+* `PostgreSQL`;
+* `MySQL`;
+* `Greenplum`;
+* `MsSQLServer`;
+* `Ydb`.
+
+||
+|| `all_external_data_sources_are_available`
+| `false`
+| Включение всех типов внешних источников. Если включено, настройка `available_external_data_sources` игнорируется.
+||
+|#
+
+## Примеры {#examples}
+
+### Включение внешних источников ClickHouse и MySQL
+
+```yaml
+query_service_config:
+  generic:
+    connector:
+      endpoint:
+        host: localhost                   # имя хоста, где развернут коннектор
+        port: 2130                        # номер порта коннектора
+      use_ssl: false                      # флаг, включающий шифрование соединений
+      ssl_ca_crt: "/opt/ydb/certs/ca.crt" # путь к сертификату CA
+    default_settings:
+    - name: UsePredicatePushdown
+      value: "true"
+  all_external_data_sources_are_available: false
+  available_external_data_sources:
+  - ClickHouse
+  - MySQL
+```
+
+### Включение всех типов внешних источников
+
+```yaml
+query_service_config:
+  generic:
+    connector:
+      endpoint:
+        host: localhost                   # имя хоста, где развернут коннектор
+        port: 2130                        # номер порта коннектора
+      use_ssl: false                      # флаг, включающий шифрование соединений
+      ssl_ca_crt: "/opt/ydb/certs/ca.crt" # путь к сертификату CA
+    default_settings:
+    - name: UsePredicatePushdown
+      value: "true"
+  all_external_data_sources_are_available: true
+```
+
+## См. также
+
+- [{#T}](../../devops/deployment-options/manual/federated-queries/index.md)
diff --git a/ydb/docs/ru/core/reference/configuration/toc_p.yaml b/ydb/docs/ru/core/reference/configuration/toc_p.yaml
index 3ebd3eb6f0a..605a6bd49ea 100644
--- a/ydb/docs/ru/core/reference/configuration/toc_p.yaml
+++ b/ydb/docs/ru/core/reference/configuration/toc_p.yaml
@@ -13,6 +13,8 @@ items:
   href: domains_config.md
 - name: feature_flags
   href: feature_flags.md
+- name: query_service_config
+  href: query_service_config.md
 - name: healthcheck_config
   href: healthcheck_config.md
 - name: hive_config