YDB FQ: docs for YDB as an external datasource (#4790)

vitalyisaev2 · blinkov · web-flow · commit a64301b53d0c · 2024-06-04T19:20:01.000Z
Co-authored-by: Ivan Blinkov &lt;ivan@ydb.tech&gt;
diff --git a/ydb/docs/ru/core/concepts/_includes/index/how_it_works.md b/ydb/docs/ru/core/concepts/_includes/index/how_it_works.md
@@ -12,7 +12,7 @@
 
 Более подробная информация об общей архитектуре YDB объясняется в разделе [документации о кластерах YDB](../../cluster/index.md).
 
-### Иерархия
+### Иерархия {#ydb-hierarchy}
 
 ![Иерархия](https://storage.yandexcloud.net/ydb-www-prod-site-assets/howitworks/organization.png)
 
diff --git a/ydb/docs/ru/core/concepts/federated_query/_assets/architecture.png b/ydb/docs/ru/core/concepts/federated_query/_assets/architecture.png
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
@@ -0,0 +1 @@
+ {% if oss %}Развернуть [коннектор](../architecture.md#connectors) {% else %}Развернуть коннектор{% endif %} и [настроить](../../../deploy/manual/deploy-ydb-federated-query.md) динамические узлы {{ ydb-short-name }} на взаимодействие с ним. Также необходимо обеспечить сетевой доступ с динамических узлов {{ ydb-short-name }} к внешнему источнику данных (по адресу, указанному в параметре `LOCATION` запроса `CREATE EXTERNAL DATA SOURCE`). В случае, если на предыдущем шаге было включено шифрование сетевых соединений к внешнему источнику, коннектор будет использовать системные корневые сертификаты (более подробно о настройке TLS можно узнать в [инструкции](../../../deploy/manual/connector.md) по разворачиванию коннектора).
diff --git a/ydb/docs/ru/core/concepts/federated_query/_includes/datetime_limits.md b/ydb/docs/ru/core/concepts/federated_query/_includes/datetime_limits.md
@@ -1 +1 @@
-Если значение даты, хранящейся во внешнем источнике данных, находится вне допустимого для {{ ydb-short-name }} диапазона (все используемые даты должны быть позднее 1970-01-01, но ранее 2105-12-31), такое значение в интерфейсе YDB будет отображаться как `NULL`. 
+Если значение даты, хранящейся во внешнем источнике данных, находится вне допустимого для {{ ydb-short-name }} диапазона (все используемые даты должны быть позднее 1970-01-01, но ранее 2105-12-31), в {{ ydb-short-name }} такое значение будет преобразовано в `NULL`. 
diff --git a/ydb/docs/ru/core/concepts/federated_query/_includes/supported_requests.md b/ydb/docs/ru/core/concepts/federated_query/_includes/supported_requests.md
@@ -0,0 +1 @@
+Внешние источники доступны только для чтения данных через запросы `SELECT`. Запросы, модифицирующие таблицы во внешних источниках, движком обработки федеративных запросов в настоящее время не поддерживаются.
diff --git a/ydb/docs/ru/core/concepts/federated_query/architecture.md b/ydb/docs/ru/core/concepts/federated_query/architecture.md
@@ -34,3 +34,4 @@
 | [S3](https://aws.amazon.com/ru/s3/) | Встроенная в `ydbd` |
 | [ClickHouse](https://clickhouse.com/) | Через коннектор [fq-connector-go](../../deploy/manual/connector.md#fq-connector-go) |
 | [PostgreSQL](https://www.postgresql.org/) | Через коннектор [fq-connector-go](../../deploy/manual/connector.md#fq-connector-go) |
+| [{{ydb-short-name}}](https://ydb.tech/) | Через коннектор [fq-connector-go](../../deploy/manual/connector.md#fq-connector-go) |
diff --git a/ydb/docs/ru/core/concepts/federated_query/clickhouse.md b/ydb/docs/ru/core/concepts/federated_query/clickhouse.md
@@ -7,7 +7,7 @@
     ```sql
     CREATE OBJECT clickhouse_datasource_user_password (TYPE SECRET) WITH (value = "<password>");
     ```
-1. Создать [внешний источник данных](../datamodel/external_data_source.md), описывающий целевую базу данных внутри кластера ClickHouse.  Для соединения с ClickHouse можно использовать либо [нативный TCP-протокол](https://clickhouse.com/docs/ru/interfaces/tcp) (`PROTOCOL="NATIVE"`), либо [протокол HTTP](https://clickhouse.com/docs/ru/interfaces/http) (`PROTOCOL="HTTP"`).
+1. Создать [внешний источник данных](../datamodel/external_data_source.md), описывающий целевую базу данных внутри кластера ClickHouse. Для соединения с ClickHouse можно использовать либо [нативный TCP-протокол](https://clickhouse.com/docs/ru/interfaces/tcp) (`PROTOCOL="NATIVE"`), либо [протокол HTTP](https://clickhouse.com/docs/ru/interfaces/http) (`PROTOCOL="HTTP"`). Включить шифрование соединений к внешней базе данных можно с помощью параметра `USE_TLS="TRUE"`.
     ```sql
     CREATE EXTERNAL DATA SOURCE clickhouse_datasource WITH (
         SOURCE_TYPE="ClickHouse", 
@@ -20,7 +20,8 @@
         USE_TLS="TRUE"
     );
     ```
-1. Для корректного выполнения запроса необходимо {% if oss %} [развернуть коннектор](../../deploy/manual/deploy-ydb-federated-query.md) {% else %} развернуть коннектор и{% endif%} обеспечить сетевой доступ с динамических узлов {{ ydb-full-name }} к целевому кластеру ClickHouse.
+
+1. {% include [!](_includes/connector_deployment.md) %}
 1. [Выполнить запрос](#query) к базе данных.
 
 
@@ -39,7 +40,7 @@ SELECT * FROM clickhouse_datasource.<table_name>
 
 При работе с кластерами ClickHouse существует ряд ограничений:
 
-1. Поддерживаются только запросы чтения данных - `SELECT`, остальные виды запросов не поддерживаются.
+1. {% include [!](_includes/supported_requests.md) %}
 1. {% include [!](_includes/datetime_limits.md) %}
 1. {% include [!](_includes/predicate_pushdown.md) %}
 
diff --git a/ydb/docs/ru/core/concepts/federated_query/index.md b/ydb/docs/ru/core/concepts/federated_query/index.md
@@ -11,6 +11,7 @@
 Для работы с данными, хранящимися во внешних СУБД, достаточно создать [внешний источник данных](../datamodel/external_data_source.md). Для работы с несхематизированными данными, хранящимися в бакетах S3 нужно дополнительно создать [внешнюю таблицу](../datamodel/external_table.md). В обоих случаях необходимо предварительно создать объекты-[секреты](../datamodel/secrets.md), хранящие конфиденциальные данные, необходимые для аутентификации во внешних системах.
 
 Вы сможете узнать о внутреннем устройстве системы обработки федеративных запросов в разделе об [архитектуре](./architecture.md). Подробная информация про работу с различными источниками данных приведена в соответствующих разделах:
-- [ClickHouse](clickhouse.md).
-- [PostgreSQL](postgresql.md).
-- [S3](s3/external_table.md).
+- [ClickHouse](clickhouse.md)
+- [PostgreSQL](postgresql.md)
+- [{{ ydb-short-name }}](ydb.md)
+- [S3](s3/external_table.md)
diff --git a/ydb/docs/ru/core/concepts/federated_query/postgresql.md b/ydb/docs/ru/core/concepts/federated_query/postgresql.md
@@ -7,7 +7,7 @@
     ```sql
     CREATE OBJECT postgresql_datasource_user_password (TYPE SECRET) WITH (value = "<password>");
     ```
-1. Создать [внешний источник данных](../datamodel/external_data_source.md), описывающий определённую базу данных в составе кластера PostgreSQL. При чтении по умолчанию используется [пространство имен](https://www.postgresql.org/docs/current/catalog-pg-namespace.html) `public`, но это значение можно изменить с помощью опционального параметра `SCHEMA`. Сетевое подключение выполняется по стандартному ([Frontend/Backend Protocol](https://www.postgresql.org/docs/current/protocol.html)) по транспорту TCP (`PROTOCOL="NATIVE"`). При работе по защищенным TLS каналам связи используется системные сертификаты, расположенные на серверах {{ ydb-full-name }}. 
+1. Создать [внешний источник данных](../datamodel/external_data_source.md), описывающий определённую базу данных в составе кластера PostgreSQL. При чтении по умолчанию используется [пространство имен](https://www.postgresql.org/docs/current/catalog-pg-namespace.html) `public`, но это значение можно изменить с помощью опционального параметра `SCHEMA`. Сетевое подключение выполняется по стандартному ([Frontend/Backend Protocol](https://www.postgresql.org/docs/current/protocol.html)) по транспорту TCP (`PROTOCOL="NATIVE"`). Включить шифрование соединений к внешней базе данных можно с помощью параметра `USE_TLS="TRUE"`. 
     ```sql
     CREATE EXTERNAL DATA SOURCE postgresql_datasource WITH (
         SOURCE_TYPE="PostgreSQL",
@@ -21,7 +21,7 @@
         SCHEMA="<schema>"
     );
     ```
-1. Для корректного выполнения запроса необходимо {% if oss %} [развернуть коннектор](../../deploy/manual/deploy-ydb-federated-query.md) {% else %} развернуть коннектор и{% endif%} обеспечить сетевой доступ с динамических узлов {{ ydb-full-name }} к целевому кластеру PostgreSQL.
+1. {% include [!](_includes/connector_deployment.md) %}
 1. [Выполнить запрос](#query) к базе данных.
 
 ## Синтаксис запросов { #query }
@@ -39,7 +39,7 @@ SELECT * FROM postgresql_datasource.<table_name>
 
 При работе с кластерами PostgreSQL существует ряд ограничений:
 
-1. Поддерживаются только запросы чтения данных - `SELECT`, остальные виды запросов не поддерживаются.
+1. {% include [!](_includes/supported_requests.md) %}
 1. {% include [!](_includes/datetime_limits.md) %}
 1. {% include [!](_includes/predicate_pushdown.md) %}
 
diff --git a/ydb/docs/ru/core/concepts/federated_query/toc_i.yaml b/ydb/docs/ru/core/concepts/federated_query/toc_i.yaml
@@ -1,7 +1,8 @@
 items:
 - { name: Обзор,                                  href: index.md }
 - { name: Архитектура,                            href: architecture.md }
-- { name: Работа с базами данных PostgreSQL,      href: postgresql.md }
 - { name: Работа с базами данных ClickHouse,      href: clickhouse.md }
+- { name: Работа с базами данных PostgreSQL,      href: postgresql.md }
+- { name: Работа с базами данных YDB,             href: ydb.md }
 - name: Работа с бакетами S3
   include: { path: s3/toc_i.yaml, mode: link }
diff --git a/ydb/docs/ru/core/concepts/federated_query/ydb.md b/ydb/docs/ru/core/concepts/federated_query/ydb.md
@@ -0,0 +1,70 @@
+# Работа с базами данных YDB
+
+{{ ydb-full-name }} может выступать в качестве внешнего источника данных для другой базы {{ ydb-full-name }}. В данном разделе рассматривается организация совместной работы двух независимых баз данных {{ ydb-short-name }} в режиме обработки федеративных запросов.
+
+Для подключения к внешней базе {{ ydb-short-name }} со стороны другой базы {{ ydb-short-name }}, выступающей в роли движка обработки федеративных запросов, на последней требуется выполнить следующие шаги:
+1. Подготовить аутентификационные данные для доступа к удалённой базе {{ ydb-short-name }}. В настоящее время в федеративных запросах к {{ ydb-short-name }} доступен метод аутентификации по [логину и паролю](../../concepts/auth.md#static-credentials) (остальные методы не поддерживаются). Пароль к внешней базе сохраняется в виде [секрета](../datamodel/secrets.md):
+    ```sql
+    CREATE OBJECT ydb_datasource_user_password (TYPE SECRET) WITH (value = "<password>");
+    ```
+1. Создать [внешний источник данных](../datamodel/external_data_source.md), описывающий стороннюю базу {{ ydb-short-name }}. Параметр `LOCATION` содержит сетевой адрес экземпляра {{ ydb-short-name }}, к которому осуществляется сетевое подключение. В `DATABASE_NAME` указывается имя базы данных (например, `local`). Для аутентификации во внешнюю базу используются значения параметров `LOGIN` и `PASSWORD_SECRET_NAME`. Включить шифрование соединений к внешней базе данных можно с помощью параметра `USE_TLS="TRUE"`. Если шифрование включено, то в поле `<port>` параметра `LOCATION` необходимо указать порт gRPCs внешней {{ ydb-short-name }}, в противном случае - порт gRPC.
+    ```sql
+    CREATE EXTERNAL DATA SOURCE ydb_datasource WITH (
+        SOURCE_TYPE="Ydb",
+        LOCATION="<host>:<port>",
+        DATABASE_NAME="<database>",
+        AUTH_METHOD="BASIC",
+        LOGIN="user",
+        PASSWORD_SECRET_NAME="ydb_datasource_user_password",
+        USE_TLS="TRUE"
+    );
+    ```
+1. {% include [!](_includes/connector_deployment.md) %}
+1. [Выполнить запрос](#query) к внешнему источнику данных.
+
+## Синтаксис запросов { #query }
+Для извлечения данных из таблиц внешней базы {{ ydb-short-name }} используется следующая форма SQL-запроса:
+
+```sql
+SELECT * FROM ydb_datasource.`<table_name>`
+```
+
+где:
+- `ydb_datasource` - идентификатор внешнего источника данных;
+- `<table_name>` - полное имя таблицы внутри [иерархии](../../concepts/index.html#ydb-hierarchy) каталогов в базе данных {{ ydb-short-name }}, например, `table`, `dir1/table1` или `dir1/dir2/table3`.
+
+В случае, если таблица находится на верхнем уровне иерархии (не принадлежит ни одному из каталогов), допускается не заключать имя таблицы в обратные апострофы "\`":
+
+```sql
+SELECT * FROM ydb_datasource.<table_name>
+```
+
+## Ограничения
+
+При работе с внешними источниками данных {{ ydb-short-name }} существует ряд ограничений:
+
+1. {% include [!](_includes/supported_requests.md) %}
+1. {% include [!](_includes/predicate_pushdown.md) %}
+
+## Поддерживаемые типы данных
+
+При работе с таблицами, размещёнными во внешней базе {{ ydb-short-name }}, пользователям доступен ограниченный набор типов данных.  Все остальные типы, за исключением перечисленных ниже, не поддерживаются. Преобразование типов не производится, то есть колонки таблицы из внешней базы {{ ydb-short-name }} сохраняют свой тип после вычитывания этой таблицы базой {{ ydb-short-name }}, обрабатывающей федеративный запрос.
+
+|Тип данных {{ ydb-short-name }}|
+|----|
+|`Bool`|
+|`Int8`|
+|`Int16`|
+|`Int32`|
+|`Int64`|
+|`Uint8`|
+|`Uint16`|
+|`Uint32`|
+|`Uint64`|
+|`Float`|
+|`Double`|
+|`String`|
+|`Utf8`|
+|`Date`|
+|`Datetime`|
+|`Timestamp`|
diff --git a/ydb/docs/ru/core/deploy/manual/connector.md b/ydb/docs/ru/core/deploy/manual/connector.md
@@ -17,7 +17,7 @@
 
 Коннектор может быть установлен с помощью бинарного дистрибутива или с помощью Docker-образа.
 
-### Запуск из бинарного дистрибутива
+### Запуск из бинарного дистрибутива {#fq-connector-go-binary}
 
 Для установки коннектора на физический или виртуальный Linux-сервер без средств контейнерной виртуализации используйте бинарные дистрибутивы.
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+ {% if oss %}Развернуть [коннектор](../architecture.md#connectors) {% else %}Развернуть коннектор{% endif %} и [настроить](../../../deploy/manual/deploy-ydb-federated-query.md) динамические узлы {{ ydb-short-name }} на взаимодействие с ним. Также необходимо обеспечить сетевой доступ с динамических узлов {{ ydb-short-name }} к внешнему источнику данных (по адресу, указанному в параметре `LOCATION` запроса `CREATE EXTERNAL DATA SOURCE`). В случае, если на предыдущем шаге было включено шифрование сетевых соединений к внешнему источнику, коннектор будет использовать системные корневые сертификаты (более подробно о настройке TLS можно узнать в [инструкции](../../../deploy/manual/connector.md) по разворачиванию коннектора).
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		-Если значение даты, хранящейся во внешнем источнике данных, находится вне допустимого для {{ ydb-short-name }} диапазона (все используемые даты должны быть позднее 1970-01-01, но ранее 2105-12-31), такое значение в интерфейсе YDB будет отображаться как `NULL`.
	`1`	+Если значение даты, хранящейся во внешнем источнике данных, находится вне допустимого для {{ ydb-short-name }} диапазона (все используемые даты должны быть позднее 1970-01-01, но ранее 2105-12-31), в {{ ydb-short-name }} такое значение будет преобразовано в `NULL`.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Внешние источники доступны только для чтения данных через запросы `SELECT`. Запросы, модифицирующие таблицы во внешних источниках, движком обработки федеративных запросов в настоящее время не поддерживаются.