url

url 関数は、指定された フォーマット と structure を使用して URL からテーブルを作成します。

url 関数は、URL テーブルのデータに対する SELECT クエリおよび INSERT クエリで使用できます。

構文

url(URL [,format] [,structure] [,headers])

パラメーター

Parameter	Description
`URL`	スキームによってバックエンドが選択される、単一引用符で囲んだ URL です。`http`/`https` (または未認識の) URL は `GET` または `POST` リクエストを受け付けるサーバーアドレスです (それぞれ `SELECT` クエリ、`INSERT` クエリに対応) 。認識される非 HTTP スキーム (`file://`、`s3://`、`az://`、`hdfs://`、…) は、対応するテーブル関数に委譲されます。詳しくは URL スキームによる振り分けを参照してください。型: String。
`format`	データのフォーマットです。型: String。
`structure`	`'UserID UInt64, Name String'` フォーマットで指定するテーブル構造です。カラム名と型を決定します。型: String。
`headers`	`'headers('key1'='value1', 'key2'='value2')'` フォーマットのヘッダーです。HTTP 呼び出し用のヘッダーを設定できます。

戻り値

指定されたフォーマットと構造を持ち、指定したURLのデータを含むテーブル。

例

CSV フォーマットで応答する HTTP サーバーから、String 型と UInt32 型のカラムを含むテーブルの先頭 3 行を取得します。

SELECT * FROM url('http://127.0.0.1:12345/', CSV, 'column1 String, column2 UInt32', headers('Accept'='text/csv; charset=utf-8')) LIMIT 3;

URL からテーブルへデータを挿入するには:

CREATE TABLE test_table (column1 String, column2 UInt32) ENGINE=Memory;
INSERT INTO FUNCTION url('http://127.0.0.1:8123/?query=INSERT+INTO+test_table+FORMAT+CSV', 'CSV', 'column1 String, column2 UInt32') VALUES ('http interface', 42);
SELECT * FROM test_table;

URL スキームによる振り分け

url 関数は、他のファイルストレージおよびオブジェクトストレージのテーブル関数を統一的に扱うラッパーとして機能します。URL スキームに基づいて適切なバックエンドに振り分けられるため、サポートされている任意の場所から単一の統一された構文で読み取ることができます。

Scheme	振り分け先
`http`, `https` (および認識されない任意のスキーム)	`URL` エンジン自体 (HTTP `GET`/`POST`)
`file`	`file` 関数
`s3`, `gs`, `gcs`, `oss`	`s3` 関数
`az`, `azure`, `abfss`, `abfs`	`azureBlobStorage` 関数
`hdfs`	`hdfs` 関数

追加設定なしで S3 URI mapper が具体的なエンドポイントに解決できる S3 スキーム (s3 と gs/gcs/oss) のみが振り分けの対象です。その他の S3-compatible ベンダーのスキーム (cos、obs、eos、…) はリージョン固有で、デフォルトのエンドポイントマッピングがありません。そのため、cos://… URL は認識されないスキームとして扱われ、エラーとして報告されます。これらのバックエンドでは、s3 関数を直接使用してください (url_scheme_mappers を設定したうえで) 。

file:// の場合、相対パス (file://data.csv) は user_files ディレクトリ内で解決され、絶対パス (file:///home/user/data.csv) は通常どおりその配下を指している必要があります。

フォーマット、構造、compression_method の引数と url_base 設定は、振り分け先にかかわらず同じように機能します。

SELECT * FROM url('file://data.csv', CSV, 'a UInt32, b String');
SELECT * FROM url('s3://clickhouse-public-datasets/hits_compatible/hits.csv');

スキームの振り分けは、urlCluster ではまだサポートされていません。urlCluster に http(s) 以外のスキームを渡すと、エラーになって拒否されます。そうしたバックエンドでは、代わりに対応するクラスター関数 (s3Cluster、azureBlobStorageCluster、hdfsCluster、…) を使用してください。

URL 内の globs

{ } 内のパターンは、分片のセットを生成したり、フェイルオーバー先のアドレスを指定したりするために使用されます。サポートされているパターンの種類と例については、remote 関数の説明を参照してください。パターン内の文字 | は、フェイルオーバー先のアドレスを指定するために使用されます。これらは、パターンに記載された順序どおりに順番に試行されます。生成されるアドレス数は、glob_expansion_max_elements 設定によって制限されます。 URL パスでの glob 構文 (*、{a,b}、{N..M}、** など) については、パス内の globs を参照してください。なお、? は URL ではクエリ文字列の開始を表すため、パス部分ではワイルドカードとして使用できません。

HTTPインデックスページでのワイルドカード

url および URL テーブルエンジンでは、ClickHouse は HTTP インデックスページ (HTML または平文) を取得し、レスポンスボディから URL を抽出することでワイルドカードを展開できます。これにより、サーバーがディレクトリ一覧を公開している場合は、/**/ のようなパターンを使用できます。

