URL 表引擎 - ClickHouse Documentation

从远程 HTTP/HTTPS 服务器查询数据，并向其写入数据。此引擎与 File 表引擎类似。 URL 引擎还是一个统一的包装器，会根据 URL 协议分派到正确的后端，因此已识别的非 HTTP 协议会委托给匹配的引擎——请参阅下方的按 URL 协议分派。语法：URL(URL [,Format] [,CompressionMethod])

URL 参数必须符合统一资源定位符的结构。对于 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 映射器解析为具体端点的 S3 协议 (s3，以及 gs/gcs/oss) 才会被分派。其他兼容 S3 的厂商协议 (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 请求，远程服务器必须支持分块传输编码。你可以使用 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 中的 path 启用/禁用解码和编码。默认启用。
url_base - 用于解析传递给引擎的相对 URL 的基础 URL。

​按 URL 协议分派

​用法

​HTTP 索引页中的通配符

​示例

​实现细节

​虚拟列

​解析相对 URL

​存储设置

按 URL 协议分派

用法

HTTP 索引页中的通配符

示例

实现细节

虚拟列

解析相对 URL

存储设置