Версия: 2.0.x

Файловая внешняя таблица

Файловая внешняя таблица — это особый тип внешней таблицы. Она позволяет напрямую выполнять запросы к файлам данных Parquet и ORC во внешних системах хранения без загрузки данных в Selena. Кроме того, файловые внешние таблицы не зависят от metastore. В текущей версии Selena поддерживает следующие внешние системы хранения: HDFS, Amazon S3 и другие S3-совместимые системы хранения.

Эта функция поддерживается начиная с Selena v1.5.2.

примечание

Начиная с версии 3.1 Selena поддерживает прямую загрузку данных из файлов в облачном хранилище с помощью команды INSERT и функции FILES, поэтому вам не нужно сначала создавать внешний каталог или файловую внешнюю таблицу. Кроме того, FILES() может автоматически определять схему таблицы из файлов, что значительно упрощает процесс загрузки данных.
Функция файловых внешних таблиц была разработана для помощи в загрузке данных в Selena, а НЕ для эффективного выполнения запросов к внешним системам в качестве обычной операции. Более производительным решением будет загрузка данных в Selena.

Ограничения

Файловые внешние таблицы должны создаваться в базах данных внутри default_catalog. Вы можете выполнить SHOW CATALOGS для просмотра каталогов, созданных в cluster.
Поддерживаются только файлы данных Parquet, ORC, Avro, RCFile и SequenceFile.
Вы можете использовать файловые внешние таблицы только для выполнения запросов к данным в целевом файле данных. Операции записи данных, такие как INSERT, DELETE и DROP, не поддерживаются.

Предварительные требования

Перед созданием файловой внешней таблицы необходимо настроить cluster Selena так, чтобы Selena могла получить доступ к внешней системе хранения, где находится целевой файл данных. Конфигурации, необходимые для файловой внешней таблицы, такие же, как и для каталога Hive, за исключением того, что вам не нужно настраивать metastore. См. Каталог Hive - Подготовка к интеграции для получения дополнительной информации о конфигурациях.

Создание базы данных (опционально)

После подключения к cluster Selena вы можете создать файловую внешнюю таблицу в существующей базе данных или создать новую базу данных для управления файловыми внешними таблицами. Чтобы просмотреть существующие базы данных в cluster, выполните SHOW DATABASES. Затем вы можете выполнить USE <db_name> для переключения на целевую базу данных.

Синтаксис создания базы данных следующий.

CREATE DATABASE [IF NOT EXISTS] <db_name>

Создание файловой внешней таблицы

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

Синтаксис

CREATE EXTERNAL TABLE <table_name>
(
    <col_name> <col_type> [NULL | NOT NULL] [COMMENT "<comment>"]
)
ENGINE=file
COMMENT ["comment"]
PROPERTIES
(
    FileLayoutParams,
    StorageCredentialParams
)

Параметры

Параметр	Обязательный	Описание
table_name	Да	Имя файловой внешней таблицы. Соглашения об именовании следующие: Имя может содержать буквы, цифры (0-9) и символы подчеркивания (_). Должно начинаться с буквы. Имя не может превышать 64 символа.
col_name	Да	Имя столбца в файловой внешней таблице. Имена столбцов в файловой внешней таблице должны совпадать с именами в целевом файле данных, но не чувствительны к регистру. Порядок столбцов в файловой внешней таблице может отличаться от порядка в целевом файле данных.
col_type	Да	Тип столбца в файловой внешней таблице. Этот параметр необходимо указать на основе типа столбца в целевом файле данных. Дополнительную информацию см. в разделе Сопоставление типов столбцов.
NULL \| NOT NULL	Нет	Допускается ли NULL для столбца в файловой внешней таблице. NULL: NULL допускается. NOT NULL: NULL не допускается. Этот модификатор необходимо указывать на основе следующих правил: Если этот параметр не указан для столбцов в целевом файле данных, вы можете не указывать его для столбцов в файловой внешней таблице или указать NULL для столбцов в файловой внешней таблице. Если NULL указан для столбцов в целевом файле данных, вы можете не указывать этот параметр для столбцов в файловой внешней таблице или указать NULL для столбцов в файловой внешней таблице. Если NOT NULL указан для столбцов в целевом файле данных, вы также должны указать NOT NULL для столбцов в файловой внешней таблице.
comment	Нет	Комментарий к столбцу в файловой внешней таблице.
ENGINE	Да	Тип движка. Установите значение file.
comment	Нет	Описание файловой внешней таблицы.
PROPERTIES	Да	`FileLayoutParams`: указывает путь и формат целевого файла. Это свойство обязательно. `StorageCredentialParams`: указывает информацию аутентификации, необходимую для доступа к системам объектного хранения. Это свойство обязательно только для AWS S3 и других S3-совместимых систем хранения.

