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

Файловая внешняя таблица — это особый тип внешней таблицы. Она позволяет напрямую выполнять запросы к файлам данных 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.