> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> リモートの HTTP/HTTPS サーバーとの間でデータを読み書きします。このエンジンは File エンジンに似ています。
# URL テーブルエンジン
リモートの HTTP/HTTPS サーバーとの間でデータを読み書きします。このエンジンは [File](/docs/ja/reference/engines/table-engines/special/file) エンジンに似ています。
`URL` エンジンは、URL スキームに基づいて適切なバックエンドに振り分ける統一ラッパーでもあるため、認識される非 HTTP スキームは対応するエンジンに委譲されます。詳細は以下の [URLスキームによるディスパッチ](#scheme-dispatch) を参照してください。
構文: `URL(URL [,Format] [,CompressionMethod])`
* `URL` パラメーターは Uniform Resource Locator の構造に従っている必要があります。`http`/`https` URL (デフォルトのバックエンド) の場合は、HTTP または HTTPS を使用するサーバーを指していなければならず、サーバーから応答を取得するために追加のヘッダーは必要ありません。認識される非 HTTP スキーム (`file://`、`s3://`、`az://`、`hdfs://`、…) を持つ URL は、代わりに対応するエンジンに振り分けられます。詳細は以下の [URLスキームによるディスパッチ](#scheme-dispatch) を参照してください。
* `Format` には、ClickHouse が `SELECT` クエリで使用でき、必要に応じて `INSERT` でも使用できるものを指定する必要があります。対応フォーマットの一覧については、[Formats](/docs/ja/reference/formats/index#formats-overview) を参照してください。
この引数を指定しない場合、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](/docs/ja/reference/engines/table-engines/special/file) エンジン、`s3://`、`gs://`、`gcs://`、`oss://` は [S3](/docs/ja/reference/engines/table-engines/integrations/s3) エンジン、`az://`、`azure://`、`abfss://`、`abfs://` は [AzureBlobStorage](/docs/ja/reference/engines/table-engines/integrations/azureBlobStorage) エンジン、`hdfs://` は [HDFS](/docs/ja/reference/engines/table-engines/integrations/hdfs) エンジンで処理されます。
ディスパッチされるのは、S3 URI mapper が追加設定なしで具体的なエンドポイントに解決できる S3 スキーム (`s3` に加えて `gs`/`gcs`/`oss`) のみです。その他の S3-compatible ベンダーのスキーム (`cos`、`obs`、`eos`、…) はリージョン固有で、デフォルトのエンドポイント マッピングがありません。そのため、このような URL を `URL` エンジンに渡すと、認識されないスキームとして扱われ、エラーとして報告されます。これらのバックエンドでは、[S3](/docs/ja/reference/engines/table-engines/integrations/s3) エンジンを直接使用してください (`url_scheme_mappers` を設定) 。
[url\_base](/docs/ja/reference/settings/session-settings#url_base) 設定はスキームのディスパッチ前に適用されるため、相対参照はまず base に対して解決され、その後、対応するエンジンにルーティングされます。
```sql theme={null}
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](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) に対応している必要があります。
[max\_http\_get\_redirects](/docs/ja/reference/settings/session-settings#max_http_get_redirects) 設定を使用すると、HTTP GET リダイレクトの最大ホップ数を制限できます。
## HTTPインデックスページでのワイルドカード
[allow\_experimental\_url\_wildcard\_from\_index\_pages](/docs/ja/reference/settings/session-settings#allow_experimental_url_wildcard_from_index_pages) が有効な場合、`URL` テーブルエンジンは、HTTPインデックスページを取得してそこからリンクを抽出することで、ワイルドカードを展開できます。
これは、[`url`](/docs/ja/reference/functions/table-functions/url#wildcards-with-http-index-pages) テーブル関数と同じ仕組みです。
展開は、取得する各インデックスページごとに [max\_http\_index\_page\_size](/docs/ja/reference/settings/server-settings/settings#max_http_index_page_size) で、再帰的なディレクトリ走査については [url\_wildcard\_max\_directories\_to\_read](/docs/ja/reference/settings/session-settings#url_wildcard_max_directories_to_read) で制限されます。
## 例
**1.** サーバー上に `url_engine_table` テーブルを作成します：
```sql theme={null}
CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)
```
**2.** 標準の Python 3 ツールを使って簡易 HTTP サーバーを作成し、
起動します:
```python3 theme={null}
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()
```
```bash theme={null}
$ python3 server.py
```
**3.** データをリクエストします：
```sql theme={null}
SELECT * FROM url_engine_table
```
```text theme={null}
┌─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](/docs/ja/reference/settings/session-settings#url_base) 設定を使用すると、`URL` エンジンで相対 URL を使用できます。`url_base` が設定されている場合、エンジンに渡された URL は [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) に従ってそれを基準として解決されます。解決ルールの詳細については、[url テーブル関数のドキュメント](/docs/ja/reference/functions/table-functions/url#resolving-relative-urls) を参照してください。
**例**
```sql theme={null}
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](/docs/ja/reference/settings/session-settings#engine_url_skip_empty_files) - 読み込み時に空のファイルをスキップできるようにします。デフォルトでは無効です。
* [enable\_url\_encoding](/docs/ja/reference/settings/session-settings#enable_url_encoding) - URI 内のパスのデコード/エンコードを有効/無効にできるようにします。デフォルトで有効です。
* [url\_base](/docs/ja/reference/settings/session-settings#url_base) - エンジンに渡される相対URLを解決するためのベースURL。