ja-source/docusaurus-plugin-content-docs/current/sql-manual/basic-element/file-path-pattern.md

{ “title”: “ファイルパスパターン”, “language”: “ja”, “description”: “DorisがS3、HDFS、その他のオブジェクトストレージなどのリモートストレージシステム内のファイルにアクセスする際にサポートするファイルパスパターンとワイルドカード。” }

概要

リモートストレージシステム（S3、HDFS、およびその他のS3互換オブジェクトストレージ）からファイルにアクセスする際、Dorisはワイルドカードや範囲表現を含む柔軟なファイルパスパターンをサポートします。このドキュメントでは、サポートされるパス形式とパターンマッチング構文について説明します。

これらのパスパターンは以下でサポートされています：

S3 TVF
HDFS TVF
Broker Load
INSERT INTO SELECT from TVF

サポートされるURI形式

S3形式のURI

形式	フォーマット	例
AWS Client Style (Hadoop S3)	`s3://bucket/path/to/file`	`s3://my-bucket/data/file.csv`
S3A Style	`s3a://bucket/path/to/file`	`s3a://my-bucket/data/file.csv`
S3N Style	`s3n://bucket/path/to/file`	`s3n://my-bucket/data/file.csv`
Virtual Host Style	`https://bucket.endpoint/path/to/file`	`https://my-bucket.s3.us-west-1.amazonaws.com/data/file.csv`
Path Style	`https://endpoint/bucket/path/to/file`	`https://s3.us-west-1.amazonaws.com/my-bucket/data/file.csv`

その他のクラウドストレージURI

プロバイダー	スキーム	例
Alibaba Cloud OSS	`oss://`	`oss://my-bucket/data/file.csv`
Tencent Cloud COS	`cos://`, `cosn://`	`cos://my-bucket/data/file.csv`
Baidu Cloud BOS	`bos://`	`bos://my-bucket/data/file.csv`
Huawei Cloud OBS	`obs://`	`obs://my-bucket/data/file.csv`
Google Cloud Storage	`gs://`	`gs://my-bucket/data/file.csv`
Azure Blob Storage	`azure://`	`azure://container/data/file.csv`

HDFS URI

形式	フォーマット	例
標準	`hdfs://namenode:port/path/to/file`	`hdfs://namenode:8020/user/data/file.csv`
HAモード	`hdfs://nameservice/path/to/file`	`hdfs://my-ha-cluster/user/data/file.csv`

ワイルドカードパターン

Dorisはファイルパスにglob形式のパターンマッチングを使用します。以下のワイルドカードがサポートされています：

基本ワイルドカード

パターン	説明	例	マッチするもの
`*`	パスセグメント内の0文字以上の文字にマッチ	`*.csv`	`file.csv`、`data.csv`、`a.csv`
`?`	正確に1文字にマッチ	`file?.csv`	`file1.csv`、`fileA.csv`だが`file10.csv`はマッチしない
`[abc]`	ブラケット内の任意の1文字にマッチ	`file[123].csv`	`file1.csv`、`file2.csv`、`file3.csv`
`[a-z]`	範囲内の任意の1文字にマッチ	`file[a-c].csv`	`filea.csv`、`fileb.csv`、`filec.csv`
`[!abc]`	ブラケット内にない任意の1文字にマッチ	`file[!0-9].csv`	`filea.csv`、`fileb.csv`だが`file1.csv`はマッチしない

範囲展開（ブレースパターン）

Dorisはブレースパターン{start..end}を使用した数値範囲展開をサポートします：

パターン	展開	マッチするもの
`{1..3}`	`{1,2,3}`	`1`、`2`、`3`
`{01..05}`	`{1,2,3,4,5}`	`1`、`2`、`3`、`4`、`5`（先頭のゼロは保持されない）
`{3..1}`	`{1,2,3}`	`1`、`2`、`3`（逆順範囲がサポートされる）
`{a,b,c}`	`{a,b,c}`	`a`、`b`、`c`（列挙）
`{1..3,5,7..9}`	`{1,2,3,5,7,8,9}`	範囲と値の混在

