движок таблицы URL

Запрашивает данные с удалённого HTTP/HTTPS-сервера и отправляет их на него. Этот движок похож на движок File.

Запрашивает данные с удалённого HTTP/HTTPS-сервера и отправляет их на него. Этот движок похож на движок File.

Синтаксис: URL(URL [,Format] [,CompressionMethod])

• Параметр URL должен соответствовать структуре Uniform Resource Locator. Указанный URL должен указывать на сервер, использующий HTTP или HTTPS. Для получения ответа от сервера не требуются дополнительные заголовки.

• Format должен поддерживаться ClickHouse в запросах SELECT и, при необходимости, в операциях INSERT. Полный список поддерживаемых форматов см. в разделе Formats.

  Если этот аргумент не указан, ClickHouse автоматически определяет формат по суффиксу параметра URL. Если суффикс параметра URL не соответствует ни одному из поддерживаемых форматов, создать таблицу не удастся. Например, для выражения движка URL('http://localhost/test.json') применяется формат JSON.

• CompressionMethod указывает, должно ли тело HTTP-сообщения быть сжато. Если сжатие включено, HTTP-пакеты, отправляемые движком URL, содержат заголовок ‘Content-Encoding’, который указывает, какой метод сжатия используется.

Чтобы включить сжатие, сначала убедитесь, что удалённая HTTP конечная точка, указанная в параметре URL, поддерживает соответствующий алгоритм сжатия.

Поддерживаемый 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 не соответствует ни одному из указанных выше методов сжатия.

​

Использование

Запросы INSERT и SELECT преобразуются в запросы POST и GET соответственно. Для обработки запросов POST удалённый сервер должен поддерживать Chunked transfer encoding.

Вы можете ограничить максимальное количество переходов по HTTP GET-перенаправлениям с помощью настройки max_http_get_redirects.

​

Пример

1. Создайте таблицу url_engine_table на сервере:

CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)

2. Создайте простой HTTP-сервер с помощью стандартных средств Python 3 и запустите его:

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. По умолчанию включено.
• url_base - базовый URL для разрешения относительных URL, передаваемых в движок.