URL 表引擎

从远程 HTTP/HTTPS 服务器查询数据。此引擎类似于 文件 引擎。

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

• URL 参数必须符合统一资源定位器的结构。指定的 URL 必须指向使用 HTTP 或 HTTPS 的服务器。这不需要任何额外的标头来从服务器获取响应。

• Format 必须是 ClickHouse 在 SELECT 查询中，以及在必要时在 INSERTs 中使用的格式。有关支持格式的完整列表，请参见 格式.

  如果未指定此参数，ClickHouse 会从 URL 参数的后缀自动检测格式。如果 URL 参数的后缀与任何支持的格式不匹配，则无法创建表。例如，对于引擎表达式 URL('https://127.0.0.1/test.json')，将应用 JSON 格式。

• CompressionMethod 指示是否应压缩 HTTP 主体。如果启用了压缩，则 URL 引擎发送的 HTTP 数据包包含 'Content-Encoding' 标头，以指示使用了哪种压缩方法。

要启用压缩，请首先确保 URL 参数指示的远程 HTTP 端点支持相应的压缩算法。

支持的 CompressionMethod 应为以下之一

• gzip 或 gz
• deflate
• brotli 或 br
• lzma 或 xz
• zstd 或 zst
• lz4
• bz2
• snappy
• 无
• 自动

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

例如，对于引擎表达式 URL('https://127.0.0.1/test.gzip')，将应用 gzip 压缩方法，但对于 URL('https://127.0.0.1/test.fr')，不会启用压缩，因为后缀 fr 与上面的任何压缩方法都不匹配。

用法

INSERT 和 SELECT 查询分别转换为 POST 和 GET 请求。为了处理 POST 请求，远程服务器必须支持 分块传输编码.

可以使用 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 │
└───────┴───────┘

实现细节

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

PARTITION BY

PARTITION BY — 可选。可以通过对分区键进行数据分区来创建单独的文件。在大多数情况下，您不需要分区键，如果需要，通常不需要比按月更细粒度地进行分区。分区不会加快查询速度（与 ORDER BY 表达式相反）。您不应使用过于细粒度的分区。不要按客户标识符或名称对数据进行分区（而是将客户标识符或名称作为 ORDER BY 表达式中的第一个列）。

要按月进行分区，请使用 toYYYYMM(date_column) 表达式，其中 date_column 是一个具有 Date 类型的日期列。这里的分区名称具有 "YYYYMM" 格式。

虚拟列

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

存储设置

• engine_url_skip_empty_files - 允许在读取时跳过空文件。默认情况下禁用。
• enable_url_encoding - 允许启用/禁用 uri 中路径的解码/编码。默认情况下启用。