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 | false | PARQUET/ORC の読み取り時に BYTE_ARRAY 型を STRING にマッピングします。有効にすると、代わりに VARBINARY 型にマッピングします。 | バージョン 4.0.3 からサポート |
enable_mapping_timestamp_tz | true | バージョン 4.1.5 以降は互換性のためにのみ受け付けられ、値は無視されます。Parquet Timestamp の isAdjustedToUTC=true と ORC の TIMESTAMP_INSTANT は、このオプションが false でも常に TIMESTAMPTZ にマッピングされます。独立したオプションである enable_mapping_varbinary は引き続き設定可能で、デフォルトは 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 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
これらの標準的な URI スタイルに加えて、次のような、あまり一般的ではない URI スタイルもサポートしています。
-
Virtual Host AWS Client (Hadoop S3) Mixed Style
s3://my-bucket.s3.us-west-1.amazonaws.com/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88 -
Path AWS Client (Hadoop S3) Mixed Style
s3://s3.us-west-1.amazonaws.com/my-bucket/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88
詳しい使用方法は、以下の例を参照してください。
-
-
TVF を直接クエリする場合、またはこの TVF に基づいてビューを作成する場合は、Resource に対する USAGE 権限が必要です。TVF に基づいて作成されたビューをクエリする場合は、そのビューに対する 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 は最初のファイルを使用してテーブルスキーマを解析します。次の 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");