メインコンテンツへスキップ
リモートの HTTP/HTTPS サーバーとの間でデータを読み書きします。このエンジンは File エンジンに似ています。 構文: URL(URL [,Format] [,CompressionMethod])
  • URL パラメーターは Uniform Resource Locator の構造に従っている必要があります。指定する URL は、HTTP または HTTPS を使用するサーバーを指していなければなりません。サーバーから応答を取得するために、追加のヘッダーは必要ありません。
  • 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` が上記のどの圧縮方式にも一致しないため、圧縮は有効になりません。

​
使用方法

INSERT クエリと SELECT クエリは、それぞれ POST リクエストと GET リクエストに変換されます。 POST リクエストを処理するには、リモートサーバーが Chunked transfer encoding に対応している必要があります。 max_http_get_redirects 設定を使用すると、HTTP GET リダイレクトの最大ホップ数を制限できます。

​
例

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。
最終更新日 2026年6月10日