Версия: 2.0.x

`FILES`

Определяет файлы данных в удаленном хранилище, используемые для загрузки и выгрузки данных:

Загрузка или запрос данных из удаленной системы хранения
Выгрузка данных в удаленную систему хранения

FILES() поддерживает следующие источники данных и форматы файлов:

Источники данных:
- HDFS
- AWS S3
- Google Cloud Storage
- Другие S3-совместимые системы хранения
- Microsoft Azure Blob Storage
- NFS(NAS)
Форматы файлов:
- Parquet
- ORC (поддерживается с версии 3.3)
- CSV (поддерживается с версии 3.3)
- Avro (поддерживается с версии 3.4.4, только для загрузки)

Начиная с версии 3.2, FILES() дополнительно поддерживает сложные типы данных, включая ARRAY, JSON, MAP и STRUCT, помимо базовых типов данных.

`FILES()` для загрузки

Начиная с версии 3.1.0, Selena поддерживает определение файлов только для чтения в удаленном хранилище с помощью табличной функции FILES(). Она может получить доступ к удаленному хранилищу с помощью свойств, связанных с путем к файлам, определить схему таблицы данных в файлах и вернуть строки данных. Вы можете напрямую запросить строки данных с помощью SELECT, загрузить строки данных в существующую таблицу с помощью INSERT или создать новую таблицу и загрузить в нее строки данных с помощью CREATE TABLE AS SELECT. Начиная с версии 3.3.4, вы также можете просмотреть схему файла данных с помощью FILES() и DESC.

Синтаксис

FILES( data_location , [data_format] [, schema_detect ] [, StorageCredentialParams ] [, columns_from_path ] [, list_files_only ] [, list_recursively])

Параметры

Все параметры задаются в виде пар "key" = "value".

`data_location`

URI для доступа к файлам.

Вы можете указать путь или файл. Например, можно указать этот параметр как "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/20210411" для загрузки файла данных с именем 20210411 из пути /user/data/tablename на сервере HDFS.

Вы также можете указать этот параметр как путь сохранения нескольких файлов данных с помощью подстановочных символов ?, *, [], {} или ^. Например, можно указать этот параметр как "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/*/*" или "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/dt=202104*/*" для загрузки файлов данных из всех партиций или только партиций 202104 в пути /user/data/tablename на сервере HDFS.

примечание

Подстановочные символы также можно использовать для указания промежуточных путей.

Для доступа к HDFS необходимо указать этот параметр как:

"path" = "hdfs://<hdfs_host>:<hdfs_port>/<hdfs_path>"
-- Пример: "path" = "hdfs://127.0.0.1:9000/path/file.parquet"

Для доступа к AWS S3:
- Если вы используете протокол S3, необходимо указать этот параметр как:
```
"path" = "s3://<s3_path>"
-- Пример: "path" = "s3://path/file.parquet"
```
- Если вы используете протокол S3A, необходимо указать этот параметр как:
```
"path" = "s3a://<s3_path>"
-- Пример: "path" = "s3a://path/file.parquet"
```
Для доступа к Google Cloud Storage необходимо указать этот параметр как:
```
"path" = "s3a://<gcs_path>"
-- Пример: "path" = "s3a://path/file.parquet"
```
Для доступа к Azure Blob Storage:
- Если ваша учетная запись хранения разрешает доступ по HTTP, необходимо указать этот параметр как:
```
"path" = "wasb://<container>@<storage_account>.blob.core.windows.net/<blob_path>"
-- Пример: "path" = "wasb://testcontainer@testaccount.blob.core.windows.net/path/file.parquet"
```
- Если ваша учетная запись хранения разрешает доступ по HTTPS, необходимо указать этот параметр как:
```
"path" = "wasbs://<container>@<storage_account>.blob.core.windows.net/<blob_path>"
-- Пример: "path" = "wasbs://testcontainer@testaccount.blob.core.windows.net/path/file.parquet"
```
Для доступа к NFS(NAS):
```
"path" = "file:///<absolute_path>"
-- Пример: "path" = "file:///home/ubuntu/parquetfile/file.parquet"
```
примечание
Для доступа к файлам в NFS через протокол file:// необходимо смонтировать устройство NAS как NFS в одном и том же каталоге на каждом узле BE или CN.

`data_format`

Формат файла данных. Допустимые значения:

parquet
orc (поддерживается с версии 3.3)
csv (поддерживается с версии 3.3)
avro (поддерживается с версии 3.4.4, только для загрузки)

Вы должны установить подробные опции для конкретных форматов файлов данных.

Когда list_files_only установлен в true, указывать data_format не требуется.

Parquet

Пример формата Parquet:

"format"="parquet",
"parquet.use_legacy_encoding" = "true",   -- только для выгрузки
"parquet.version" = "2.6"                 -- только для выгрузки

`parquet.use_legacy_encoding`

Управляет техникой кодирования, используемой для типов данных DATETIME и DECIMAL. Допустимые значения: true и false (по умолчанию). Это свойство поддерживается только для выгрузки данных.

Если этот параметр установлен в true:

Для типа DATETIME система использует кодировку INT96.
Для типа DECIMAL система использует кодировку fixed_len_byte_array.

Если этот параметр установлен в false:

Для типа DATETIME система использует кодировку INT64.
Для типа DECIMAL система использует кодировку INT32 или INT64.

примечание

Для типа данных DECIMAL 128 доступна только кодировка fixed_len_byte_array. parquet.use_legacy_encoding не действует.

`parquet.version`

Управляет версией Parquet, в которую система выгружает данные. Поддерживается с версии 3.4.6. Допустимые значения: 1.0, 2.4 и 2.6 (по умолчанию). Это свойство поддерживается только для выгрузки данных.

CSV

Пример формата CSV:

"format"="csv",
"csv.column_separator"="\\t",
"csv.enclose"='"',
"csv.skip_header"="1",
"csv.escape"="\\"

`csv.column_separator`

Указывает разделитель столбцов при формате данных CSV. Если вы не укажете этот параметр, по умолчанию используется \\t, что означает табуляцию. Указанный вами разделитель столбцов должен совпадать с разделителем столбцов, фактически используемым в файле данных. В противном случае задача загрузки завершится неудачей из-за недостаточного качества данных.

Задачи, использующие Files(), отправляются согласно протоколу MySQL. Selena и MySQL экранируют символы в запросах загрузки. Поэтому, если разделитель столбцов является невидимым символом, таким как табуляция, вы должны добавить обратную косую черту (\) перед разделителем столбцов. Например, вы должны ввести \\t, если разделитель столбцов - \t, и вы должны ввести \\n, если разделитель столбцов - \n. Файлы Apache Hive™ используют \x01 в качестве разделителя столбцов, поэтому вы должны ввести \\x01, если файл данных из Hive.

примечание

Для данных CSV вы можете использовать строку UTF-8, такую как запятая (,), табуляция или вертикальная черта (|), длина которой не превышает 50 байт, в качестве текстового разделителя.

Значения NULL обозначаются с помощью \N. Например, файл данных состоит из трех столбцов, и запись из этого файла данных содержит данные в первом и третьем столбцах, но не содержит данных во втором столбце. В этой ситуации вам нужно использовать \N во втором столбце для обозначения значения NULL. Это означает, что запись должна быть скомпилирована как a,\N,b, а не a,,b. a,,b означает, что второй столбец записи содержит пустую строку.

`csv.enclose`

