S3
Описание
Табличная функция S3 (TVF) позволяет читать файлы из объектного хранилища, совместимого с S3, и обращаться к ним как к данным реляционной таблицы. В настоящее время поддерживаются форматы файлов csv/csv_with_names/csv_with_names_and_types/json/parquet/orc.
Синтаксис
S3(
"uri" = "<uri>",
"s3.access_key" = "<s3_access_key>",
"s3.secret_key" = "<s3_secret_key>",
"s3.region" = "<s3_region>",
"s3.endpoint" = "<s3_endpoint>",
"format" = "<format>"
[, "<optional_property_key>" = "<optional_property_value>" [, ...] ]
)
Обязательные параметры
| Параметр | Описание |
|---|---|
uri | URI для доступа к S3. Поддерживает подстановочные знаки и шаблоны диапазонов. Подробнее см. в разделе Шаблон пути к файлу. Функция использует Path Style или Virtual-hosted Style в зависимости от параметра use_path_style |
s3.access_key | Ключ доступа к S3 |
s3.secret_key | Секретный ключ для S3 |
s3.region | Регион S3 |
s3.endpoint | Адрес конечной точки S3 |
format | Формат файла; поддерживаются csv/csv_with_names/csv_with_names_and_types/json/parquet/orc |
Необязательные параметры
| Параметр | По умолчанию | Описание | Примечания |
|---|---|---|---|
s3.session_token | - | Токен сессии S3 | |
use_path_style | false | S3 SDK по умолчанию использует Virtual-hosted Style. Некоторые системы объектного хранения могут не поддерживать Virtual-hosted Style. Этот параметр позволяет принудительно использовать доступ в стиле Path Style. Например, MinIO по умолчанию допускает только Path Style, поэтому при обращении к MinIO следует задать use_path_style=true | |
force_parsing_by_standard_uri | false | Принудительно разбирает нестандартные URI как стандартные | |
column_separator | \t | Разделитель столбцов | |
line_delimiter | \n | Разделитель строк | |
compress_type | UNKNOWN | Тип сжатия. В настоящее время поддерживаются UNKNOWN/PLAIN/GZ/LZO/BZ2/LZ4FRAME/DEFLATE/SNAPPYBLOCK; тип определяется автоматически по суффиксу uri | |
read_json_by_line | "true" | Для загрузки данных в формате JSON | Загрузка JSON |
strip_outer_array | "false" | Для загрузки данных в формате JSON | Загрузка JSON |
json_root | Пусто | Для загрузки данных в формате JSON | Загрузка JSON |
jsonpaths | Пусто | Для загрузки данных в формате JSON | Загрузка JSON |
num_as_string | false | Для загрузки данных в формате JSON | Загрузка JSON |
fuzzy_parse | false | Для загрузки данных в формате JSON | |
trim_double_quotes | false | Для загрузки данных в формате CSV; удаляет внешние двойные кавычки из каждого поля | |
skip_lines | 0 | Пропускает первые N строк файла CSV. Этот параметр не действует при использовании формата csv_with_names или csv_with_names_and_types | |
path_partition_keys | - | Задаёт имена столбцов партиционирования в пути к файлу. Например, для пути /path/to/city=beijing/date="2023-07-09" задайте path_partition_keys="city,date", чтобы автоматически считать имена и значения столбцов из пути | |
resource | - | Задаёт имя Resource. S3 TVF может использовать существующий S3 Resource для прямого доступа к S3. О создании S3 Resource см. CREATE-RESOURCE. Поддерживается с версии 2.1.4. | |
enable_mapping_varbinary | true | В версии dev принимается только для совместимости и игнорируется: внешние двоичные данные всегда сопоставляются с VARBINARY. В Doris 4.1.5 этот параметр TVF остаётся настраиваемым со значением по умолчанию false. | Поддерживается с версии 4.0.3 |
enable_mapping_timestamp_tz | true | Начиная с 4.1.5 принимается только для совместимости; значение игнорируется. Parquet Timestamp с isAdjustedToUTC=true и ORC TIMESTAMP_INSTANT всегда сопоставляются с TIMESTAMPTZ, даже если этот параметр имеет значение false. | Поддерживается с версии 4.0.3 |
hive.parquet.time-zone | Пустая строка | Необязательная строка, по умолчанию пустая. Поддерживается с версии 4.1.5. Задаёт часовой пояс, используемый при записи Parquet INT96: часовой пояс IANA или смещение от -12:00 до +14:00; короткие псевдонимы, такие как CST и PRC, не принимаются. См. Parquet. | Начиная с 4.1.5 |
Примечания
-
Для AWS S3 стандартные стили URI включают:
-
Стиль клиента AWS (стиль Hadoop S3)
s3://my-bucket/path/to/file?versionId=abc123&partNumber=77&partNumber=88 -
Стиль Virtual Host
https://my-bucket.s3.us-west-1.amazonaws.com/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88 -
Стиль Path
https://s3.us-west-1.amazonaws.com/my-bucket/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88
Помимо этих трёх стандартных стилей URI, поддерживаются и другие, менее распространённые:
-
Смешанный стиль Virtual Host и клиента AWS (Hadoop S3)
s3://my-bucket.s3.us-west-1.amazonaws.com/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88 -
Смешанный стиль Path и клиента AWS (Hadoop S3)
s3://s3.us-west-1.amazonaws.com/my-bucket/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88
Подробные примеры использования приведены ниже.
-
-
Для прямого выполнения запросов к TVF или создания представления на основе этой TVF требуется право USAGE на Resource. Для запроса к представлению, созданному на основе TVF, достаточно права SELECT на это представление.
Примеры
-
Чтение файлов формата CSV из объектного хранилища, совместимого с S3, и доступ к ним
select * from s3("uri" = "http://127.0.0.1:9312/test2/student1.csv",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "csv",
"use_path_style" = "true") order by c1; -
Можно использовать с
desc functiondesc function s3("uri" = "http://127.0.0.1:9312/test2/student1.csv",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "csv",
"use_path_style" = "true"); -
Использование различных схем URL
Примеры использования
http://,https://:-- Note URI Bucket notation and use_path_style parameter setting, same for HTTP.
-- Since "use_path_style"="true" is set, Path Style will be used to access S3.
select * from s3(
"uri" = "https://endpoint/bucket/file/student.csv",
"s3.access_key"= "ak",
"s3.secret_key" = "sk",
"s3.endpoint" = "endpoint",
"s3.region" = "region",
"format" = "csv",
"use_path_style"="true");
-- Note URI Bucket notation and use_path_style parameter setting, same for HTTP.
-- Since "use_path_style"="false" is set, Virtual-hosted Style will be used to access S3.
select * from s3(
"uri" = "https://bucket.endpoint/bucket/file/student.csv",
"s3.access_key"= "ak",
"s3.secret_key" = "sk",
"s3.endpoint" = "endpoint",
"s3.region" = "region",
"format" = "csv",
"use_path_style"="false");
-- Alibaba Cloud OSS and Tencent Cloud COS use Virtual-hosted Style to access S3.
-- OSS
select * from s3(
"uri" = "http://example-bucket.oss-cn-beijing.aliyuncs.com/your-folder/file.parquet",
"s3.access_key"= "ak",
"s3.secret_key" = "sk",
"s3.endpoint" = "oss-cn-beijing.aliyuncs.com",
"s3.region" = "oss-cn-beijing",
"format" = "parquet",
"use_path_style" = "false");
-- COS
select * from s3(
"uri" = "https://example-bucket.cos.ap-hongkong.myqcloud.com/your-folder/file.parquet",
"s3.access_key"= "ak",
"s3.secret_key" = "sk",
"s3.endpoint" = "cos.ap-hongkong.myqcloud.com",
"s3.region" = "ap-hongkong",
"format" = "parquet",
"use_path_style" = "false");
-- MinIO
select * from s3(
"uri" = "s3://bucket/file.csv",
"s3.endpoint" = "http://172.21.0.101:9000",
"s3.access_key"= "ak",
"s3.secret_key" = "sk",
"s3.region" = "us-east-1",
"format" = "csv"
);
-- Baidu Cloud BOS uses S3-compatible Virtual-hosted Style to access S3.
-- BOS
select * from s3(
"uri" = "https://example-bucket.s3.bj.bcebos.com/your-folder/file.parquet",
"s3.access_key"= "ak",
"s3.secret_key" = "sk",
"s3.region" = "bj",
"s3.endpoint" = "http://bj.bcebos.com",
"format" = "parquet",
"use_path_style" = "false"); -
Пример использования
s3://:-- Note URI Bucket notation, no need to set use_path_style parameter.
-- Virtual-hosted Style will be used to access S3.
select * from s3(
"uri" = "s3://bucket/file/student.csv",
"s3.endpoint"= "endpont",
"s3.region"= "region",
"s3.access_key"= "ak",
"s3.secret_key" = "sk",
"format" = "csv"); -
Примеры других поддерживаемых стилей URI:
-- Virtual Host AWS Client (Hadoop S3) Mixed Style. Use by setting use_path_style=false and force_parsing_by_standard_uri=true.
select * from s3(
"URI" = "s3://my-bucket.s3.us-west-1.amazonaws.com/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88",
"s3.access_key"= "ak",
"s3.secret_key" = "sk",
"s3.endpoint"= "endpont",
"s3.region"= "region",
"format" = "csv",
"use_path_style"="false",
"force_parsing_by_standard_uri"="true");
-- Path AWS Client (Hadoop S3) Mixed Style. Use by setting use_path_style=true and force_parsing_by_standard_uri=true.
select * from s3(
"URI" = "s3://s3.us-west-1.amazonaws.com/my-bucket/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88",
"s3.access_key"= "ak",
"s3.secret_key" = "sk",
"s3.endpoint"= "endpont",
"s3.region"= "region",
"format" = "csv",
"use_path_style"="true",
"force_parsing_by_standard_uri"="true"); -
Формат CSV
Поскольку табличная функция S3 заранее не знает схему таблицы, она читает файл один раз, чтобы определить эту схему.
Формат
csv: табличная функция S3 читает файлы из S3 и обрабатывает их как файлы CSV, определяя схему таблицы по первой строке. Количество столбцовnв первой строке используется как количество столбцов в схеме таблицы; столбцам автоматически присваиваются именаc1, c2, ..., cn, а для всех столбцов задаётся типString. Пример:Содержимое файла
student1.csv:1,ftw,12
2,zs,18
3,ww,20Использование S3 TVF:
select * from s3("uri" = "http://127.0.0.1:9312/test2/student1.csv",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "csv",
"use_path_style" = "true") order by c1;
+------+------+------+
| c1 | c2 | c3 |
+------+------+------+
| 1 | ftw | 12 |
| 2 | zs | 18 |
| 3 | ww | 20 |
+------+------+------+Для просмотра схемы таблицы можно использовать
desc function S3():Desc function s3("uri" = "http://127.0.0.1:9312/test2/student1.csv",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "csv",
"use_path_style" = "true");
+-------+------+------+-------+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------+------+------+-------+---------+-------+
| c1 | TEXT | Yes | false | NULL | NONE |
| c2 | TEXT | Yes | false | NULL | NONE |
| c3 | TEXT | Yes | false | NULL | NONE |
+-------+------+------+-------+---------+-------+ -
Формат
csv_with_namesФормат
csv_with_names: первая строка файла используется для определения количества и имён столбцов в схеме таблицы; для всех столбцов задаётся типString. Пример:Содержимое файла
student_with_names.csv:id,name,age
1,ftw,12
2,zs,18
3,ww,20Использование S3 TVF:
select * from s3("uri" = "http://127.0.0.1:9312/test2/student_with_names.csv",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "csv_with_names",
"use_path_style" = "true") order by id;
+------+------+------+
| id | name | age |
+------+------+------+
| 1 | ftw | 12 |
| 2 | zs | 18 |
| 3 | ww | 20 |
+------+------+------+ -
Аналогично, используйте
desc function S3()для просмотра схемы таблицыdesc function s3("uri" = "http://127.0.0.1:9312/test2/student_with_names.csv",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "csv_with_names",
"use_path_style" = "true");
+-------+------+------+-------+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------+------+------+-------+---------+-------+
| id | TEXT | Yes | false | NULL | NONE |
| name | TEXT | Yes | false | NULL | NONE |
| age | TEXT | Yes | false | NULL | NONE |
+-------+------+------+-------+---------+-------+ -
Формат
csv_with_names_and_typesФормат
csv_with_names_and_types: определение типов столбцов по файлам CSV в настоящее время не поддерживается. При использовании этого формата S3 TVF определяет количество и имена столбцов в схеме таблицы по первой строке, задаёт всем столбцам тип String и игнорирует вторую строку файла.Содержимое файла
student_with_names_and_types.csv:id,name,age
INT,STRING,INT
1,ftw,12
2,zs,18
3,ww,20Использование S3 TVF:
select * from s3("uri" = "http://127.0.0.1:9312/test2/student_with_names_and_types.csv",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "csv_with_names_and_types",
"use_path_style" = "true") order by id;
+------+------+------+
| id | name | age |
+------+------+------+
| 1 | ftw | 12 |
| 2 | zs | 18 |
| 3 | ww | 20 |
+------+------+------+Аналогично, используйте
desc function S3()для просмотра схемы таблицы:Desc function s3("uri" = "http://127.0.0.1:9312/test2/student_with_names_and_types.csv",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "csv_with_names_and_types",
"use_path_style" = "true");
+-------+------+------+-------+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------+------+------+-------+---------+-------+
| id | TEXT | Yes | false | NULL | NONE |
| name | TEXT | Yes | false | NULL | NONE |
| age | TEXT | Yes | false | NULL | NONE |
+-------+------+------+-------+---------+-------+ -
Формат JSON
Формат
json: для формата JSON предусмотрено множество необязательных параметров. О назначении каждого параметра см. в разделе Загрузка JSON. При запросе файлов формата JSON с помощью S3 TVF функция находит объект JSON на основе параметровjson_rootиjsonpaths, используетkeyобъекта как имена столбцов в схеме таблицы и задаёт всем столбцам тип String. Пример:Содержимое файла
data.json:[{"id":1, "name":"ftw", "age":18}]
[{"id":2, "name":"xxx", "age":17}]
[{"id":3, "name":"yyy", "age":19}]Выполнение запроса с помощью S3 TVF:
select * from s3(
"uri" = "http://127.0.0.1:9312/test2/data.json",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "json",
"strip_outer_array" = "true",
"read_json_by_line" = "true",
"use_path_style"="true");
+------+------+------+
| id | name | age |
+------+------+------+
| 1 | ftw | 18 |
| 2 | xxx | 17 |
| 3 | yyy | 19 |
+------+------+------+
select * from s3(
"uri" = "http://127.0.0.1:9312/test2/data.json",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "json",
"strip_outer_array" = "true",
"jsonpaths" = "[\"$.id\", \"$.age\"]",
"use_path_style"="true");
+------+------+
| id | age |
+------+------+
| 1 | 18 |
| 2 | 17 |
| 3 | 19 |
+------+------+ -
Формат Parquet
Формат
parquet: S3 TVF поддерживает извлечение имён и типов столбцов из файлов Parquet для определения схемы таблицы. Пример:select * from s3(
"uri" = "http://127.0.0.1:9312/test2/test.snappy.parquet",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "parquet",
"use_path_style"="true") limit 5;
+-----------+------------------------------------------+----------------+----------+-------------------------+--------+-------------+---------------+---------------------+
| p_partkey | p_name | p_mfgr | p_brand | p_type | p_size | p_container | p_retailprice | p_comment |
+-----------+------------------------------------------+----------------+----------+-------------------------+--------+-------------+---------------+---------------------+
| 1 | goldenrod lavender spring chocolate lace | Manufacturer#1 | Brand#13 | PROMO BURNISHED COPPER | 7 | JUMBO PKG | 901 | ly. slyly ironi |
| 2 | blush thistle blue yellow saddle | Manufacturer#1 | Brand#13 | LARGE BRUSHED BRASS | 1 | LG CASE | 902 | lar accounts amo |
| 3 | spring green yellow purple cornsilk | Manufacturer#4 | Brand#42 | STANDARD POLISHED BRASS | 21 | WRAP CASE | 903 | egular deposits hag |
| 4 | cornflower chocolate smoke green pink | Manufacturer#3 | Brand#34 | SMALL PLATED BRASS | 14 | MED DRUM | 904 | p furiously r |
| 5 | forest brown coral puff cream | Manufacturer#3 | Brand#32 | STANDARD POLISHED TIN | 15 | SM PKG | 905 | wake carefully |
+-----------+------------------------------------------+----------------+----------+-------------------------+--------+-------------+---------------+---------------------+MySQL [(none)]> desc function s3(
"uri" = "http://127.0.0.1:9312/test2/test.snappy.parquet",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "parquet",
"use_path_style"="true");
+---------------+--------------+------+-------+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+---------------+--------------+------+-------+---------+-------+
| p_partkey | INT | Yes | false | NULL | NONE |
| p_name | TEXT | Yes | false | NULL | NONE |
| p_mfgr | TEXT | Yes | false | NULL | NONE |
| p_brand | TEXT | Yes | false | NULL | NONE |
| p_type | TEXT | Yes | false | NULL | NONE |
| p_size | INT | Yes | false | NULL | NONE |
| p_container | TEXT | Yes | false | NULL | NONE |
| p_retailprice | DECIMAL(9,0) | Yes | false | NULL | NONE |
| p_comment | TEXT | Yes | false | NULL | NONE |
+---------------+--------------+------+-------+---------+-------+ -
Формат ORC
Формат
orc: используется так же, как форматparquet; достаточно задать параметруformatзначениеorc.select * from s3(
"uri" = "http://127.0.0.1:9312/test2/test.snappy.orc",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "orc",
"use_path_style"="true") limit 5;
+-----------+------------------------------------------+----------------+----------+-------------------------+--------+-------------+---------------+---------------------+
| p_partkey | p_name | p_mfgr | p_brand | p_type | p_size | p_container | p_retailprice | p_comment |
+-----------+------------------------------------------+----------------+----------+-------------------------+--------+-------------+---------------+---------------------+
| 1 | goldenrod lavender spring chocolate lace | Manufacturer#1 | Brand#13 | PROMO BURNISHED COPPER | 7 | JUMBO PKG | 901 | ly. slyly ironi |
| 2 | blush thistle blue yellow saddle | Manufacturer#1 | Brand#13 | LARGE BRUSHED BRASS | 1 | LG CASE | 902 | lar accounts amo |
| 3 | spring green yellow purple cornsilk | Manufacturer#4 | Brand#42 | STANDARD POLISHED BRASS | 21 | WRAP CASE | 903 | egular deposits hag |
| 4 | cornflower chocolate smoke green pink | Manufacturer#3 | Brand#34 | SMALL PLATED BRASS | 14 | MED DRUM | 904 | p furiously r |
| 5 | forest brown coral puff cream | Manufacturer#3 | Brand#32 | STANDARD POLISHED TIN | 15 | SM PKG | 905 | wake carefully |
+-----------+------------------------------------------+----------------+----------+-------------------------+--------+-------------+---------------+---------------------+ -
URI с подстановочными знаками
URI может содержать подстановочные знаки и шаблоны диапазонов для чтения нескольких файлов. Подробный синтаксис, включая
*,?,[...]и раскрытие диапазонов{1..10}, описан в разделе Шаблон пути к файлу. Примечание: при использовании подстановочных знаков убедитесь, что все файлы имеют одинаковый формат (в частности,csv,csv_with_names,csv_with_names_and_typesсчитаются разными форматами). S3 TVF использует первый файл для определения схемы таблицы.Для следующих двух файлов CSV:
// file1.csv
1,aaa,18
2,qqq,20
3,qwe,19
// file2.csv
5,cyx,19
6,ftw,21Можно выполнить запрос с подстановочными знаками в URI:
select * from s3(
"uri" = "http://127.0.0.1:9312/test2/file*.csv",
"s3.access_key"= "minioadmin",
"s3.secret_key" = "minioadmin",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "csv",
"use_path_style"="true");
+------+------+------+
| c1 | c2 | c3 |
+------+------+------+
| 1 | aaa | 18 |
| 2 | qqq | 20 |
| 3 | qwe | 19 |
| 5 | cyx | 19 |
| 6 | ftw | 21 |
+------+------+------+ -
Использование S3 TVF с
insert intoиcast-- Create Doris internal table
CREATE TABLE IF NOT EXISTS ${testTable}
(
id int,
name varchar(50),
age int
)
COMMENT "my first table"
DISTRIBUTED BY HASH(id) BUCKETS 32
PROPERTIES("replication_num" = "1");
-- Insert data using S3
insert into ${testTable} (id,name,age)
select cast (id as INT) as id, name, cast (age as INT) as age
from s3(
"uri" = "${uri}",
"s3.access_key"= "${ak}",
"s3.secret_key" = "${sk}",
"s3.endpoint" = "http://127.0.0.1:9312",
"s3.region" = "us-east-1",
"format" = "${format}",
"strip_outer_array" = "true",
"read_json_by_line" = "true",
"use_path_style" = "true");