跳到主要内容
跳到主要内容

URL 表引擎

从远程 HTTP/HTTPS 服务器查询数据。该引擎类似于 File 引擎。

语法: URL(URL [,Format] [,CompressionMethod])

  • URL 参数必须符合统一资源定位符的结构。指定的 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 或 gz
  • deflate
  • brotli 或 br
  • lzma 或 xz
  • zstd 或 zst
  • lz4
  • bz2
  • snappy
  • none
  • auto

如果未指定 CompressionMethod,则默认为 auto。这意味着 ClickHouse 会自动从 URL 参数的后缀检测压缩方法。如果后缀与上述列出任一压缩方法匹配,则应用相应的压缩,否则不会启用任何压缩。

例如,对于引擎表达式 URL('http://localhost/test.gzip'),应用 gzip 压缩方法,但对于 URL('http://localhost/test.fr'),没有启用压缩,因为后缀 fr 不匹配上述任何压缩方法。

使用

INSERTSELECT 查询分别被转换为 POSTGET 请求。为了处理 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 │
└───────┴───────┘

实现细节

  • 读取和写入可以并行进行
  • 不支持:
    • ALTERSELECT...SAMPLE 操作。
    • 索引。
    • 复制。

虚拟列

  • _pathURL 的路径。类型:LowCardinality(String)
  • _fileURL 的资源名称。类型:LowCardinality(String)
  • _size — 资源大小(字节)。类型:Nullable(UInt64)。如果大小未知,则值为 NULL
  • _time — 文件的最后修改时间。类型:Nullable(DateTime)。如果时间未知,则值为 NULL
  • _headers - HTTP 响应头。类型:Map(LowCardinality(String), LowCardinality(String))

存储设置