Skip to main content
Skip to main content
Edit this page

URL Table Engine

Queries data to/from a remote HTTP/HTTPS server. This engine is similar to the File engine.

Syntax: URL(URL [,Format] [,CompressionMethod])

  • The URL parameter must conform to the structure of a Uniform Resource Locator. The specified URL must point to a server that uses HTTP or HTTPS. This does not require any additional headers for getting a response from the server.

  • The Format must be one that ClickHouse can use in SELECT queries and, if necessary, in INSERTs. For the full list of supported formats, see Formats.

    If this argument is not specified, ClickHouse detects the format automatically from the suffix of the URL parameter. If the suffix of URL parameter does not match any supported formats, it fails to create table. For example, for engine expression URL('http://localhost/test.json'), JSON format is applied.

  • CompressionMethod indicates that whether the HTTP body should be compressed. If the compression is enabled, the HTTP packets sent by the URL engine contain 'Content-Encoding' header to indicate which compression method is used.

To enable compression, please first make sure the remote HTTP endpoint indicated by the URL parameter supports corresponding compression algorithm.

The supported CompressionMethod should be one of following:

  • gzip or gz
  • deflate
  • brotli or br
  • lzma or xz
  • zstd or zst
  • lz4
  • bz2
  • snappy
  • none
  • auto

If CompressionMethod is not specified, it defaults to auto. This means ClickHouse detects compression method from the suffix of URL parameter automatically. If the suffix matches any of compression method listed above, corresponding compression is applied or there won't be any compression enabled.

For example, for engine expression URL('http://localhost/test.gzip'), gzip compression method is applied, but for URL('http://localhost/test.fr'), no compression is enabled because the suffix fr does not match any compression methods above.

Usage​

INSERT and SELECT queries are transformed to POST and GET requests, respectively. For processing POST requests, the remote server must support Chunked transfer encoding.

You can limit the maximum number of HTTP GET redirect hops using the max_http_get_redirects setting.

Example​

1. Create a url_engine_table table on the server :

2. Create a basic HTTP server using the standard Python 3 tools and start it:

3. Request data:

Details of Implementation​

  • Reads and writes can be parallel
  • Not supported:
    • ALTER and SELECT...SAMPLE operations.
    • Indexes.
    • Replication.

Virtual Columns​

  • _path — Path to the URL. Type: LowCardinality(String).
  • _file — Resource name of the URL. Type: LowCardinality(String).
  • _size — Size of the resource in bytes. Type: Nullable(UInt64). If the size is unknown, the value is NULL.
  • _time — Last modified time of the file. Type: Nullable(DateTime). If the time is unknown, the value is NULL.
  • _headers - HTTP response headers. Type: Map(LowCardinality(String), LowCardinality(String)).

Storage Settings​