Версия: 1.5.x

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

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

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

примечание

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

Ограничения

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

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

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

Создание базы данных (Необязательно)

После подключения к кластеру Selena вы можете создать внешнюю таблицу файлов в существующей базе данных или создать новую базу данных для управления внешними таблицами файлов. Для запроса существующих баз данных в кластере выполните 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-`. Этот параметр поддерживается начиная с версии 1.5.0.

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

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

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