注意:

相対 URL は、インデックスページの URL を基準に解決されます。
URL テンプレートは、インデックスページを取得する前に展開されます。これには、カンマ区切りおよび数値範囲の分片展開と、パス部分の外側にある | フェイルオーバーオプションが含まれます。
パス部分の内側にある | フェイルオーバーパターンは、HTTP インデックスページ展開ではサポートされていません。
ワイルドカードの照合は、URL のパス部分に適用されます。
一覧に含まれる URL にすでにクエリ文字列またはフラグメントが含まれている場合は、ソース URL のものよりそちらが優先されます。含まれていない場合は、ソース URL のクエリ文字列とフラグメントが使用されます。
空の一覧も許可されます。インデックスページに対する HTTP エラー (例: 404) は例外を発生させます。
インデックスページの最大サイズは、max_http_index_page_size によって制限されます。
再帰的な展開中に読み取るディレクトリの最大数は、url_wildcard_max_directories_to_read によって制限されます。

例:

SELECT count()
FROM url('https://ftp.gnu.org/gnu/wget/wget-1.21*.tar.gz', 'RawBLOB')
SETTINGS max_threads = 1, allow_experimental_url_wildcard_from_index_pages = 1;

仮想カラム

_path — URL のパス。型: LowCardinality(String)。
_file — URL のリソース名。型: LowCardinality(String)。
_size — リソースのサイズ (バイト単位) 。型: Nullable(UInt64)。サイズが不明な場合、値は NULL です。
_time — ファイルの最終更新時刻。型: Nullable(DateTime)。時刻が不明な場合、値は NULL です。
_headers - HTTP レスポンスヘッダー。型: Map(LowCardinality(String), LowCardinality(String))。

`use_hive_partitioning` 設定

use_hive_partitioning 設定を 1 にすると、ClickHouse はパス (/name=value/) 内の Hive スタイルのパーティション化を検出し、クエリ内でパーティションカラムを仮想カラムとして使用できるようになります。これらの仮想カラムには、パーティション化されたパス内と同じ名前が付きます。

例

Hive スタイルのパーティション化で作成された仮想カラムを使用する

SELECT * FROM url('http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

相対 URL の解決

url_base 設定を使用すると、url 関数に相対 URL を渡せます。url_base が設定されていて、関数の引数が相対参照である場合、その参照は RFC 3986 に従ってベース URL を基準に解決されます。

解決規則は次のとおりです。

パス相対 (例: data.csv) : ベース URL のパスにマージされ、ベースパスの最後の / 以降はすべて置き換えられます。末尾のスラッシュの有無は重要です。https://example.com/dir/ + data.csv は https://example.com/dir/data.csv になりますが、https://example.com/dir + data.csv は https://example.com/data.csv になります。ドットセグメント (./ と ../) は正規化されます。
ホスト相対 (例: /test/data.csv) : ベース URL のスキームとホストを使用して解決されます。
スキーム相対 (例: //other.com/test/data.csv) : ベース URL のスキームを使用して解決されます。
クエリのみ (例: ?x=1) : 完全なベースパスに付加され、既存のクエリやフラグメントは置き換えられます。
フラグメントのみ (例: #frag) : ベース URL に付加され、クエリは保持されたまま、既存のフラグメントは置き換えられます。
空: フラグメントを除いたベース URL を返します。
絶対 URL: 変更せずそのまま渡されます。url_base は無視されます。URL が絶対 URL と見なされるのは、scheme:// で始まる場合のみです。最初のパスセグメントにコロンを含む名前 (例: report:2026.csv) は、RFC 3986 ではスキーム report を持つ絶対 URI として解析されますが、そのような名前は使用可能な URL ではないため、代わりにパス相対参照として解決されます。
スキームのみのベース (例: file://) : パス相対 URL はベースに直接付加されます。file:// + data.csv = file://data.csv となり、file:// スキームではこれは user_files ディレクトリ (clickhouse-local では現在のディレクトリ) を基準とするパスを意味します。この場合、ドットセグメントはそのまま保持されます。

例

SET url_base = 'https://raw.githubusercontent.com/ClickHouse/ClickHouse/master/';
SELECT * FROM url('tests/queries/0_stateless/data_csv/data.csv', CSV) LIMIT 3;

ストレージ設定

engine_url_skip_empty_files - 読み取り時に空のファイルをスキップできます。デフォルトでは無効です。
enable_url_encoding - URI 内のパスのデコード/エンコードを有効または無効にできます。デフォルトでは有効です。
url_base - url 関数に渡された相対 URL を解決するためのベース URL です。

権限

url 関数を使用するには、CREATE TEMPORARY TABLE 権限が必要です。そのため、readonly = 1 に設定されているユーザーは利用できません。少なくとも readonly = 2 が必要です。

仮想カラム