:::caution 注意

Dorisは可能な限り多くのファイルをマッチしようとします。ブレース表現内の無効な部分は静かにスキップされ、有効な部分は引き続き展開されます。例えば、file_{a..b,-1..3,4..5}はfile_4とfile_5にマッチします（無効なa..bと負の範囲-1..3はスキップされますが、4..5は正常に展開されます）。
全体の範囲が負の場合（例：{-1..2}）、その範囲はスキップされます。有効な範囲と混在している場合（例：{-1..2,1..3}）、有効な範囲1..3のみが展開されます。
範囲でカンマ区切りの値を使用する場合、数値のみが許可されます。例えば、{1..4,a}では、非数値のaは無視され、結果として{1,2,3,4}になります。
{a,b,c}のような純粋な列挙パターン（..範囲を含まない）は直接glob マッチングに渡され、期待通りに動作します。 :::

パターンの組み合わせ

複数のパターンを1つのパスに組み合わせることができます：

s3://bucket/data_{1..3}/file_*.csv

これは以下にマッチします：

s3://bucket/data_1/file_a.csv
s3://bucket/data_1/file_b.csv
s3://bucket/data_2/file_a.csv
... など

例

S3 TVF の例

ディレクトリ内のすべてのCSVファイルにマッチ：

SELECT * FROM S3(
    "uri" = "s3://my-bucket/data/*.csv",
    "s3.access_key" = "xxx",
    "s3.secret_key" = "xxx",
    "s3.region" = "us-east-1",
    "format" = "csv"
);

数値範囲でファイルをマッチ:

SELECT * FROM S3(
    "uri" = "s3://my-bucket/logs/data_{1..10}.csv",
    "s3.access_key" = "xxx",
    "s3.secret_key" = "xxx",
    "s3.region" = "us-east-1",
    "format" = "csv"
);

日付でパーティション分けされたディレクトリ内のファイルをマッチ:

SELECT * FROM S3(
    "uri" = "s3://my-bucket/logs/year=2024/month=*/day=*/data.parquet",
    "s3.access_key" = "xxx",
    "s3.secret_key" = "xxx",
    "s3.region" = "us-east-1",
    "format" = "parquet"
);

:::caution ゼロパディングされたディレクトリ month=01、month=02のようなゼロパディングされたディレクトリ名の場合は、範囲パターンではなくワイルドカード（*）を使用してください。パターン{01..12}は{1,2,...,12}に展開されるため、month=01にマッチしません。 :::

番号付きファイル分割にマッチさせる（例：Spark出力）：

SELECT * FROM S3(
    "uri" = "s3://my-bucket/output/part-{00000..00099}.csv",
    "s3.access_key" = "xxx",
    "s3.secret_key" = "xxx",
    "s3.region" = "us-east-1",
    "format" = "csv"
);

Broker Load Examples

パターンにマッチするすべてのCSVファイルを読み込む:

LOAD LABEL db.label_wildcard
(
    DATA INFILE("s3://my-bucket/data/file_*.csv")
    INTO TABLE my_table
    COLUMNS TERMINATED BY ","
    FORMAT AS "CSV"
    (col1, col2, col3)
)
WITH S3 (
    "provider" = "S3",
    "AWS_ENDPOINT" = "s3.us-west-2.amazonaws.com",
    "AWS_ACCESS_KEY" = "xxx",
    "AWS_SECRET_KEY" = "xxx",
    "AWS_REGION" = "us-west-2"
);

数値範囲展開を使用してファイルを読み込む:

