Description for EXTERNAL DATA SOURCE ObjectStorage has been added YQ-…

…4026 (#14127)

Co-authored-by: Ivan Blinkov <ivan@ydb.tech>
Co-authored-by: Andrey Fomichev <andrey.fomichev@gmail.com>

ydb/docs/en/core/concepts/federated_query/s3/external_data_source.md

@@ -1,5 +1,45 @@
 # Working with S3 buckets ({{objstorage-full-name}})
 
+To work with S3, you need to set up a data storage connection. There is a DDL for configuring such connections. Next, let's look at the SQL syntax and the management of these settings.
+
+There are two types of buckets in S3: public and private. To connect to a public bucket, use `AUTH_METHOD="NONE"`. To connect to a private bucket, use `AUTH_METHOD="AWS"`. A detailed description of `AWS` can be found [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-authentication-methods.html). `AUTH_METHOD="NONE"` means that no authentication is used. If `AUTH_METHOD="AWS"` is specified, several additional parameters are required:
+
+- `AWS_ACCESS_KEY_ID_SECRET_NAME` – reference to the name of the [secret](../../datamodel/secrets.md) where `AWS_ACCESS_KEY_ID` is stored.
+- `AWS_SECRET_ACCESS_KEY_SECRET_NAME` – reference to the name of the [secret](../../datamodel/secrets.md) where `AWS_SECRET_ACCESS_KEY` is stored.
+- `AWS_REGION` – region from which reading is performed, for example, `ru-central-1`.
+
+To set up a connection to a public bucket, execute the following SQL query. The query creates an external connection named `object_storage`, which points to a specific S3 bucket named `bucket`.
+
+```yql
+CREATE EXTERNAL DATA SOURCE object_storage WITH (
+  SOURCE_TYPE="ObjectStorage",
+  LOCATION="https://object_storage_domain/bucket/",
+  AUTH_METHOD="NONE"
+);
+```
+
+To set up a connection to a private bucket, you need to run a few SQL queries. First, create [secrets](../../datamodel/secrets.md) containing `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
+
+```yql
+    CREATE OBJECT aws_access_id (TYPE SECRET) WITH (value=`<id>`);
+    CREATE OBJECT aws_access_key (TYPE SECRET) WITH (value=`<key>`);
+```
+
+The next step is to create an external connection named `object_storage`, which points to a specific S3 bucket named `bucket` and uses `AUTH_METHOD="AWS"`. The parameters `AWS_ACCESS_KEY_ID_SECRET_NAME`, `AWS_SECRET_ACCESS_KEY_SECRET_NAME`, and `AWS_REGION` are filled in for `AWS`. The values of these parameters are described above.
+
+```yql
+CREATE EXTERNAL DATA SOURCE object_storage WITH (
+  SOURCE_TYPE="ObjectStorage",
+  LOCATION="https://object_storage_domain/bucket/",
+  AUTH_METHOD="AWS",
+  AWS_ACCESS_KEY_ID_SECRET_NAME="aws_access_id",
+  AWS_SECRET_ACCESS_KEY_SECRET_NAME="aws_access_key",
+  AWS_REGION="ru-central-1"
+);
+```
+
+## Using an external connection to an S3 bucket {#external-data-source-settings}
+
 When working with {{ objstorage-full-name }} using [external data sources](../../datamodel/external_data_source.md), it is convenient to perform prototyping and initial data connection setup.
 
 An example query to read data:

ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md

@@ -1,5 +1,45 @@
 # Работа с бакетами S3 ({{objstorage-full-name}})
 
+Перед началом работы с S3 необходимо настроить подключение к хранилищу данных. Для этого существует DDL для настройки таких подключений. Далее рассмотрим SQL синтаксис и управление этими настройками.
+
+Бакеты в S3 бывают двух видов: публичные и приватные. Для подключения к публичному бакету необходимо использовать `AUTH_METHOD="NONE"`, а для подключения к приватному — `AUTH_METHOD="AWS"`. Подробное описание `AWS` можно найти [здесь](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-authentication-methods.html). `AUTH_METHOD="NONE"` означает, что аутентификация не требуется. В случае `AUTH_METHOD="AWS"` необходимо указать несколько дополнительных параметров:
+
+- `AWS_ACCESS_KEY_ID_SECRET_NAME` — ссылка на имя [секрета](../../datamodel/secrets.md), в котором хранится `AWS_ACCESS_KEY_ID`.
+- `AWS_SECRET_ACCESS_KEY_SECRET_NAME` — ссылка на имя [секрета](../../datamodel/secrets.md), в котором хранится `AWS_SECRET_ACCESS_KEY`.
+- `AWS_REGION` — регион, из которого будет происходить чтение, например `ru-central-1`.
+
+Для настройки соединения с публичным бакетом достаточно выполнить следующий SQL-запрос. Запрос создаст внешнее подключение с именем `object_storage`, которое будет указывать на конкретный S3-бакет с именем `bucket`.
+
+```yql
+CREATE EXTERNAL DATA SOURCE object_storage WITH (
+  SOURCE_TYPE="ObjectStorage",
+  LOCATION="https://object_storage_domain/bucket/",
+  AUTH_METHOD="NONE"
+);
+```
+
+Для настройки соединения с приватным бакетом необходимо выполнить несколько SQL-запросов. Сначала нужно создать [секреты](../../datamodel/secrets.md), содержащие `AWS_ACCESS_KEY_ID` и `AWS_SECRET_ACCESS_KEY`.
+
+```yql
+    CREATE OBJECT aws_access_id (TYPE SECRET) WITH (value=`<id>`);
+    CREATE OBJECT aws_access_key (TYPE SECRET) WITH (value=`<key>`);
+```
+
+Следующим шагом создаётся внешнее подключение с именем `object_storage`, которое будет указывать на конкретный S3-бакет с именем `bucket`, а также использовать `AUTH_METHOD="AWS"`, для которого заполняются параметры `AWS_ACCESS_KEY_ID_SECRET_NAME`, `AWS_SECRET_ACCESS_KEY_SECRET_NAME`, `AWS_REGION`. Значения этих параметров описаны выше.
+
+```yql
+CREATE EXTERNAL DATA SOURCE object_storage WITH (
+  SOURCE_TYPE="ObjectStorage",
+  LOCATION="https://object_storage_domain/bucket/",
+  AUTH_METHOD="AWS",
+  AWS_ACCESS_KEY_ID_SECRET_NAME="aws_access_id",
+  AWS_SECRET_ACCESS_KEY_SECRET_NAME="aws_access_key",
+  AWS_REGION="ru-central-1"
+);
+```
+
+## Использование внешнего подключения к S3-бакету {#external-data-source-settings}
+
 При работе с {{ objstorage-full-name }} с помощью [внешних источников данных](../../datamodel/external_data_source.md) удобно выполнять прототипирование, первоначальную настройку подключений к данным.
 
 Пример запроса для чтения данных: