Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

URL テーブルエンジン

View as MarkdownEdit this pageReport an issueSet up docs MCP

リモートの HTTP/HTTPS サーバーとの間でデータを読み書きします。このエンジンは File エンジンに似ています。

URL エンジンは、URL スキームに基づいて適切なバックエンドに振り分ける統一ラッパーでもあるため、認識される非 HTTP スキームは対応するエンジンに委譲されます。詳細は以下の URLスキームによるディスパッチ を参照してください。

構文: URL(URL [,Format] [,CompressionMethod])

  • URL パラメーターは Uniform Resource Locator の構造に従っている必要があります。http/https URL (デフォルトのバックエンド) の場合は、HTTP または HTTPS を使用するサーバーを指していなければならず、サーバーから応答を取得するために追加のヘッダーは必要ありません。認識される非 HTTP スキーム (file://、s3://、az://、hdfs://、…) を持つ URL は、代わりに対応するエンジンに振り分けられます。詳細は以下の URLスキームによるディスパッチ を参照してください。

  • Format には、ClickHouse が SELECT クエリで使用でき、必要に応じて INSERT でも使用できるものを指定する必要があります。対応フォーマットの一覧については、Formats を参照してください。

    この引数を指定しない場合、ClickHouse は URL パラメーターの接尾辞からフォーマットを自動的に検出します。URL パラメーターの接尾辞が対応フォーマットのいずれにも一致しない場合、テーブルの作成は失敗します。たとえば、エンジン式 URL('http://localhost/test.json') では、JSON フォーマットが適用されます。

  • CompressionMethod は、HTTP ボディを圧縮するかどうかを示します。圧縮が有効な場合、URL エンジンによって送信される HTTP パケットには、使用されている圧縮方式を示す 'Content-Encoding' ヘッダーが含まれます。

圧縮を有効にするには、まず URL パラメーターで指定したリモート HTTP エンドポイントが、対応する圧縮アルゴリズムをサポートしていることを確認してください。

対応する CompressionMethod は、次のいずれかである必要があります。

  • gzip or gz
  • deflate
  • brotli or br
  • lzma or xz
  • zstd or zst
  • lz4
  • bz2
  • snappy
  • none
  • auto

CompressionMethod を指定しない場合、デフォルトは auto です。これは、ClickHouse が URL パラメーターの接尾辞から圧縮方式を自動的に検出することを意味します。接尾辞が上記の圧縮方式のいずれかに一致する場合は対応する圧縮が適用され、一致しない場合は圧縮は有効になりません。

たとえば、エンジン式 URL('http://localhost/test.gzip') では gzip 圧縮方式が適用されますが、URL('http://localhost/test.fr') では接尾辞 fr が上記のどの圧縮方式にも一致しないため、圧縮は有効になりません。

URLスキームによるディスパッチ

URL エンジンは、他のファイルストレージ エンジンやオブジェクトストレージ エンジンを統一的に扱うラッパーで、URL スキームに基づいて適切なバックエンドに振り分けます。http/https (および認識されないスキーム) は URL エンジン自体で処理され、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、…) はリージョン固有で、デフォルトのエンドポイント マッピングがありません。そのため、このような URL を URL エンジンに渡すと、認識されないスキームとして扱われ、エラーとして報告されます。これらのバックエンドでは、S3 エンジンを直接使用してください (url_scheme_mappers を設定) 。

url_base 設定はスキームのディスパッチ前に適用されるため、相対参照はまず base に対して解決され、その後、対応するエンジンにルーティングされます。

CREATE TABLE file_via_url (a UInt32, b String) ENGINE = URL('file://data.csv', CSV);
CREATE TABLE s3_via_url (a UInt32, b String) ENGINE = URL('s3://bucket/key.csv', CSV);

使用方法

INSERT クエリと SELECT クエリは、それぞれ POST リクエストと GET リクエストに変換されます。 POST リクエストを処理するには、リモートサーバーが Chunked transfer encoding に対応している必要があります。

max_http_get_redirects 設定を使用すると、HTTP GET リダイレクトの最大ホップ数を制限できます。

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

allow_experimental_url_wildcard_from_index_pages が有効な場合、URL テーブルエンジンは、HTTPインデックスページを取得してそこからリンクを抽出することで、ワイルドカードを展開できます。 これは、url テーブル関数と同じ仕組みです。

展開は、取得する各インデックスページごとに max_http_index_page_size で、再帰的なディレクトリ走査については url_wildcard_max_directories_to_read で制限されます。

例

1. サーバー上に url_engine_table テーブルを作成します：

CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)

2. 標準の Python 3 ツールを使って簡易 HTTP サーバーを作成し、 起動します:

from http.server import BaseHTTPRequestHandler, HTTPServer

class CSVHTTPServer(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header('Content-type', 'text/csv')
        self.end_headers()

        self.wfile.write(bytes('Hello,1\nWorld,2\n', "utf-8"))

if __name__ == "__main__":
    server_address = ('127.0.0.1', 12345)
    HTTPServer(server_address, CSVHTTPServer).serve_forever()
$ python3 server.py

3. データをリクエストします：

SELECT * FROM url_engine_table
┌─word──┬─value─┐
│ Hello │     1 │
│ World │     2 │
└───────┴───────┘

実装の詳細

  • 読み取りと書き込みは並列で実行できます
  • サポートされていません:
    • ALTER および SELECT...SAMPLE 操作
    • 索引
    • レプリケーション

仮想カラム

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

相対 URL の解決

url_base 設定を使用すると、URL エンジンで相対 URL を使用できます。url_base が設定されている場合、エンジンに渡された URL は RFC 3986 に従ってそれを基準として解決されます。解決ルールの詳細については、url テーブル関数のドキュメント を参照してください。

例

SET url_base = 'http://127.0.0.1:12345/';
CREATE TABLE url_engine_table (word String, value UInt64) ENGINE = URL('hello.csv', CSV);
SELECT * FROM url_engine_table;

ストレージ設定

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