LOAD LABEL db.label_range
(
    DATA INFILE("s3://my-bucket/exports/data_{1..5}.csv")
    INTO TABLE my_table
    COLUMNS TERMINATED BY ","
    FORMAT AS "CSV"
    (col1, col2, col3)
)
WITH S3 (
    "provider" = "S3",
    "AWS_ENDPOINT" = "s3.us-west-2.amazonaws.com",
    "AWS_ACCESS_KEY" = "xxx",
    "AWS_SECRET_KEY" = "xxx",
    "AWS_REGION" = "us-west-2"
);

ワイルドカードを使用してHDFSから読み込み:

LOAD LABEL db.label_hdfs_wildcard
(
    DATA INFILE("hdfs://namenode:8020/user/data/2024-*/*.csv")
    INTO TABLE my_table
    COLUMNS TERMINATED BY ","
    FORMAT AS "CSV"
    (col1, col2, col3)
)
WITH HDFS (
    "fs.defaultFS" = "hdfs://namenode:8020",
    "hadoop.username" = "user"
);

数値範囲でHDFSから読み込み:

LOAD LABEL db.label_hdfs_range
(
    DATA INFILE("hdfs://namenode:8020/data/file_{1..3,5,7..9}.csv")
    INTO TABLE my_table
    COLUMNS TERMINATED BY ","
    FORMAT AS "CSV"
    (col1, col2, col3)
)
WITH HDFS (
    "fs.defaultFS" = "hdfs://namenode:8020",
    "hadoop.username" = "user"
);

INSERT INTO SELECT の例

ワイルドカードを使用したS3からの挿入:

INSERT INTO my_table (col1, col2, col3)
SELECT * FROM S3(
    "uri" = "s3://my-bucket/data/part-*.parquet",
    "s3.access_key" = "xxx",
    "s3.secret_key" = "xxx",
    "s3.region" = "us-east-1",
    "format" = "parquet"
);

パフォーマンスに関する考慮事項

具体的なプレフィックスを使用する

Dorisは、S3/HDFSリスト操作を最適化するために、パスパターンから最長の非ワイルドカードプレフィックスを抽出します。より具体的なプレフィックスを使用することで、ファイル検出が高速化されます。

-- Good: specific prefix reduces listing scope
"uri" = "s3://bucket/data/2024/01/15/*.csv"

-- Less optimal: broad wildcard at early path segment
"uri" = "s3://bucket/data/**/file.csv"

既知のシーケンスにはレンジパターンを優先する

正確なファイル番号がわかっている場合は、ワイルドカードの代わりにレンジパターンを使用してください：

-- Better: explicit range
"uri" = "s3://bucket/data/part-{0001..0100}.csv"

-- Less optimal: wildcard matches unknown files
"uri" = "s3://bucket/data/part-*.csv"

深い再帰的ワイルドカードを避ける

** のような深い再帰的パターンは、大きなバケットでファイルリストの処理が遅くなる原因となります：

-- Avoid when possible
"uri" = "s3://bucket/**/*.csv"

-- Prefer explicit path structure
"uri" = "s3://bucket/data/year=*/month=*/day=*/*.csv"

トラブルシューティング

問題	原因	解決策
ファイルが見つからない	パターンがどのファイルにもマッチしない	パスとパターンの構文を確認し、まず単一ファイルでテストする
ファイル一覧の処理が遅い	ワイルドカードが広範囲すぎる、またはファイルが多すぎる	より具体的なプレフィックスを使用し、ワイルドカードのスコープを制限する
無効なURI error	パス構文の形式が正しくない	URIスキームとbucket名の形式を確認する
Access denied	認証情報または権限の問題	S3/HDFS認証情報とbucketポリシーを確認する

パスパターンのテスト

大規模なロードジョブを実行する前に、制限されたクエリでパターンをテストしてください：

-- Test if files exist and match pattern
SELECT * FROM S3(
    "uri" = "s3://bucket/your/pattern/*.csv",
    ...
) LIMIT 1;

マッチしたファイルのスキーマを検証するには DESC FUNCTION を使用します:

DESC FUNCTION S3(
    "uri" = "s3://bucket/your/pattern/*.csv",
    ...
);