FileLayoutParams

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

"path" = "<file_path>",
"format" = "<file_format>"
"enable_recursive_listing" = "{ true | false }"
"enable_wildcards" = "{ true | false }"

Параметр	Обязательный	Описание
path	Да	Путь к файлу данных. Если файл данных хранится в HDFS, формат пути: `hdfs://<IP-адрес HDFS>:<порт>/<путь>`. Порт по умолчанию — 8020. Если вы используете порт по умолчанию, указывать его не нужно. Если файл данных хранится в AWS S3 или другой S3-совместимой системе хранения, формат пути: `s3://<имя бакета>/<папка>/`. Обратите внимание на следующие правила при вводе пути: Если вы хотите получить доступ ко всем файлам в пути, завершите этот параметр косой чертой (`/`), например, `hdfs://x.x.x.x/user/hive/warehouse/array2d_parq/data/`. При выполнении запроса Selena просматривает все файлы данных в этом пути. Она не обходит файлы данных рекурсивно. Если вы хотите получить доступ к одному файлу, введите путь, который напрямую указывает на этот файл, например, `hdfs://x.x.x.x/user/hive/warehouse/array2d_parq/data`. При выполнении запроса Selena сканирует только этот файл данных.
format	Да	Формат файла данных. Допустимые значения: `parquet`, `orc`, `avro`, `rctext` или `rcbinary` и `sequence`.
enable_recursive_listing	Нет	Указывает, следует ли рекурсивно обходить все файлы в текущем пути. Значение по умолчанию: `true`. Значение `true` указывает на рекурсивный обход подкаталогов, а значение `false` указывает на игнорирование подкаталогов.
enable_wildcards	Нет	Поддерживать ли использование подстановочных знаков (``) в `path`. Значение по умолчанию: `false`. Например, `2024-07-` соответствует всем файлам с префиксом `2024-07-`. Этот параметр поддерживается начиная с версии 3.1.9.

StorageCredentialParams (опционально)

Набор параметров о том, как Selena интегрируется с целевой системой хранения. Этот набор параметров опционален.

Вам нужно настроить StorageCredentialParams только когда целевая система хранения — AWS S3 или другое S3-совместимое хранилище.

Для других систем хранения вы можете игнорировать StorageCredentialParams.

AWS S3

Если вам нужен доступ к файлу данных, хранящемуся в AWS S3, настройте следующие параметры аутентификации в StorageCredentialParams.

Если вы выбираете метод аутентификации на основе профиля экземпляра, настройте 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" = "<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>"

Имя параметра	Обязательный	Описание
aws.s3.use_instance_profile	Да	Указывает, следует ли включить метод аутентификации на основе профиля экземпляра и метод аутентификации на основе предполагаемой роли при доступе к AWS S3. Допустимые значения: `true` и `false`. Значение по умолчанию: `false`.
aws.s3.iam_role_arn	Да	ARN роли IAM, которая имеет привилегии на ваш бакет AWS S3. Если вы используете метод аутентификации на основе предполагаемой роли для доступа к AWS S3, вы должны указать этот параметр. Тогда Selena примет эту роль при доступе к целевому файлу данных.
aws.s3.region	Да	Регион, в котором находится ваш бакет 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, см. в разделе Параметры аутентификации для доступа к AWS S3.

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	Да	Указывает, следует ли включить доступ в стиле пути. Допустимые значения: `true` и `false`. Значение по умолчанию: `false`. Для MinIO вы должны установить значение `true`. URL в стиле пути используют следующий формат: `https://s3.<region_code>.amazonaws.com/<bucket_name>/<key_name>`. Например, если вы создаете бакет с именем `DOC-EXAMPLE-BUCKET1` в регионе US West (Oregon) и хотите получить доступ к объекту `alice.jpg` в этом бакете, вы можете использовать следующий URL в стиле пути: `https://s3.us-west-2.amazonaws.com/DOC-EXAMPLE-BUCKET1/alice.jpg`.
aws.s3.endpoint	Да	Конечная точка, используемая для подключения к S3-совместимой системе хранения вместо AWS S3.
aws.s3.access_key	Да	Ключ доступа вашего пользователя IAM.
aws.s3.secret_key	Да	Секретный ключ вашего пользователя IAM.

