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 参数必须符合统一资源定位符的结构。对于 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;

存储设置

Navigation