diff --git a/ydb/docs/en/core/concepts/federated_query/s3/external_data_source.md b/ydb/docs/en/core/concepts/federated_query/s3/external_data_source.md index 85127f77e85b..2fb2fa26794c 100644 --- a/ydb/docs/en/core/concepts/federated_query/s3/external_data_source.md +++ b/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=``); + CREATE OBJECT aws_access_key (TYPE SECRET) WITH (value=``); +``` + +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: diff --git a/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md b/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md index 44b49fe031e6..5645f21bb45d 100644 --- a/ydb/docs/ru/core/concepts/federated_query/s3/external_data_source.md +++ b/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=``); + CREATE OBJECT aws_access_key (TYPE SECRET) WITH (value=``); +``` + +Следующим шагом создаётся внешнее подключение с именем `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) удобно выполнять прототипирование, первоначальную настройку подключений к данным. Пример запроса для чтения данных: