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 | S3 にアクセスするための URI。ワイルドカードと範囲パターンをサポートします。詳細はファイルパスパターンを参照してください。use_path_style パラメータに応じて、Path Style または Virtual-hosted 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 を標準の 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 | CSV ファイルの先頭から N 行をスキップします。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 | 開発版では互換性のために受け付けますが、値は無視されます。外部のバイナリデータは常に VARBINARY にマッピングされます。Doris 4.1.5 では、この TVF オプションを引き続き設定でき、デフォルト値は false です。 | 4.0.3 以降でサポート |
enable_mapping_timestamp_tz | true | 4.1.5 以降、互換性のために受け付けますが、値は無視されます。isAdjustedToUTC=true の Parquet Timestamp と ORC の TIMESTAMP_INSTANT は、このオプションが false でも常に TIMESTAMPTZ にマッピングされます。 | 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 Client Style(Hadoop S3 Style)
s3://my-bucket/path/to/file?versionId=abc123&partNumber=77&partNumber=88 -
Virtual Host Style
https://my-bucket.s3.us-west-1.amazonaws.com/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88 -
Path Style
https://s3.us-west-1.amazonaws.com/my-bucket/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88
これら 3 つの標準的な URI 形式のほかに、あまり一般的ではありませんが、以下の URI 形式もサポートしています。
-
Virtual Host AWS Client(Hadoop S3)混合形式
s3://my-bucket.s3.us-west-1.amazonaws.com/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88 -
Path AWS Client(Hadoop S3)混合形式
s3://s3.us-west-1.amazonaws.com/my-bucket/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88
詳しい使用例は、以下の例を参照してください。
-
-
TVF を直接クエリする場合や、この TVF を基に View を作成する場合は、Resource に対する USAGE 権限が必要です。TVF を基に作成した View をクエリする場合は、その View に対する SELECT 権限のみが必要です。
例
-
S3 互換のオブジェクトストレージ上の CSV 形式のファイルを読み取る
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 functionと組み合わせて使用する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"); -
さまざまな 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,20S3 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,20S3 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 に設定します。ファイルの 2 行目は無視します。student_with_names_and_types.csvファイルの内容:id,name,age
INT,STRING,INT
1,ftw,12
2,zs,18
3,ww,20S3 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 データロードを参照してください。S3 TVF で JSON 形式のファイルをクエリする場合、json_rootとjsonpathsパラメータに基づいて JSON オブジェクトを特定します。オブジェクト内の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 は最初のファイルを使ってテーブルスキーマを解析します。次の 2 つの CSV ファイルがある場合:
// file1.csv
1,aaa,18
2,qqq,20
3,qwe,19
// file2.csv
5,cyx,19
6,ftw,21URI にワイルドカードを指定してクエリできます:
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");