Сопоставление типов столбцов

В следующей таблице представлено сопоставление типов столбцов между целевым файлом данных и файловой внешней таблицей.

Файл данных	Файловая внешняя таблица
INT/INTEGER	INT
BIGINT	BIGINT
TIMESTAMP	DATETIME. Обратите внимание, что TIMESTAMP преобразуется в DATETIME без часового пояса на основе настройки часового пояса текущей сессии и теряет часть своей точности.
STRING	STRING
VARCHAR	VARCHAR
CHAR	CHAR
DOUBLE	DOUBLE
FLOAT	FLOAT
DECIMAL	DECIMAL
BOOLEAN	BOOLEAN
ARRAY	ARRAY
MAP	MAP
STRUCT	STRUCT

Примеры

HDFS

Создание файловой внешней таблицы с именем t0 для выполнения запросов к файлам данных Parquet, хранящимся в пути HDFS.

USE db_example;

CREATE EXTERNAL TABLE t0
(
    name string,
    id int
)
ENGINE=file
PROPERTIES
(
    "path"="hdfs://x.x.x.x:8020/user/hive/warehouse/person_parq/",
    "format"="parquet"
);

AWS S3

Пример 1: Создание файловой внешней таблицы и использование профиля экземпляра для доступа к одному файлу Parquet в AWS S3.

USE db_example;

CREATE EXTERNAL TABLE table_1
(
    name string,
    id int
)
ENGINE=file
PROPERTIES
(
    "path" = "s3://bucket-test/folder1/raw_0.parquet",
    "format" = "parquet",
    "aws.s3.use_instance_profile" = "true",
    "aws.s3.region" = "us-west-2"
);

Пример 2: Создание файловой внешней таблицы и использование предполагаемой роли для доступа ко всем файлам ORC в целевом пути файла в AWS S3.

USE db_example;

CREATE EXTERNAL TABLE table_1
(
    name string,
    id int
)
ENGINE=file
PROPERTIES
(
    "path" = "s3://bucket-test/folder1/",
    "format" = "orc",
    "aws.s3.use_instance_profile" = "true",
    "aws.s3.iam_role_arn" = "arn:aws:iam::51234343412:role/role_name_in_aws_iam",
    "aws.s3.region" = "us-west-2"
);

Пример 3: Создание файловой внешней таблицы и использование пользователя IAM для доступа ко всем файлам ORC в пути файла в AWS S3.

USE db_example;

CREATE EXTERNAL TABLE table_1
(
    name string,
    id int
)
ENGINE=file
PROPERTIES
(
    "path" = "s3://bucket-test/folder1/",
    "format" = "orc",
    "aws.s3.use_instance_profile" = "false",
    "aws.s3.access_key" = "<iam_user_access_key>",
    "aws.s3.secret_key" = "<iam_user_access_key>",
    "aws.s3.region" = "us-west-2"
);

Выполнение запросов к файловой внешней таблице

Синтаксис:

SELECT <clause> FROM <file_external_table>

Например, чтобы выполнить запрос к данным из файловой внешней таблицы t0, созданной в разделе Примеры - HDFS, выполните следующую команду:

SELECT * FROM t0;

+--------+------+
| name   | id   |
+--------+------+
| jack   |    2 |
| lily   |    1 |
+--------+------+
2 rows in set (0.08 sec)

Управление файловыми внешними таблицами

Вы можете просмотреть схему таблицы с помощью DESC или удалить таблицу с помощью DROP TABLE.

Ограничения​

Предварительные требования​

Создание базы данных (опционально)​

Создание файловой внешней таблицы​

Синтаксис​

Параметры​

FileLayoutParams​

StorageCredentialParams (опционально)​

AWS S3​

S3-совместимое хранилище​

Сопоставление типов столбцов​

Примеры​

HDFS​

AWS S3​

Выполнение запросов к файловой внешней таблице​

Управление файловыми внешними таблицами​

Ограничения

Предварительные требования

Создание базы данных (опционально)

Создание файловой внешней таблицы

Синтаксис

Параметры

FileLayoutParams

StorageCredentialParams (опционально)

AWS S3

S3-совместимое хранилище

Сопоставление типов столбцов

Примеры

HDFS

AWS S3

Выполнение запросов к файловой внешней таблице

Управление файловыми внешними таблицами