From 4808b47024dc8b2fac8487bf9efb213ef93beada Mon Sep 17 00:00:00 2001 From: Nina Gulevich Date: Sun, 4 May 2025 11:12:07 +0300 Subject: [PATCH 1/5] mongodb docs --- .../core/concepts/federated_query/mongodb.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 ydb/docs/ru/core/concepts/federated_query/mongodb.md diff --git a/ydb/docs/ru/core/concepts/federated_query/mongodb.md b/ydb/docs/ru/core/concepts/federated_query/mongodb.md new file mode 100644 index 000000000000..79fa05670e62 --- /dev/null +++ b/ydb/docs/ru/core/concepts/federated_query/mongodb.md @@ -0,0 +1,91 @@ +# Работа с базами данных MongoDB + +В этом разделе описана основная информация про работу с внешней NoSQL базой данных [MongoDB](https://www.mongodb.com/). + +Для работы с внешней базой данных MongoDB необходимо выполнить следующие шаги: + +1. Создать [секрет](../datamodel/secrets.md), содержащий пароль для подключения к базе данных. + + ```yql + CREATE OBJECT mongodb_datasource_user_password (TYPE SECRET) WITH (value = ""); + ``` + +1. Создать [внешний источник данных](../datamodel/external_data_source.md), описывающий целевую базу данных внутри кластера MongoDB. Для соединения с MongoDB используется [нативный TCP-протокол](https://www.mongodb.com/docs/manual/reference/mongodb-wire-protocol/) (`PROTOCOL="NATIVE"`). Параметр `LOCATION` содержит сетевой адрес экземпляра MongoDB, к которому осуществляется подключение. В `DATABASE_NAME` указывается имя базы данных (например, `master`). Для аутентификации во внешнюю базу используются значения параметров `LOGIN` и `PASSWORD_SECRET_NAME`. Включить шифрование соединений к внешней базе данных можно с помощью параметра `USE_TLS="TRUE"`. + + Параметр `READING_MODE` определяет то, каким образом документ из MongoDB будет представлен в реляционном формате: опция `TABLE` подразумевает отображение каждого корневого поля документа в отдельную колонку таблицы. + + В параметре `UNSUPPORTED_TYPE_DISPLAY_MODE` указывается политика обработки типов данных MongoDB, которые пока не поддерживаются в {{ ydb-full-name }}. Можно выбрать один из двух вариантов: в случае `UNSUPPORTED_OMIT` поля неподдерживаемых типов будут пропущены в запросе, а с `UNSUPPORTED_AS_STRING` запрос вернет значение подобных полей в сериализованном виде как тип `Utf8`. Подробнее о том, как система типов MongoDB отображается в {{ ydb-full-name }}, можно почитать в разделе 'Поддерживаемые типы данных'. + + Опция `UNEXPECTED_TYPE_DISPLAY_MODE` отвечает за представление значений, которые оказались несовместимы с выведенной структурой документов MongoDB. При чтении данных из внешнего источника MongoDB {{ ydb-full-name }} автоматически выводит структуру документов коллекции с помощью небольшого скана. Поскольку данные MongoDB неструктурированы, отдельные документы коллекции могут не сооветствовать полученной схеме. С опцией `UNEXPECTED_AS_NULL` подобные поля будут пропускаться вне зависимости от выведенного типа, а с опцией `UNEXPECTED_AS_STRING` значения полей неприводимых типов будут сериализованы в строки `Utf8`, если ожидаемый тип подобных полей в выведенной схеме - `Utf8`. + + ```yql + CREATE EXTERNAL DATA SOURCE mongodb_datasource WITH ( + SOURCE_TYPE="MongoDB", + LOCATION=":", + DATABASE_NAME="", + AUTH_METHOD="BASIC", + LOGIN="", + PASSWORD_SECRET_NAME="mongodb_datasource_user_password", + USE_TLS="TRUE", + READING_MODE="TABLE", + UNSUPPORTED_TYPE_DISPLAY_MODE="UNSUPPORTED_OMIT", + UNEXPECTED_TYPE_DISPLAY_MODE="UNEXPECTED_AS_NULL" + ); + ``` + +1. {% include [!](_includes/connector_deployment.md) %} +1. [Выполнить запрос](#query) к базе данных. + +## Синтаксис запросов {#query} + +Для работы с MongoDB используется следующая форма SQL-запроса: + +```yql +SELECT * FROM mongodb_datasource. +``` + +где: + +- `mongodb_datasource` - идентификатор внешнего источника данных; +- `` - имя коллекции внутри внешнего источника данных. + +## Ограничения + +При работе с кластерами MongoDB существует ряд ограничений: + +1. {% include [!](_includes/supported_requests.md) %} +1. {% include [!](_includes/predicate_pushdown.md) %} + + |Тип данных {{ ydb-short-name }}| + |----| + |`Bool`| + |`Int8`| + |`Uint8`| + |`Int16`| + |`Uint16`| + |`Int32`| + |`Uint32`| + |`Int64`| + |`Uint64`| + |`Float`| + |`Double`| + |`String`| + |`Utf8`| + +## Поддерживаемые типы данных + +MongoDB - это NoSQL-СУБД, предназначенная для работы с неструктурированными и полуструктурированными данными. В отличие от реляционных баз данных, MongoDB хранит JSON-подобные документы, которые как правило не соответствуют единому формату или структуре. В связи с этим, для преобразования данных MongoDB в реляционный формат, необходимый для выполнения SQL запросов, {{ ydb-full-name }} автоматически выводит схему MongoDB при выполнении запроса с помощью небольшого скана коллекции. В случае обработки документов, в которых одинаковые поля представлены разными неприводимыми типами (например, `Int32` и `String`), они будут представлены в запросе в сериализованном виде, а тип {{ ydb-full-name }} для них будет соответствовать `Optional`. + +Любые поля MongoDB кроме `_id` по умолчанию могут быть пропущены или содержать значения `NULL`, и в системе типов {{ ydb-full-name }} они должны отображаться в [опциональные](../../yql/reference/types/optional.md) типы. Поскольку поле `_id` разных документов одной коллекции может быть разных типов, в системе типов {{ ydb-full-name }} оно также будет опциональным. + +Ниже приведена таблица соответствия типов MongoDB и {{ ydb-short-name }}. Все остальные типы данных, за исключением перечисленных, не поддерживаются и не могут быть использованы в пушдауне предикатов. Однако, поля таких типов все еще могут использоваться в качестве возвращаемого значения запроса в сериализованном виде как `Optional` при включении параметра `UNSUPPORTED_TYPE_DISPLAY_MODE=UNSUPPORTED_AS_STRING`. + +|Тип данных MongoDB|Тип данных {{ ydb-full-name }} +|---|---| +|`Boolean`|`Optional`| +|`Int32`|`Optional`| +|`Int64`|`Optional`| +|`Double`|`Optional`| +|`String`|`Optional`| +|`Binary`|`Optional`| +|`ObjectId`|`Optional`| From 70ae275c3167632f5d9352d38f168150aa8a587e Mon Sep 17 00:00:00 2001 From: Nina <100221635+ninaiad@users.noreply.github.com> Date: Mon, 5 May 2025 19:31:22 +0300 Subject: [PATCH 2/5] Update ydb/docs/ru/core/concepts/federated_query/mongodb.md Co-authored-by: Ivan Blinkov --- ydb/docs/ru/core/concepts/federated_query/mongodb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/ru/core/concepts/federated_query/mongodb.md b/ydb/docs/ru/core/concepts/federated_query/mongodb.md index 79fa05670e62..fdb465748654 100644 --- a/ydb/docs/ru/core/concepts/federated_query/mongodb.md +++ b/ydb/docs/ru/core/concepts/federated_query/mongodb.md @@ -1,6 +1,6 @@ # Работа с базами данных MongoDB -В этом разделе описана основная информация про работу с внешней NoSQL базой данных [MongoDB](https://www.mongodb.com/). +В этом разделе приведена основная информация о работе с внешней NoSQL-базой данных [MongoDB](https://www.mongodb.com/). Для работы с внешней базой данных MongoDB необходимо выполнить следующие шаги: From d6cc55bff1b3ea0c56a3c1763f936546287e5eaa Mon Sep 17 00:00:00 2001 From: Nina <100221635+ninaiad@users.noreply.github.com> Date: Mon, 5 May 2025 19:31:33 +0300 Subject: [PATCH 3/5] Update ydb/docs/ru/core/concepts/federated_query/mongodb.md Co-authored-by: Ivan Blinkov --- ydb/docs/ru/core/concepts/federated_query/mongodb.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ydb/docs/ru/core/concepts/federated_query/mongodb.md b/ydb/docs/ru/core/concepts/federated_query/mongodb.md index fdb465748654..13031628fc19 100644 --- a/ydb/docs/ru/core/concepts/federated_query/mongodb.md +++ b/ydb/docs/ru/core/concepts/federated_query/mongodb.md @@ -10,13 +10,13 @@ CREATE OBJECT mongodb_datasource_user_password (TYPE SECRET) WITH (value = ""); ``` -1. Создать [внешний источник данных](../datamodel/external_data_source.md), описывающий целевую базу данных внутри кластера MongoDB. Для соединения с MongoDB используется [нативный TCP-протокол](https://www.mongodb.com/docs/manual/reference/mongodb-wire-protocol/) (`PROTOCOL="NATIVE"`). Параметр `LOCATION` содержит сетевой адрес экземпляра MongoDB, к которому осуществляется подключение. В `DATABASE_NAME` указывается имя базы данных (например, `master`). Для аутентификации во внешнюю базу используются значения параметров `LOGIN` и `PASSWORD_SECRET_NAME`. Включить шифрование соединений к внешней базе данных можно с помощью параметра `USE_TLS="TRUE"`. +1. Создать [внешний источник данных](../datamodel/external_data_source.md), описывающий целевую базу данных внутри кластера MongoDB. Для соединения с MongoDB используется [нативный TCP-протокол](https://www.mongodb.com/docs/manual/reference/mongodb-wire-protocol/) (`PROTOCOL="NATIVE"`). Параметр `LOCATION` содержит сетевой адрес экземпляра MongoDB, к которому осуществляется подключение. В `DATABASE_NAME` указывается имя базы данных (например, `master`). Для аутентификации во внешнюю базу используются значения параметров `LOGIN` и `PASSWORD_SECRET_NAME`. Включить шифрование соединений с внешней базой данных можно с помощью параметра `USE_TLS="TRUE"`. Параметр `READING_MODE` определяет то, каким образом документ из MongoDB будет представлен в реляционном формате: опция `TABLE` подразумевает отображение каждого корневого поля документа в отдельную колонку таблицы. - В параметре `UNSUPPORTED_TYPE_DISPLAY_MODE` указывается политика обработки типов данных MongoDB, которые пока не поддерживаются в {{ ydb-full-name }}. Можно выбрать один из двух вариантов: в случае `UNSUPPORTED_OMIT` поля неподдерживаемых типов будут пропущены в запросе, а с `UNSUPPORTED_AS_STRING` запрос вернет значение подобных полей в сериализованном виде как тип `Utf8`. Подробнее о том, как система типов MongoDB отображается в {{ ydb-full-name }}, можно почитать в разделе 'Поддерживаемые типы данных'. + В параметре `UNSUPPORTED_TYPE_DISPLAY_MODE` указывается политика обработки типов данных MongoDB, которые пока не поддерживаются в {{ ydb-full-name }}. Можно выбрать один из двух вариантов: в случае `UNSUPPORTED_OMIT` поля неподдерживаемых типов будут пропущены в результате запроса, а с `UNSUPPORTED_AS_STRING` запрос вернёт значение подобных полей в сериализованном виде как тип `Utf8`. Подробнее о том, как система типов MongoDB отображается в {{ ydb-full-name }}, можно прочитать в разделе [«Поддерживаемые типы данных»](#supported-data-types). - Опция `UNEXPECTED_TYPE_DISPLAY_MODE` отвечает за представление значений, которые оказались несовместимы с выведенной структурой документов MongoDB. При чтении данных из внешнего источника MongoDB {{ ydb-full-name }} автоматически выводит структуру документов коллекции с помощью небольшого скана. Поскольку данные MongoDB неструктурированы, отдельные документы коллекции могут не сооветствовать полученной схеме. С опцией `UNEXPECTED_AS_NULL` подобные поля будут пропускаться вне зависимости от выведенного типа, а с опцией `UNEXPECTED_AS_STRING` значения полей неприводимых типов будут сериализованы в строки `Utf8`, если ожидаемый тип подобных полей в выведенной схеме - `Utf8`. + Опция `UNEXPECTED_TYPE_DISPLAY_MODE` отвечает за представление значений, которые оказались несовместимы с выведенной структурой документов MongoDB. При чтении данных из внешнего источника MongoDB {{ ydb-full-name }} автоматически выводит структуру документов коллекции с помощью небольшого скана. Поскольку данные MongoDB неструктурированы, отдельные документы коллекции могут не соответствовать полученной схеме. С опцией `UNEXPECTED_AS_NULL` подобные поля будут пропускаться вне зависимости от выведенного типа, а с опцией `UNEXPECTED_AS_STRING` значения полей неприводимых типов будут сериализованы в строки `Utf8`, если ожидаемый тип подобных полей в выведенной схеме — `Utf8`. ```yql CREATE EXTERNAL DATA SOURCE mongodb_datasource WITH ( From 7f1632e9f2a53cf5260d695b72e5a6396c3a02ec Mon Sep 17 00:00:00 2001 From: Nina <100221635+ninaiad@users.noreply.github.com> Date: Mon, 5 May 2025 19:31:46 +0300 Subject: [PATCH 4/5] Update ydb/docs/ru/core/concepts/federated_query/mongodb.md Co-authored-by: Ivan Blinkov --- ydb/docs/ru/core/concepts/federated_query/mongodb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/ru/core/concepts/federated_query/mongodb.md b/ydb/docs/ru/core/concepts/federated_query/mongodb.md index 13031628fc19..b5ad83d99bd8 100644 --- a/ydb/docs/ru/core/concepts/federated_query/mongodb.md +++ b/ydb/docs/ru/core/concepts/federated_query/mongodb.md @@ -72,7 +72,7 @@ SELECT * FROM mongodb_datasource. |`String`| |`Utf8`| -## Поддерживаемые типы данных +## Поддерживаемые типы данных {#supported-data-types} MongoDB - это NoSQL-СУБД, предназначенная для работы с неструктурированными и полуструктурированными данными. В отличие от реляционных баз данных, MongoDB хранит JSON-подобные документы, которые как правило не соответствуют единому формату или структуре. В связи с этим, для преобразования данных MongoDB в реляционный формат, необходимый для выполнения SQL запросов, {{ ydb-full-name }} автоматически выводит схему MongoDB при выполнении запроса с помощью небольшого скана коллекции. В случае обработки документов, в которых одинаковые поля представлены разными неприводимыми типами (например, `Int32` и `String`), они будут представлены в запросе в сериализованном виде, а тип {{ ydb-full-name }} для них будет соответствовать `Optional`. From 18e737a91cb82c8d1446f4a0a5b3d956e63e86be Mon Sep 17 00:00:00 2001 From: Nina <100221635+ninaiad@users.noreply.github.com> Date: Mon, 5 May 2025 19:32:18 +0300 Subject: [PATCH 5/5] Update ydb/docs/ru/core/concepts/federated_query/mongodb.md Co-authored-by: Ivan Blinkov --- ydb/docs/ru/core/concepts/federated_query/mongodb.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ydb/docs/ru/core/concepts/federated_query/mongodb.md b/ydb/docs/ru/core/concepts/federated_query/mongodb.md index b5ad83d99bd8..b5cf4833c8d3 100644 --- a/ydb/docs/ru/core/concepts/federated_query/mongodb.md +++ b/ydb/docs/ru/core/concepts/federated_query/mongodb.md @@ -74,11 +74,11 @@ SELECT * FROM mongodb_datasource. ## Поддерживаемые типы данных {#supported-data-types} -MongoDB - это NoSQL-СУБД, предназначенная для работы с неструктурированными и полуструктурированными данными. В отличие от реляционных баз данных, MongoDB хранит JSON-подобные документы, которые как правило не соответствуют единому формату или структуре. В связи с этим, для преобразования данных MongoDB в реляционный формат, необходимый для выполнения SQL запросов, {{ ydb-full-name }} автоматически выводит схему MongoDB при выполнении запроса с помощью небольшого скана коллекции. В случае обработки документов, в которых одинаковые поля представлены разными неприводимыми типами (например, `Int32` и `String`), они будут представлены в запросе в сериализованном виде, а тип {{ ydb-full-name }} для них будет соответствовать `Optional`. +MongoDB — это NoSQL-СУБД, предназначенная для работы с неструктурированными и полуструктурированными данными. В отличие от реляционных баз данных, MongoDB хранит JSON-подобные документы, которые, как правило, не соответствуют единому формату или структуре. В связи с этим для преобразования данных MongoDB в реляционный формат, необходимый для выполнения SQL-запросов, {{ ydb-full-name }} автоматически выводит схему MongoDB при выполнении запроса с помощью небольшого сканирования коллекции. В случае обработки документов, в которых одинаковые поля представлены разными неприводимыми типами (например, `Int32` и `String`), они будут представлены в запросе в сериализованном виде, а тип {{ ydb-full-name }} для них будет соответствовать `Optional`. -Любые поля MongoDB кроме `_id` по умолчанию могут быть пропущены или содержать значения `NULL`, и в системе типов {{ ydb-full-name }} они должны отображаться в [опциональные](../../yql/reference/types/optional.md) типы. Поскольку поле `_id` разных документов одной коллекции может быть разных типов, в системе типов {{ ydb-full-name }} оно также будет опциональным. +Любые поля MongoDB, кроме `_id`, по умолчанию могут быть опущены или содержать значения `NULL`, и в системе типов {{ ydb-full-name }} они должны отображаться в [опциональные](../../yql/reference/types/optional.md) типы. Поскольку поле `_id` в разных документах одной коллекции может иметь разные типы, в системе типов {{ ydb-full-name }} оно также будет опциональным. -Ниже приведена таблица соответствия типов MongoDB и {{ ydb-short-name }}. Все остальные типы данных, за исключением перечисленных, не поддерживаются и не могут быть использованы в пушдауне предикатов. Однако, поля таких типов все еще могут использоваться в качестве возвращаемого значения запроса в сериализованном виде как `Optional` при включении параметра `UNSUPPORTED_TYPE_DISPLAY_MODE=UNSUPPORTED_AS_STRING`. +Ниже приведена таблица соответствия типов MongoDB и {{ ydb-short-name }}. Все остальные типы данных, за исключением перечисленных, не поддерживаются и не могут быть использованы в пушдауне предикатов. Однако поля таких типов всё ещё могут использоваться в качестве возвращаемого значения запроса в сериализованном виде как `Optional` при включении параметра `UNSUPPORTED_TYPE_DISPLAY_MODE=UNSUPPORTED_AS_STRING`. |Тип данных MongoDB|Тип данных {{ ydb-full-name }} |---|---|