メインコンテンツまでスキップ
バージョン: 4.x

S3

デスクリプション​

S3 table-valued function (TVF) を使用すると、ユーザーはS3互換オブジェクトストレージに保存されているファイルを、リレーショナルTable形式のデータにアクセスするように読み取りおよびアクセスできます。現在、csv/csv_with_names/csv_with_names_and_types/json/parquet/orc ファイル形式をサポートしています。

Syntax​

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>" [, ...] ]
  )

必須パラメータ​

パラメータ説明
uriS3にアクセスするためのURI。この関数はuse_path_styleパラメータに基づいてPath StyleまたはVirtual-hosted Styleを使用します
s3.access_keyS3のアクセスキー
s3.secret_keyS3のシークレットキー
s3.regionS3リージョン
s3.endpointS3エンドポイントアドレス
formatファイル形式。csv/csv_with_names/csv_with_names_and_types/json/parquet/orcをサポート

オプションパラメータ​

パラメータデフォルト説明備考
s3.session_token-S3セッショントークン
use_path_stylefalseS3 SDKはデフォルトでVirtual-hosted Styleを使用します。一部のオブジェクトストレージシステムはVirtual-hosted Styleをサポートしていない場合があります。このパラメータを設定してPath Styleアクセスを強制します。例えば、MinIOはデフォルトでPath Styleのみを許可するため、MinIOにアクセスする際はuse_path_style=trueを設定する必要があります
force_parsing_by_standard_urifalse非標準URIを標準URIとして強制的にパースします
column_separator\tカラム区切り文字
line_delimiter\n行区切り文字
compress_typeUNKNOWN圧縮タイプ。現在UNKNOWN/PLAIN/GZ/LZO/BZ2/LZ4FRAME/DEFLATE/SNAPPYBLOCKをサポート。uriのサフィックスに基づいて自動検出します
read_json_by_line"true"JSON形式のインポート用JSON Load
strip_outer_array"false"JSON形式のインポート用JSON Load
json_rootEmptyJSON形式のインポート用JSON Load
jsonpathsEmptyJSON形式のインポート用JSON Load
num_as_stringfalseJSON形式のインポート用JSON Load
fuzzy_parsefalseJSON形式のインポート用
trim_double_quotesfalseCSV形式のインポート用。各フィールドから最外側のダブルクォートを削除します
skip_lines0CSVファイルの最初の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_varbinaryfalsePARQUET/ORCを読み取る際にBYTE_ARRAY型をSTRINGにマップします。有効にすると、代わりにVARBINARY型にマップします。バージョン4.0.3からサポート

注意事項​

  1. AWS S3の場合、標準URI形式には以下が含まれます：

    • AWS クライアント 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
    ```

  • パススタイル

    ```
    https://s3.us-west-1.amazonaws.com/my-bucket/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88
    ```

これら3つの標準的なURIスタイルに加えて、他のURIスタイルもサポートされています（ただし、あまり一般的ではありません）：

  • Virtual Host AWS クライアント (Hadoop S3) Mixed Style

    s3://my-bucket.s3.us-west-1.amazonaws.com/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88

  • Path AWS クライアント (Hadoop S3) Mixed Style

    ```
    s3://s3.us-west-1.amazonaws.com/my-bucket/resources/doc.txt?versionId=abc123&partNumber=77&partNumber=88
    ```

詳細な使用例については、以下の例を参照してください。

  1. TVFを直接クエリする場合やこのTVFに基づいてViewを作成する場合は、Resourceに対するUSAGE権限が必要です。TVFに基づいて作成されたViewをクエリする場合は、Viewに対するSELECT権限のみが必要です。

Examples​

  • 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 バケット 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 バケット 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 バケット 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 クライアント (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 クライアント (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 Format

    S3 table-valued-function は事前にTable Schemaを知らないため、Table Schemaを解析するためにファイルを一度読み取ります。

    csv format: S3 table-valued-function はS3上のファイルを読み取り、CSVファイルとして処理し、最初の行を使用してTable Schemaを解析します。最初の行の列数 n がTable Schemaの列数として使用され、列名は自動的に c1, c2, ..., cn と命名され、すべての列タイプは String に設定されます。例:

    student1.csv ファイルの内容:

    1,ftw,12
    2,zs,18
    3,ww,20

S3 TVFの使用:

```sql
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() を使用してTableスキーマを表示できます：

```sql
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 | タイプ | 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 フォーマット：ファイルの最初の行をTable Schemaの列数と列名として解析し、すべての列の型を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() を使用してTable Schemaを表示します

    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 | タイプ | 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は最初の行をTable Schema内の列の数と名前として解析し、すべての列の型をStringに設定し、ファイルの2行目は無視します。

    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() を使用してTable Schemaを表示します：

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 | タイプ | Null | Key   | Default | Extra |
  +-------+------+------+-------+---------+-------+
  | id    | TEXT | Yes  | false | NULL    | NONE  |
  | name  | TEXT | Yes  | false | NULL    | NONE  |
  | age   | TEXT | Yes  | false | NULL    | NONE  |
  +-------+------+------+-------+---------+-------+

  • JSON Format

    jsonフォーマット: JSONフォーマットには多くのオプションパラメータが含まれます。各パラメータの意味については、Json Loadを参照してください。S3 TVFでJSONフォーマットファイルをクエリする際、json_rootとjsonpathsパラメータに基づいてJSONオブジェクトを特定し、オブジェクト内のkeyをTable Schemaの列名として使用し、すべての列タイプは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 Format

    parquet フォーマット: S3 TVF は Table Schema に対して 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         | タイプ         | 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 Format

    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はワイルドカードを使用して複数のファイルを読み取ることができます。注意：ワイルドカードを使用する際は、すべてのファイルが同じフォーマットであることを確認してください（特にcsv、csv_with_names、csv_with_names_and_typesは異なるフォーマットです）。S3 TVFは最初のファイルを使用してTable Schemaを解析します。

    以下の2つの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");