Указывает символ, который используется для обертывания значений полей в файле данных согласно RFC4180, когда формат данных CSV. Тип: однобайтовый символ. Значение по умолчанию: NONE. Наиболее распространенными символами являются одинарная кавычка (') и двойная кавычка (").

Все специальные символы (включая разделители строк и разделители столбцов), обернутые с помощью символа, указанного в enclose, считаются обычными символами. Selena может делать больше, чем RFC4180, так как позволяет указать любой однобайтовый символ в качестве символа enclose.

Если значение поля содержит символ, указанный в enclose, вы можете использовать тот же символ для экранирования этого символа enclose. Например, вы установили enclose в ", а значение поля - a "quoted" c. В этом случае вы можете ввести значение поля как "a ""quoted"" c" в файл данных.

`csv.skip_header`

Указывает количество строк заголовка, которые нужно пропустить в данных формата CSV. Тип: INTEGER. Значение по умолчанию: 0.

В некоторых файлах данных формата CSV несколько строк заголовка используются для определения метаданных, таких как имена столбцов и типы данных столбцов. Устанавливая параметр skip_header, вы можете настроить Selena на пропуск этих строк заголовка. Например, если вы установите этот параметр в 1, Selena пропустит первую строку файла данных при загрузке данных.

Строки заголовка в файле данных должны быть разделены с помощью разделителя строк, который вы указываете в операторе загрузки.

`csv.escape`

Указывает символ, который используется для экранирования различных специальных символов, таких как разделители строк, разделители столбцов, символы экранирования и символы, указанные в enclose, которые затем рассматриваются Selena как обычные символы и анализируются как часть значений полей, в которых они находятся. Тип: однобайтовый символ. Значение по умолчанию: NONE. Наиболее распространенным символом является косая черта (\), которая должна быть записана как двойная косая черта (\\) в операторах SQL.

примечание

Символ, указанный в escape, применяется как внутри, так и снаружи каждой пары символов, указанных в enclose.

Два примера:

Когда вы устанавливаете enclose в " и escape в \, Selena анализирует "say \"Hello world\"" в say "Hello world".

Предположим, что разделитель столбцов - запятая (,). Когда вы устанавливаете escape в \, Selena анализирует a, b\, c в два отдельных значения полей: a и b, c.

`schema_detect`

Начиная с версии 3.2, FILES() поддерживает автоматическое определение схемы и объединение одной и той же партии файлов данных. Selena сначала определяет схему данных путем выборки определенных строк данных из случайного файла данных в партии. Затем Selena объединяет столбцы из всех файлов данных в партии.

Вы можете настроить правило выборки с помощью следующих параметров:

auto_detect_sample_files: количество случайных файлов данных для выборки в каждой партии. По умолчанию выбираются первый и последний файлы. Диапазон: [0, + ∞]. По умолчанию: 2.
auto_detect_sample_rows: количество строк данных для сканирования в каждом выбранном файле данных. Диапазон: [0, + ∞]. По умолчанию: 500.
auto_detect_types: (действует только для CSV) - определять ли типы данных выбранных столбцов или просто предполагать String. {true | false}. По умолчанию: true.

После выборки Selena объединяет столбцы из всех файлов данных согласно следующим правилам:

Для столбцов с разными именами или индексами каждый столбец идентифицируется как отдельный столбец, и в итоге возвращается объединение всех отдельных столбцов.
Для столбцов с одинаковым именем, но разными типами данных они идентифицируются как один и тот же столбец, но с общим типом данных на относительно мелком уровне детализации. Например, если столбец col1 в файле A имеет тип INT, но DECIMAL в файле B, в возвращаемом столбце используется тип DOUBLE.
- Все целочисленные столбцы будут объединены в целочисленный тип на общем более грубом уровне детализации.
- Целочисленные столбцы вместе со столбцами типа FLOAT будут объединены в тип DECIMAL.
- Строковые типы используются для объединения других типов.
Как правило, тип STRING может использоваться для объединения всех типов данных.
Если автоопределение типов отключено, все столбцы будут возвращены как STRING

Вы можете обратиться к Примеру 5.

Если Selena не удается объединить все столбцы, она генерирует отчет об ошибке схемы, который включает информацию об ошибке и все схемы файлов.

important

Все файлы данных в одной партии должны быть одного формата файла.

Проверка схемы целевой таблицы с проталкиванием

Начиная с версии 3.4.0, система поддерживает проталкивание проверки схемы целевой таблицы на этап Scan функции FILES().

Определение схемы FILES() не является полностью строгим. Например, любой целочисленный столбец в файлах CSV выводится и проверяется как тип BIGINT при чтении файлов функцией. В этом случае, если соответствующий столбец в целевой таблице имеет тип TINYINT, записи данных CSV, которые превышают тип BIGINT, не будут отфильтрованы. Вместо этого они будут неявно заполнены значением NULL.

Для решения этой проблемы система вводит динамический элемент конфигурации FE files_enable_insert_push_down_schema для управления тем, проталкивать ли проверку схемы целевой таблицы на этап Scan функции FILES(). Установив files_enable_insert_push_down_schema в true, система будет фильтровать записи данных, которые не проходят проверку схемы целевой таблицы при чтении файла.

Объединение файлов с разной схемой

Начиная с версии 3.4.0, система поддерживает объединение файлов с разной схемой, и по умолчанию возвращается ошибка при наличии несуществующих столбцов. Установив свойство fill_mismatch_column_with в null, вы можете разрешить системе назначать значения NULL несуществующим столбцам вместо возврата ошибки.

fill_mismatch_column_with: поведение системы после обнаружения несуществующего столбца при объединении файлов с разной схемой. Допустимые значения:

none: возвращается ошибка, если обнаружен несуществующий столбец.
null: значения NULL будут назначены несуществующему столбцу.

Например, читаемые файлы из разных партиций таблицы Hive, и Schema Change была выполнена на более новых партициях. При чтении как новых, так и старых партиций вы можете установить fill_mismatch_column_with в null, и система объединит схему файлов новых и старых партиций и назначит значения NULL несуществующим столбцам.

Система объединяет схему файлов Parquet и ORC на основе имен столбцов, а файлов CSV - на основе позиции (порядка) столбцов.

Вывод типа STRUCT из Parquet

Начиная с версии 3.4.0, FILES() поддерживает вывод данных типа STRUCT из файлов Parquet.

`StorageCredentialParams`

Информация для аутентификации, используемая Selena для доступа к вашей системе хранения.

Selena в настоящее время поддерживает доступ к HDFS с простой аутентификацией, доступ к AWS S3 и GCS с аутентификацией на основе пользователя IAM и доступ к Azure Blob Storage с помощью Shared Key, SAS Token, Managed Identity и Service Principal.

HDFS

Использование простой аутентификации для доступа к HDFS:

"hadoop.security.authentication" = "simple",
"username" = "xxxxxxxxxx",
"password" = "yyyyyyyyyy"

Ключ	Обязательный	Описание
`hadoop.security.authentication`	Нет	Метод аутентификации. Допустимое значение: `simple` (по умолчанию). `simple` означает простую аутентификацию, то есть без аутентификации.
`username`	Да	Имя пользователя учетной записи, которую вы хотите использовать для доступа к NameNode cluster HDFS.
`password`	Да	Пароль учетной записи, которую вы хотите использовать для доступа к NameNode cluster HDFS.

Использование аутентификации Kerberos для доступа к HDFS:

В настоящее время FILES() поддерживает аутентификацию Kerberos с HDFS только через файл конфигурации hdfs-site.xml, размещенный в каталогах fe/conf, be/conf и cn/conf.

Кроме того, вам нужно добавить следующую опцию в элемент конфигурации JAVA_OPTS в каждом файле конфигурации FE fe.conf, файле конфигурации BE be.conf и файле конфигурации CN cn.conf:
```
# Укажите локальный путь, по которому хранится файл конфигурации Kerberos.
-Djava.security.krb5.conf=<path_to_kerberos_conf_file>
```
Пример:
```
JAVA_OPTS="-Xlog:gc*:${LOG_DIR}/be.gc.log.$DATE:time -XX:ErrorFile=${LOG_DIR}/hs_err_pid%p.log -Djava.security.krb5.conf=/etc/krb5.conf"
```
Вам также нужно выполнить команду kinit на каждом узле FE, BE и CN для получения Ticket Granting Ticket (TGT) от Key Distribution Center (KDC).
```
kinit -kt <path_to_keytab_file> <principal>
```
Для выполнения этой команды используемый principal должен иметь права на запись в ваш cluster HDFS. Кроме того, вам нужно настроить crontab для команды, чтобы запланировать задачу с определенным интервалом, предотвращая истечение срока аутентификации.

Пример:
```
# Обновлять TGT каждые 6 часов.
0 */6 * * * kinit -kt sr.keytab sr/test.selena.com@SELENA.COM > /tmp/kinit.log
```
Доступ к HDFS с включенным режимом HA:

В настоящее время FILES() поддерживает доступ к HDFS с включенным режимом HA только через файл конфигурации hdfs-site.xml, размещенный в каталогах fe/conf, be/conf и cn/conf.

AWS S3

Если вы выбрали AWS S3 в качестве системы хранения, выполните одно из следующих действий:

Для выбора метода аутентификации на основе профиля экземпляра настройте StorageCredentialParams следующим образом:
```
"aws.s3.use_instance_profile" = "true",
"aws.s3.region" = "<aws_s3_region>"
```
Для выбора метода аутентификации на основе принятой роли настройте StorageCredentialParams следующим образом:
```
"aws.s3.use_instance_profile" = "true",
"aws.s3.iam_role_arn" = "<iam_role_arn>",
"aws.s3.region" = "<aws_s3_region>"
```
Для выбора метода аутентификации на основе пользователя IAM настройте StorageCredentialParams следующим образом:
```
"aws.s3.use_instance_profile" = "false",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>",
"aws.s3.region" = "<aws_s3_region>"
```

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Обязательный	Описание
`aws.s3.use_instance_profile`	Да	Указывает, включать ли методы учетных данных профиля экземпляра и принятой роли. Допустимые значения: `true` и `false`. Значение по умолчанию: `false`.
`aws.s3.iam_role_arn`	Нет	ARN роли IAM, которая имеет привилегии на вашем bucket AWS S3. Если вы выбрали принятую роль в качестве метода учетных данных для доступа к AWS S3, вы должны указать этот параметр.
`aws.s3.region`	Да	Регион, в котором находится ваш bucket AWS S3. Пример: `us-west-1`.
`aws.s3.access_key`	Нет	Ключ доступа вашего пользователя IAM. Если вы выбрали пользователя IAM в качестве метода учетных данных для доступа к AWS S3, вы должны указать этот параметр.
`aws.s3.secret_key`	Нет	Секретный ключ вашего пользователя IAM. Если вы выбрали пользователя IAM в качестве метода учетных данных для доступа к AWS S3, вы должны указать этот параметр.

Информацию о том, как выбрать метод аутентификации для доступа к AWS S3 и как настроить политику управления доступом в AWS IAM Console, см. в разделе Параметры аутентификации для доступа к AWS S3.

Региональные конечные точки AWS STS

AWS Security Token Service (AWS STS) доступен как глобальная и региональная служба.

Параметр	Обязательный	Описание
`aws.s3.sts.region`	Нет	Регион AWS Security Token Service для доступа.
`aws.s3.sts.endpoint`	Нет	Используется для переопределения конечной точки AWS Security Token Service по умолчанию.

important

При использовании конечных точек AWS STS для аутентификации и доступа к данным в S3-совместимом хранилище за пределами S3 необходимо установить aws.s3.use_instance_profile в false.

Google GCS

Если вы выбрали Google GCS в качестве системы хранения, выполните одно из следующих действий:

Для выбора метода аутентификации на основе VM настройте StorageCredentialParams следующим образом:

"gcp.gcs.use_compute_engine_service_account" = "true"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Значение по умолчанию	Пример значения	Описание
`gcp.gcs.use_compute_engine_service_account`	false	true	Указывает, использовать ли напрямую сервисную учетную запись, привязанную к вашему Compute Engine.

Для выбора метода аутентификации на основе сервисной учетной записи настройте StorageCredentialParams следующим образом:

"gcp.gcs.service_account_email" = "<google_service_account_email>",
"gcp.gcs.service_account_private_key_id" = "<google_service_private_key_id>",
"gcp.gcs.service_account_private_key" = "<google_service_private_key>"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Значение по умолчанию	Пример значения	Описание
`gcp.gcs.service_account_email`	""	`"user@hello.iam.gserviceaccount.com"`	Адрес электронной почты в JSON-файле, созданном при создании сервисной учетной записи.
`gcp.gcs.service_account_private_key_id`	""	"61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"	Идентификатор закрытого ключа в JSON-файле, созданном при создании сервисной учетной записи.
`gcp.gcs.service_account_private_key`	""	"`-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n`"	Закрытый ключ в JSON-файле, созданном при создании сервисной учетной записи.

Для выбора метода аутентификации на основе имперсонации настройте StorageCredentialParams следующим образом:

Сделать экземпляр VM имперсонирующим сервисную учетную запись:

"gcp.gcs.use_compute_engine_service_account" = "true",
"gcp.gcs.impersonation_service_account" = "<assumed_google_service_account_email>"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Значение по умолчанию	Пример значения	Описание
`gcp.gcs.use_compute_engine_service_account`	false	true	Указывает, использовать ли напрямую сервисную учетную запись, привязанную к вашему Compute Engine.
`gcp.gcs.impersonation_service_account`	""	"hello"	Сервисная учетная запись, которую вы хотите имперсонировать.

Сделать сервисную учетную запись (называемую мета-сервисной учетной записью) имперсонирующей другую сервисную учетную запись (называемую сервисной учетной записью данных):

"gcp.gcs.service_account_email" = "<google_service_account_email>",
"gcp.gcs.service_account_private_key_id" = "<meta_google_service_account_email>",
"gcp.gcs.service_account_private_key" = "<meta_google_service_account_email>",
"gcp.gcs.impersonation_service_account" = "<data_google_service_account_email>"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Значение по умолчанию	Пример значения	Описание
`gcp.gcs.service_account_email`	""	`"user@hello.iam.gserviceaccount.com"`	Адрес электронной почты в JSON-файле, созданном при создании мета-сервисной учетной записи.
`gcp.gcs.service_account_private_key_id`	""	"61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"	Идентификатор закрытого ключа в JSON-файле, созданном при создании мета-сервисной учетной записи.
`gcp.gcs.service_account_private_key`	""	"-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"	Закрытый ключ в JSON-файле, созданном при создании мета-сервисной учетной записи.
`gcp.gcs.impersonation_service_account`	""	"hello"	Сервисная учетная запись данных, которую вы хотите имперсонировать.

Azure Blob Storage

Использование Shared Key для доступа к Azure Blob Storage:

"azure.blob.shared_key" = "<shared_key>"

Ключ	Обязательный	Описание
`azure.blob.shared_key`	Да	Shared Key, который вы можете использовать для доступа к учетной записи Azure Blob Storage.

Использование SAS Token для доступа к Azure Blob Storage:

"azure.blob.sas_token" = "<storage_account_SAS_token>"

Ключ	Обязательный	Описание
`azure.blob.sas_token`	Да	SAS token, который вы можете использовать для доступа к учетной записи Azure Blob Storage.

Использование Managed Identity для доступа к Azure Blob Storage (поддерживается с версии 3.4.4):

примечание

Поддерживаются только User-assigned Managed Identities с учетными данными Client ID.
Динамическая конфигурация FE azure_use_native_sdk (по умолчанию: true) управляет тем, разрешать ли системе использовать аутентификацию с Managed Identity и Service Principals.

"azure.blob.oauth2_use_managed_identity" = "true",
"azure.blob.oauth2_client_id" = "<oauth2_client_id>"

Ключ	Обязательный	Описание
`azure.blob.oauth2_use_managed_identity`	Да	Использовать ли Managed Identity для доступа к учетной записи Azure Blob Storage. Установите в `true`.
`azure.blob.oauth2_client_id`	Да	Client ID Managed Identity, который вы можете использовать для доступа к учетной записи Azure Blob Storage.

Использование Service Principal для доступа к Azure Blob Storage (поддерживается с версии 3.4.4):

примечание

Поддерживаются только учетные данные Client Secret.
Динамическая конфигурация FE azure_use_native_sdk (по умолчанию: true) управляет тем, разрешать ли системе использовать аутентификацию с Managed Identity и Service Principals.

"azure.blob.oauth2_client_id" = "<oauth2_client_id>",
"azure.blob.oauth2_client_secret" = "<oauth2_client_secret>",
"azure.blob.oauth2_tenant_id" = "<oauth2_tenant_id>"

Ключ	Обязательный	Описание
`azure.blob.oauth2_client_id`	Да	Client ID Service Principal, который вы можете использовать для доступа к учетной записи Azure Blob Storage.
`azure.blob.oauth2_client_secret`	Да	Client Secret Service Principal, который вы можете использовать для доступа к учетной записи Azure Blob Storage.
`azure.blob.oauth2_tenant_id`	Да	Tenant ID Service Principal, который вы можете использовать для доступа к учетной записи Azure Blob Storage.

Azure Data Lake Storage Gen2

Если вы выбрали Data Lake Storage Gen2 в качестве системы хранения, выполните одно из следующих действий:

Для выбора метода аутентификации Managed Identity настройте StorageCredentialParams следующим образом:

"azure.adls2.oauth2_use_managed_identity" = "true",
"azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
"azure.adls2.oauth2_client_id" = "<service_client_id>"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Обязательный	Описание
`azure.adls2.oauth2_use_managed_identity`	Да	Указывает, включать ли метод аутентификации Managed Identity. Установите значение в `true`.
`azure.adls2.oauth2_tenant_id`	Да	ID tenant, к данным которого вы хотите получить доступ.
`azure.adls2.oauth2_client_id`	Да	Client (application) ID управляемой идентичности.

Для выбора метода аутентификации Shared Key настройте StorageCredentialParams следующим образом:

"azure.adls2.storage_account" = "<storage_account_name>",
"azure.adls2.shared_key" = "<storage_account_shared_key>"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Обязательный	Описание
`azure.adls2.storage_account`	Да	Имя пользователя вашей учетной записи хранения Data Lake Storage Gen2.
`azure.adls2.shared_key`	Да	Shared key вашей учетной записи хранения Data Lake Storage Gen2.

Для выбора метода аутентификации Service Principal настройте StorageCredentialParams следующим образом:

"azure.adls2.oauth2_client_id" = "<service_client_id>",
"azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
"azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Обязательный	Описание
`azure.adls2.oauth2_client_id`	Да	Client (application) ID service principal.
`azure.adls2.oauth2_client_secret`	Да	Значение нового созданного client (application) secret.
`azure.adls2.oauth2_client_endpoint`	Да	Конечная точка токена OAuth 2.0 (v1) service principal или application.

Azure Data Lake Storage Gen1

Если вы выбрали Data Lake Storage Gen1 в качестве системы хранения, выполните одно из следующих действий:

Для выбора метода аутентификации Managed Service Identity настройте StorageCredentialParams следующим образом:

"azure.adls1.use_managed_service_identity" = "true"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Обязательный	Описание
`azure.adls1.use_managed_service_identity`	Да	Указывает, включать ли метод аутентификации Managed Service Identity. Установите значение в `true`.

Для выбора метода аутентификации Service Principal настройте StorageCredentialParams следующим образом:

"azure.adls1.oauth2_client_id" = "<application_client_id>",
"azure.adls1.oauth2_credential" = "<application_client_credential>",
"azure.adls1.oauth2_endpoint" = "<OAuth_2.0_authorization_endpoint_v2>"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Обязательный	Описание
`azure.adls1.oauth2_client_id`	Да	Client (application) ID.
`azure.adls1.oauth2_credential`	Да	Значение нового созданного client (application) secret.
`azure.adls1.oauth2_endpoint`	Да	Конечная точка токена OAuth 2.0 (v1) service principal или application.

Другие S3-совместимые системы хранения

Если вы выбрали другую S3-совместимую систему хранения, такую как MinIO, настройте StorageCredentialParams следующим образом:

"aws.s3.enable_ssl" = "false",
"aws.s3.enable_path_style_access" = "true",
"aws.s3.endpoint" = "<s3_endpoint>",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>"

В следующей таблице описаны параметры, которые необходимо настроить в StorageCredentialParams.

Параметр	Обязательный	Описание
`aws.s3.enable_ssl`	Да	Указывает, включать ли SSL-соединение. Допустимые значения: `true` и `false`. Значение по умолчанию: `true`.
`aws.s3.enable_path_style_access`	Да	Указывает, включать ли доступ по URL в стиле пути. Допустимые значения: `true` и `false`. Значение по умолчанию: `false`. Для MinIO необходимо установить значение в `true`.
`aws.s3.endpoint`	Да	Конечная точка, которая используется для подключения к вашей S3-совместимой системе хранения вместо AWS S3.
`aws.s3.access_key`	Да	Ключ доступа вашего пользователя IAM.
`aws.s3.secret_key`	Да	Секретный ключ вашего пользователя IAM.

`columns_from_path`

Начиная с версии 3.2, Selena может извлекать значение пары ключ/значение из пути к файлу как значение столбца.

"columns_from_path" = "<column_name> [, ...]"

Предположим, файл данных file1 хранится по пути в формате /geo/country=US/city=LA/. Вы можете указать параметр columns_from_path как "columns_from_path" = "country, city" для извлечения географической информации из пути к файлу в качестве значения возвращаемых столбцов. Дополнительные инструкции см. в Примере 4.

`list_files_only`

Начиная с версии 3.4.0, FILES() поддерживает только перечисление файлов при их чтении.

"list_files_only" = "true"

Обратите внимание, что вам не нужно указывать data_format, когда list_files_only установлен в true.

Подробнее см. в разделе Возвращаемое значение.

`list_recursively`

Selena дополнительно поддерживает list_recursively для рекурсивного перечисления файлов и каталогов. list_recursively действует только когда list_files_only установлен в true. Значение по умолчанию: false.

"list_files_only" = "true",
"list_recursively" = "true"

Когда и list_files_only, и list_recursively установлены в true, Selena выполнит следующее:

Если указанный path является файлом (указанным явно или представленным подстановочными символами), Selena покажет информацию о файле.
Если указанный path является каталогом (указанным явно или представленным подстановочными символами, и независимо от того, заканчивается ли он на /), Selena покажет все файлы и подкаталоги в этом каталоге.

Подробнее см. в разделе Возвращаемое значение.

Возвращаемое значение

`SELECT FROM FILES()`

При использовании с SELECT, FILES() возвращает данные в файле как таблицу.

При запросе файлов CSV вы можете использовать $1, $2 и т.д. для представления каждого столбца в операторе SELECT или указать * для получения данных из всех столбцов.

SELECT * FROM FILES(
    "path" = "s3://inserttest/csv/file1.csv",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
)
WHERE $1 > 5;
+------+---------+------------+
| $1   | $2      | $3         |
+------+---------+------------+
|    6 | 0.34413 | 2017-11-25 |
|    7 | 0.40055 | 2017-11-26 |
|    8 | 0.42437 | 2017-11-27 |
|    9 | 0.67935 | 2017-11-27 |
|   10 | 0.22783 | 2017-11-29 |
+------+---------+------------+
5 rows in set (0.30 sec)

SELECT $1, $2 FROM FILES(
    "path" = "s3://inserttest/csv/file1.csv",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);
+------+---------+
| $1   | $2      |
+------+---------+
|    1 | 0.71173 |
|    2 | 0.16145 |
|    3 | 0.80524 |
|    4 | 0.91852 |
|    5 | 0.37766 |
|    6 | 0.34413 |
|    7 | 0.40055 |
|    8 | 0.42437 |
|    9 | 0.67935 |
|   10 | 0.22783 |
+------+---------+
10 rows in set (0.38 sec)

При запросе файлов Parquet или ORC вы можете напрямую указать имя нужных столбцов в операторе SELECT или указать * для получения данных из всех столбцов.

SELECT * FROM FILES(
    "path" = "s3://inserttest/parquet/file2.parquet",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
)
WHERE c1 IN (101,105);
+------+------+---------------------+
| c1   | c2   | c3                  |
+------+------+---------------------+
|  101 |    9 | 2018-05-15T18:30:00 |
|  105 |    6 | 2018-05-15T18:30:00 |
+------+------+---------------------+
2 rows in set (0.29 sec)

SELECT c1, c3 FROM FILES(
    "path" = "s3://inserttest/parquet/file2.parquet",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);
+------+---------------------+
| c1   | c3                  |
+------+---------------------+
|  101 | 2018-05-15T18:30:00 |
|  102 | 2018-05-15T18:30:00 |
|  103 | 2018-05-15T18:30:00 |
|  104 | 2018-05-15T18:30:00 |
|  105 | 2018-05-15T18:30:00 |
|  106 | 2018-05-15T18:30:00 |
|  107 | 2018-05-15T18:30:00 |
|  108 | 2018-05-15T18:30:00 |
|  109 | 2018-05-15T18:30:00 |
|  110 | 2018-05-15T18:30:00 |
+------+---------------------+
10 rows in set (0.55 sec)

При запросе файлов с list_files_only установленным в true, система вернет PATH, SIZE, IS_DIR (является ли данный путь каталогом) и MODIFICATION_TIME.

SELECT * FROM FILES(
    "path" = "s3://bucket/*.parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "list_files_only" = "true"
);
+-----------------------+------+--------+---------------------+
| PATH                  | SIZE | IS_DIR | MODIFICATION_TIME   |
+-----------------------+------+--------+---------------------+
| s3://bucket/1.parquet | 5221 |      0 | 2024-08-15 20:47:02 |
| s3://bucket/2.parquet | 5222 |      0 | 2024-08-15 20:54:57 |
| s3://bucket/3.parquet | 5223 |      0 | 2024-08-20 15:21:00 |
| s3://bucket/4.parquet | 5224 |      0 | 2024-08-15 11:32:14 |
+-----------------------+------+--------+---------------------+
4 rows in set (0.03 sec)

При запросе файлов с list_files_only и list_recursively установленными в true, система рекурсивно перечислит файлы и каталоги.

Предположим, путь s3://bucket/list/ содержит следующие файлы и подкаталоги:

s3://bucket/list/
├── basic1.csv
├── basic2.csv
├── orc0
│   └── orc1
│       └── basic_type.orc
├── orc1
│   └── basic_type.orc
└── parquet
    └── basic_type.parquet

Рекурсивное перечисление файлов и каталогов:

SELECT * FROM FILES(
    "path"="s3://bucket/list/",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "list_files_only" = "true",
    "list_recursively" = "true"
);
+---------------------------------------------+------+--------+---------------------+
| PATH                                        | SIZE | IS_DIR | MODIFICATION_TIME   |
+---------------------------------------------+------+--------+---------------------+
| s3://bucket/list                            |    0 |      1 | 2024-12-24 22:15:59 |
| s3://bucket/list/basic1.csv                 |   52 |      0 | 2024-12-24 11:35:53 |
| s3://bucket/list/basic2.csv                 |   34 |      0 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc0                       |    0 |      1 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc0/orc1                  |    0 |      1 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc0/orc1/basic_type.orc   | 1027 |      0 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc1                       |    0 |      1 | 2024-12-24 22:16:00 |
| s3://bucket/list/orc1/basic_type.orc        | 1027 |      0 | 2024-12-24 22:16:00 |
| s3://bucket/list/parquet                    |    0 |      1 | 2024-12-24 11:35:53 |
| s3://bucket/list/parquet/basic_type.parquet | 2281 |      0 | 2024-12-24 11:35:53 |
+---------------------------------------------+------+--------+---------------------+
10 rows in set (0.04 sec)

Нерекурсивное перечисление файлов и каталогов, соответствующих orc* в этом пути:

SELECT * FROM FILES(
    "path"="s3://bucket/list/orc*",
    "list_files_only" = "true",
    "list_recursively" = "false"
);
+--------------------------------------+------+--------+---------------------+
| PATH                                 | SIZE | IS_DIR | MODIFICATION_TIME   |
+--------------------------------------+------+--------+---------------------+
| s3://bucket/list/orc0/orc1           |    0 |      1 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc1/basic_type.orc | 1027 |      0 | 2024-12-24 22:16:00 |
+--------------------------------------+------+--------+---------------------+
2 rows in set (0.03 sec)

`DESC FILES()`

При использовании с DESC, FILES() возвращает схему файла.

DESC FILES(
    "path" = "s3://inserttest/lineorder.parquet",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);

+------------------+------------------+------+
| Field            | Type             | Null |
+------------------+------------------+------+
| lo_orderkey      | int              | YES  |
| lo_linenumber    | int              | YES  |
| lo_custkey       | int              | YES  |
| lo_partkey       | int              | YES  |
| lo_suppkey       | int              | YES  |
| lo_orderdate     | int              | YES  |
| lo_orderpriority | varchar(1048576) | YES  |
| lo_shippriority  | int              | YES  |
| lo_quantity      | int              | YES  |
| lo_extendedprice | int              | YES  |
| lo_ordtotalprice | int              | YES  |
| lo_discount      | int              | YES  |
| lo_revenue       | int              | YES  |
| lo_supplycost    | int              | YES  |
| lo_tax           | int              | YES  |
| lo_commitdate    | int              | YES  |
| lo_shipmode      | varchar(1048576) | YES  |
+------------------+------------------+------+
17 rows in set (0.05 sec)

При просмотре файлов с list_files_only установленным в true, система вернет свойства Type и Null для PATH, SIZE, IS_DIR (является ли данный путь каталогом) и MODIFICATION_TIME.

DESC FILES(
    "path" = "s3://bucket/*.parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "list_files_only" = "true"
);
+-------------------+------------------+------+
| Field             | Type             | Null |
+-------------------+------------------+------+
| PATH              | varchar(1048576) | YES  |
| SIZE              | bigint           | YES  |
| IS_DIR            | boolean          | YES  |
| MODIFICATION_TIME | datetime         | YES  |
+-------------------+------------------+------+
4 rows in set (0.00 sec)

`FILES()` для выгрузки

Начиная с версии 3.2.0, FILES() поддерживает запись данных в файлы в удаленном хранилище. Вы можете использовать INSERT INTO FILES() для выгрузки данных из Selena в удаленное хранилище.

Синтаксис

FILES( data_location , data_format [, StorageCredentialParams ] , unload_data_param )

Параметры

Все параметры задаются в виде пар "key" = "value".

`unload_data_param`

unload_data_param ::=
    "compression" = { "uncompressed" | "gzip" | "snappy" | "zstd | "lz4" },
    "partition_by" = "<column_name> [, ...]",
    "single" = { "true" | "false" } ,
    "target_max_file_size" = "<int>"

Ключ	Обязательный	Описание
`compression`	Да	Метод сжатия для использования при выгрузке данных. Допустимые значения: `uncompressed`: алгоритм сжатия не используется. `gzip`: использовать алгоритм сжатия gzip. `snappy`: использовать алгоритм сжатия SNAPPY. `zstd`: использовать алгоритм сжатия Zstd. `lz4`: использовать алгоритм сжатия LZ4. ПРИМЕЧАНИЕ Выгрузка в файлы CSV не поддерживает сжатие данных. Необходимо установить этот параметр в `uncompressed`.
`partition_by`	Нет	Список столбцов, используемых для разделения файлов данных на разные пути хранения. Несколько столбцов разделяются запятыми (,). `FILES()` извлекает информацию ключ/значение указанных столбцов и сохраняет файлы данных по путям хранения с извлеченной парой ключ/значение. Дополнительные инструкции см. в Примере 7.
`single`	Нет	Выгружать ли данные в один файл. Допустимые значения: `true`: данные сохраняются в одном файле данных. `false` (по умолчанию): данные сохраняются в нескольких файлах, если объем выгружаемых данных превышает 512 МБ.
`target_max_file_size`	Нет	Приблизительный максимальный размер каждого файла в партии для выгрузки. Единица измерения: байты. Значение по умолчанию: 1073741824 (1 ГБ). Когда размер выгружаемых данных превышает это значение, данные будут разделены на несколько файлов, и размер каждого файла не будет значительно превышать это значение. Введено в версии 3.2.7.

Примеры

Пример 1: Запрос данных из файла

Запрос данных из файла Parquet parquet/par-dup.parquet в bucket AWS S3 inserttest:

SELECT * FROM FILES(
     "path" = "s3://inserttest/parquet/par-dup.parquet",
     "format" = "parquet",
     "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
     "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
     "aws.s3.region" = "us-west-2"
);
+------+---------------------------------------------------------+
| c1   | c2                                                      |
+------+---------------------------------------------------------+
|    1 | {"1": "key", "1": "1", "111": "1111", "111": "aaaa"}    |
|    2 | {"2": "key", "2": "NULL", "222": "2222", "222": "bbbb"} |
+------+---------------------------------------------------------+
2 rows in set (22.335 sec)

Запрос данных из файлов Parquet в NFS(NAS):

SELECT * FROM FILES(
  'path' = 'file:///home/ubuntu/parquetfile/*.parquet',
  'format' = 'parquet'
);

Пример 2: Вставка строк данных из файла

Вставка строк данных из файла Parquet parquet/insert_wiki_edit_append.parquet в bucket AWS S3 inserttest в таблицу insert_wiki_edit:

INSERT INTO insert_wiki_edit
    SELECT * FROM FILES(
        "path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet",
        "format" = "parquet",
        "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
        "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
        "aws.s3.region" = "us-west-2"
);
Query OK, 2 rows affected (23.03 sec)
{'label':'insert_d8d4b2ee-ac5c-11ed-a2cf-4e1110a8f63b', 'status':'VISIBLE', 'txnId':'2440'}

Вставка строк данных из файлов CSV в NFS(NAS) в таблицу insert_wiki_edit:

INSERT INTO insert_wiki_edit
  SELECT * FROM FILES(
    'path' = 'file:///home/ubuntu/csvfile/*.csv',
    'format' = 'csv',
    'csv.column_separator' = ',',
    'csv.row_delimiter' = '\n'
  );

Пример 3: CTAS со строками данных из файла

Создание таблицы с именем ctas_wiki_edit и вставка строк данных из файла Parquet parquet/insert_wiki_edit_append.parquet в bucket AWS S3 inserttest в таблицу:

CREATE TABLE ctas_wiki_edit AS
    SELECT * FROM FILES(
        "path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet",
        "format" = "parquet",
        "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
        "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
        "aws.s3.region" = "us-west-2"
);
Query OK, 2 rows affected (22.09 sec)
{'label':'insert_1a217d70-2f52-11ee-9e4a-7a563fb695da', 'status':'VISIBLE', 'txnId':'3248'}

Пример 4: Запрос данных из файла и извлечение информации ключ/значение из его пути

Запрос данных из файла Parquet /geo/country=US/city=LA/file1.parquet (который содержит только два столбца - id и user) и извлечение информации ключ/значение из его пути как возвращаемых столбцов.

SELECT * FROM FILES(
    "path" = "hdfs://xxx.xx.xxx.xx:9000/geo/country=US/city=LA/file1.parquet",
    "format" = "parquet",
    "hadoop.security.authentication" = "simple",
    "username" = "xxxxx",
    "password" = "xxxxx",
    "columns_from_path" = "country, city"
);
+------+---------+---------+------+
| id   | user    | country | city |
+------+---------+---------+------+
|    1 | richard | US      | LA   |
|    2 | amber   | US      | LA   |
+------+---------+---------+------+
2 rows in set (3.84 sec)

Пример 5: Автоматическое определение схемы и объединение

Следующий пример основан на двух файлах Parquet в bucket S3:

Файл 1 содержит три столбца - INT столбец c1, FLOAT столбец c2 и DATE столбец c3.

c1,c2,c3
1,0.71173,2017-11-20
2,0.16145,2017-11-21
3,0.80524,2017-11-22
4,0.91852,2017-11-23
5,0.37766,2017-11-24
6,0.34413,2017-11-25
7,0.40055,2017-11-26
8,0.42437,2017-11-27
9,0.67935,2017-11-27
10,0.22783,2017-11-29

Файл 2 содержит три столбца - INT столбец c1, INT столбец c2 и DATETIME столбец c3.

c1,c2,c3
101,9,2018-05-15T18:30:00
102,3,2018-05-15T18:30:00
103,2,2018-05-15T18:30:00
104,3,2018-05-15T18:30:00
105,6,2018-05-15T18:30:00
106,1,2018-05-15T18:30:00
107,8,2018-05-15T18:30:00
108,5,2018-05-15T18:30:00
109,6,2018-05-15T18:30:00
110,8,2018-05-15T18:30:00

Использование оператора CTAS для создания таблицы с именем test_ctas_parquet и вставки строк данных из двух файлов Parquet в таблицу:

CREATE TABLE test_ctas_parquet AS
SELECT * FROM FILES(
    "path" = "s3://inserttest/parquet/*",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);

Просмотр схемы таблицы test_ctas_parquet:

SHOW CREATE TABLE test_ctas_parquet\G

*************************** 1. row ***************************
       Table: test_ctas_parquet
Create Table: CREATE TABLE `test_ctas_parquet` (
  `c1` bigint(20) NULL COMMENT "",
  `c2` decimal(38, 9) NULL COMMENT "",
  `c3` varchar(1048576) NULL COMMENT ""
) ENGINE=OLAP
DUPLICATE KEY(`c1`, `c2`)
COMMENT "OLAP"
DISTRIBUTED BY RANDOM
PROPERTIES (
"bucket_size" = "4294967296",
"compression" = "LZ4",
"replication_num" = "3"
);

Результат показывает, что столбец c2, который содержит данные FLOAT и INT, объединен в столбец DECIMAL, а c3, который содержит данные DATE и DATETIME, объединен в столбец VARCHAR.

Вышеуказанный результат остается таким же, когда файлы Parquet заменены на файлы CSV, содержащие те же данные:

CREATE TABLE test_ctas_csv AS
  SELECT * FROM FILES(
    "path" = "s3://inserttest/csv/*",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);
Query OK, 0 rows affected (30.90 sec)

SHOW CREATE TABLE test_ctas_csv\G
*************************** 1. row ***************************
       Table: test_ctas_csv
Create Table: CREATE TABLE `test_ctas_csv` (
  `c1` bigint(20) NULL COMMENT "",
  `c2` decimal(38, 9) NULL COMMENT "",
  `c3` varchar(1048576) NULL COMMENT ""
) ENGINE=OLAP
DUPLICATE KEY(`c1`, `c2`)
COMMENT "OLAP"
DISTRIBUTED BY RANDOM
PROPERTIES (
"bucket_size" = "4294967296",
"compression" = "LZ4",
"replication_num" = "3"
);
1 row in set (0.27 sec)

Объединение схемы файлов Parquet и разрешение системе назначать значения NULL несуществующим столбцам путем установки fill_mismatch_column_with в null:

SELECT * FROM FILES(
  "path" = "s3://inserttest/basic_type.parquet,s3://inserttest/basic_type_k2k5k7.parquet",
  "format" = "parquet",
  "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
  "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
  "aws.s3.region" = "us-west-2",
  "fill_mismatch_column_with" = "null"
);
+------+------+------+-------+------------+---------------------+------+------+
| k1   | k2   | k3   | k4    | k5         | k6                  | k7   | k8   |
+------+------+------+-------+------------+---------------------+------+------+
| NULL |   21 | NULL |  NULL | 2024-10-03 | NULL                | c    | NULL |
|    0 |    1 |    2 |  3.20 | 2024-10-01 | 2024-10-01 12:12:12 | a    |  4.3 |
|    1 |   11 |   12 | 13.20 | 2024-10-02 | 2024-10-02 13:13:13 | b    | 14.3 |
+------+------+------+-------+------------+---------------------+------+------+
3 rows in set (0.03 sec)

Пример 6: Просмотр схемы файла

Просмотр схемы файла Parquet lineorder, хранящегося в AWS S3, с помощью DESC.

DESC FILES(
    "path" = "s3://inserttest/lineorder.parquet",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);

+------------------+------------------+------+
| Field            | Type             | Null |
+------------------+------------------+------+
| lo_orderkey      | int              | YES  |
| lo_linenumber    | int              | YES  |
| lo_custkey       | int              | YES  |
| lo_partkey       | int              | YES  |
| lo_suppkey       | int              | YES  |
| lo_orderdate     | int              | YES  |
| lo_orderpriority | varchar(1048576) | YES  |
| lo_shippriority  | int              | YES  |
| lo_quantity      | int              | YES  |
| lo_extendedprice | int              | YES  |
| lo_ordtotalprice | int              | YES  |
| lo_discount      | int              | YES  |
| lo_revenue       | int              | YES  |
| lo_supplycost    | int              | YES  |
| lo_tax           | int              | YES  |
| lo_commitdate    | int              | YES  |
| lo_shipmode      | varchar(1048576) | YES  |
+------------------+------------------+------+
17 rows in set (0.05 sec)

Пример 7: Выгрузка данных

Выгрузка всех строк данных из sales_records в несколько файлов Parquet по пути /unload/partitioned/ в cluster HDFS. Эти файлы сохраняются в разных подпутях, различающихся значениями в столбце sales_time.

INSERT INTO FILES(
    "path" = "hdfs://xxx.xx.xxx.xx:9000/unload/partitioned/",
    "format" = "parquet",
    "hadoop.security.authentication" = "simple",
    "username" = "xxxxx",
    "password" = "xxxxx",
    "compression" = "lz4",
    "partition_by" = "sales_time"
)
SELECT * FROM sales_records;

Выгрузка результатов запроса в файлы CSV и Parquet в NFS(NAS):

-- CSV
INSERT INTO FILES(
    'path' = 'file:///home/ubuntu/csvfile/',
    'format' = 'csv',
    'csv.column_separator' = ',',
    'csv.row_delimitor' = '\n'
)
SELECT * FROM sales_records;

-- Parquet
INSERT INTO FILES(
    'path' = 'file:///home/ubuntu/parquetfile/',
    'format' = 'parquet'
)
SELECT * FROM sales_records;

Пример 8: Файлы Avro

Загрузка файла Avro:

INSERT INTO avro_tbl
  SELECT * FROM FILES(
    "path" = "hdfs://xxx.xx.xx.x:yyyy/avro/primitive.avro",
    "format" = "avro"
);

Запрос данных из файла Avro:

SELECT * FROM FILES("path" = "hdfs://xxx.xx.xx.x:yyyy/avro/complex.avro", "format" = "avro")\G
*************************** 1. row ***************************
record_field: {"id":1,"name":"avro"}
  enum_field: HEARTS
 array_field: ["one","two","three"]
   map_field: {"a":1,"b":2}
 union_field: 100
 fixed_field: 0x61626162616261626162616261626162
1 row in set (0.05 sec)

Просмотр схемы файла Avro:

DESC FILES("path" = "hdfs://xxx.xx.xx.x:yyyy/avro/logical.avro", "format" = "avro");
+------------------------+------------------+------+
| Field                  | Type             | Null |
+------------------------+------------------+------+
| decimal_bytes          | decimal(10,2)    | YES  |
| decimal_fixed          | decimal(10,2)    | YES  |
| uuid_string            | varchar(1048576) | YES  |
| date                   | date             | YES  |
| time_millis            | int              | YES  |
| time_micros            | bigint           | YES  |
| timestamp_millis       | datetime         | YES  |
| timestamp_micros       | datetime         | YES  |
| local_timestamp_millis | bigint           | YES  |
| local_timestamp_micros | bigint           | YES  |
| duration               | varbinary(12)    | YES  |
+------------------------+------------------+------+

Пример 9: Доступ к Azure Blob Storage с использованием Managed Identity и Service Principal

-- Managed Identity
SELECT * FROM FILES(
    "path" = "wasbs://storage-container@storage-account.blob.core.windows.net/ssb_1g/customer/*",
    "format" = "parquet",
    "azure.blob.oauth2_use_managed_identity" = "true",
    "azure.blob.oauth2_client_id" = "1d6bfdec-dd34-4260-b8fd-aaaaaaaaaaaa"
);
-- Service Principal
SELECT * FROM FILES(
    "path" = "wasbs://storage-container@storage-account.blob.core.windows.net/ssb_1g/customer/*",
    "format" = "parquet",
    "azure.blob.oauth2_client_id" = "1d6bfdec-dd34-4260-b8fd-bbbbbbbbbbbb",
    "azure.blob.oauth2_client_secret" = "C2M8Q~ZXXXXXX_5XsbDCeL2dqP7hIR60xxxxxxxx",
    "azure.blob.oauth2_tenant_id" = "540e19cc-386b-4a44-a7b8-cccccccccccc"
);

Пример 10: Файл CSV

Запрос данных из файла CSV:

SELECT * FROM FILES(                                                                                                                                                     "path" = "s3://test-bucket/file1.csv",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\r\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);
+------+---------+--------------+
| $1   | $2      | $3           |
+------+---------+--------------+
|    1 | 0.71173 | 2017-11-20   |
|    2 | 0.16145 | 2017-11-21   |
|    3 | 0.80524 | 2017-11-22   |
|    4 | 0.91852 | 2017-11-23   |
|    5 | 0.37766 | 2017-11-24   |
|    6 | 0.34413 | 2017-11-25   |
|    7 | 0.40055 | 2017-11-26   |
|    8 | 0.42437 | 2017-11-27   |
|    9 | 0.67935 | 2017-11-27   |
|   10 | 0.22783 | 2017-11-29   |
+------+---------+--------------+
10 rows in set (0.33 sec)

Загрузка файла CSV:

INSERT INTO csv_tbl
  SELECT * FROM FILES(
    "path" = "s3://test-bucket/file1.csv",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\r\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);

Пример 11: Использование региональных конечных точек AWS STS

Здесь показаны два случая:

Использование региональной конечной точки STS вне среды AWS.
Использование STS внутри среды AWS (например, EC2).

Вне среды AWS

important

При работе вне среды AWS и использовании региональной STS требуется установить "aws.s3.use_instance_profile" = "false".

SELECT COUNT(*)
FROM FILES("path" = "s3://aws-bucket/path/file.csv.gz",
    "format" = "csv",
    "compression" = "gzip",
    "aws.s3.endpoint"="https://s3.us-east-1.amazonaws.com",
    "aws.s3.region"="us-east-1",
    "aws.s3.use_aws_sdk_default_behavior" = "false",
    "aws.s3.use_instance_profile" = "false",
    "aws.s3.access_key" = "****",
    "aws.s3.secret_key" = "****",
    "aws.s3.iam_role_arn"="arn:aws:iam::1234567890:role/access-role",
    "aws.s3.sts.region" = "{sts_region}",
    "aws.s3.sts.endpoint" = "{sts_endpoint}"
);

Внутри среды AWS

SELECT COUNT(*)
FROM FILES("path" = "s3://aws-bucket/path/file.csv.gz",
    "format" = "csv",
    "compression" = "gzip",
    "aws.s3.endpoint"="https://s3.us-east-1.amazonaws.com",
    "aws.s3.region"="us-east-1",
    "aws.s3.use_aws_sdk_default_behavior" = "false",
    "aws.s3.use_instance_profile" = "true",
    "aws.s3.access_key" = "****",
    "aws.s3.secret_key" = "****",
    "aws.s3.iam_role_arn"="arn:aws:iam::1234567890:role/access-role",
    "aws.s3.sts.region" = "{sts_region}",
    "aws.s3.sts.endpoint" = "{sts_endpoint}"
);

FILES() для загрузки​

Синтаксис​

Параметры​

data_location​

data_format​

Parquet​

parquet.use_legacy_encoding​

parquet.version​

CSV​

csv.column_separator​

csv.enclose​

csv.skip_header​

csv.escape​

schema_detect​

Проверка схемы целевой таблицы с проталкиванием​

Объединение файлов с разной схемой​

Вывод типа STRUCT из Parquet​

StorageCredentialParams​

HDFS​

AWS S3​

Региональные конечные точки AWS STS​

Google GCS​

Azure Blob Storage​

Azure Data Lake Storage Gen2​

Azure Data Lake Storage Gen1​

Другие S3-совместимые системы хранения​

columns_from_path​

list_files_only​

list_recursively​

Возвращаемое значение​

SELECT FROM FILES()​

DESC FILES()​

FILES() для выгрузки​

Синтаксис​

Параметры​

data_location​

data_format​

StorageCredentialParams​

unload_data_param​

Примеры​

Пример 1: Запрос данных из файла​

Пример 2: Вставка строк данных из файла​

Пример 3: CTAS со строками данных из файла​

Пример 4: Запрос данных из файла и извлечение информации ключ/значение из его пути​

Пример 5: Автоматическое определение схемы и объединение​

Пример 6: Просмотр схемы файла​

Пример 7: Выгрузка данных​

Пример 8: Файлы Avro​

Пример 9: Доступ к Azure Blob Storage с использованием Managed Identity и Service Principal​

Пример 10: Файл CSV​

Пример 11: Использование региональных конечных точек AWS STS​

Вне среды AWS​

Внутри среды AWS​

`FILES()` для загрузки

Синтаксис

Параметры

`data_location`

`data_format`

Parquet

`parquet.use_legacy_encoding`

`parquet.version`

CSV

`csv.column_separator`

`csv.enclose`

`csv.skip_header`

`csv.escape`

`schema_detect`

Проверка схемы целевой таблицы с проталкиванием

Объединение файлов с разной схемой

Вывод типа STRUCT из Parquet

`StorageCredentialParams`

HDFS

AWS S3

Региональные конечные точки AWS STS

Google GCS

Azure Blob Storage

Azure Data Lake Storage Gen2

Azure Data Lake Storage Gen1

Другие S3-совместимые системы хранения

`columns_from_path`

`list_files_only`

`list_recursively`

Возвращаемое значение

`SELECT FROM FILES()`

`DESC FILES()`

`FILES()` для выгрузки

Синтаксис

Параметры

data_location

data_format

StorageCredentialParams

`unload_data_param`

Примеры

Пример 1: Запрос данных из файла

Пример 2: Вставка строк данных из файла

Пример 3: CTAS со строками данных из файла

Пример 4: Запрос данных из файла и извлечение информации ключ/значение из его пути

Пример 5: Автоматическое определение схемы и объединение

Пример 6: Просмотр схемы файла

Пример 7: Выгрузка данных

Пример 8: Файлы Avro

Пример 9: Доступ к Azure Blob Storage с использованием Managed Identity и Service Principal

Пример 10: Файл CSV

Пример 11: Использование региональных конечных точек AWS STS

Вне среды AWS

Внутри среды AWS