> ## 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/zh/reference/engines/table-engines/special/file) 表引擎类似。

`URL` 引擎还是一个统一的包装器，会根据 URL 协议分派到正确的后端，因此已识别的非 HTTP 协议会委托给匹配的引擎——请参阅下方的 [按 URL 协议分派](#scheme-dispatch)。

语法：`URL(URL [,Format] [,CompressionMethod])`

* `URL` 参数必须符合统一资源定位符的结构。对于 `http`/`https` URL (默认 后端) ，它必须指向使用 HTTP 或 HTTPS 的服务器，并且获取服务器响应时不需要任何额外的请求头。对于具有已识别非 HTTP 协议 (`file://`、`s3://`、`az://`、`hdfs://`、…) 的 URL，则会委托给匹配的引擎处理——请参阅下方的 [按 URL 协议分派](#scheme-dispatch)。

* `Format` 必须是 ClickHouse 可在 `SELECT` 查询中使用的格式，并且在需要时也可用于 `INSERT`。有关受支持格式的完整列表，请参阅 [Formats](/docs/zh/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` 与上述任何压缩方法都不匹配。

<div id="scheme-dispatch">
  ## 按 URL 协议分派
</div>

`URL` 引擎是在其他文件和对象存储引擎之上的统一封装：它会根据 URL 协议分派到正确的后端。`http`/`https` (以及任何无法识别的协议) 由 `URL` 引擎自身处理；`file://` 由 [File 表引擎](/docs/zh/reference/engines/table-engines/special/file) 处理；`s3://`、`gs://`、`gcs://`、`oss://` 由 [S3](/docs/zh/reference/engines/table-engines/integrations/s3) 引擎处理；`az://`、`azure://`、`abfss://`、`abfs://` 由 [AzureBlobStorage](/docs/zh/reference/engines/table-engines/integrations/azureBlobStorage) 引擎处理；`hdfs://` 由 [HDFS](/docs/zh/reference/engines/table-engines/integrations/hdfs) 引擎处理。

只有那些无需额外配置即可由 S3 URI 映射器解析为具体端点的 S3 协议 (`s3`，以及 `gs`/`gcs`/`oss`) 才会被分派。其他兼容 S3 的厂商协议 (`cos`、`obs`、`eos`、……) 依赖特定区域，且没有默认的端点映射，因此将此类 URL 传给 `URL` 引擎时，会被视为无法识别的协议并报错；对于这些后端，请直接使用 [S3](/docs/zh/reference/engines/table-engines/integrations/s3) 引擎 (并配置 `url_scheme_mappers`) 。

[url\_base](/docs/zh/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);
```

<div id="using-the-engine-in-the-clickhouse-server">
  ## 用法
</div>

`INSERT` 和 `SELECT` 查询会分别转换为 `POST` 和 `GET` 请求。
要处理 `POST` 请求，远程服务器必须支持
[分块传输编码](https://en.wikipedia.org/wiki/Chunked_transfer_encoding)。

你可以使用 [max\_http\_get\_redirects](/docs/zh/reference/settings/session-settings#max_http_get_redirects) 设置来限制 HTTP GET 重定向的最大跳转次数。

<div id="wildcards-with-http-index-pages">
  ## HTTP 索引页中的通配符
</div>

启用 [allow\_experimental\_url\_wildcard\_from\_index\_pages](/docs/zh/reference/settings/session-settings#allow_experimental_url_wildcard_from_index_pages) 后，`URL` 表引擎可以通过拉取 HTTP 索引页并从中提取链接来展开通配符。
其机制与 [`url`](/docs/zh/reference/functions/table-functions/url#wildcards-with-http-index-pages) 表函数相同。

展开过程会受到以下限制：对每个拉取的索引页，受 [max\_http\_index\_page\_size](/docs/zh/reference/settings/server-settings/settings#max_http_index_page_size) 限制；对于递归目录遍历，受 [url\_wildcard\_max\_directories\_to\_read](/docs/zh/reference/settings/session-settings#url_wildcard_max_directories_to_read) 限制。

<div id="example">
  ## 示例
</div>

**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 │
└───────┴───────┘
```

<div id="details-of-implementation">
  ## 实现细节
</div>

* 读写可并行进行
* 不支持：
  * `ALTER` 和 `SELECT...SAMPLE` 操作。
  * 索引。
  * 复制。

<div id="virtual-columns">
  ## 虚拟列
</div>

* `_path` — `URL` 的路径。类型：`LowCardinality(String)`。
* `_file` — `URL` 的资源名。类型：`LowCardinality(String)`。
* `_size` — 资源大小 (以字节为单位) 。类型：`Nullable(UInt64)`。如果大小未知，则值为 `NULL`。
* `_time` — 文件的最后修改时间。类型：`Nullable(DateTime)`。如果时间未知，则值为 `NULL`。
* `_headers` - HTTP 响应头。类型：`Map(LowCardinality(String), LowCardinality(String))`。

<div id="resolving-relative-urls">
  ## 解析相对 URL
</div>

[url\_base](/docs/zh/reference/settings/session-settings#url_base) 设置允许在 `URL` 引擎 中使用相对 URL。设置 `url_base` 后，传递给该 引擎 的 URL 会按照 [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) 相对于它进行解析。有关解析规则的完整说明，请参见 [url 表函数文档](/docs/zh/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;
```

<div id="storage-settings">
  ## 存储设置
</div>

* [engine\_url\_skip\_empty\_files](/docs/zh/reference/settings/session-settings#engine_url_skip_empty_files) - 允许在读取时跳过空文件。默认禁用。
* [enable\_url\_encoding](/docs/zh/reference/settings/session-settings#enable_url_encoding) - 允许对 URI 中的 path 启用/禁用解码和编码。默认启用。
* [url\_base](/docs/zh/reference/settings/session-settings#url_base) - 用于解析传递给引擎的相对 URL 的基础 URL。