url

指定された フォーマット と 構造 を使用して URL からテーブルを作成します

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

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

​

構文

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

​

パラメーター

Parameter	Description
URL	単一引用符で囲んだ HTTP または HTTPS のサーバーアドレスです。GET または POST リクエストを受け付けます (それぞれ SELECT クエリ、INSERT クエリに対応) 。型: 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 内の 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 は無視されます。

例

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 が必要です。

​

関連

• 仮想カラム