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 также представляет собой унифицированную обёртку, которая направляет запросы в нужный backend в зависимости от схемы URL, поэтому распознанная схема, отличная от HTTP, передаётся соответствующему движку — см. маршрутизация по схеме URL ниже.

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

  • Параметр URL должен соответствовать структуре Uniform Resource Locator. Для URL http/https (backend по умолчанию) он должен указывать на сервер, использующий HTTP или HTTPS, а для получения ответа от сервера не требуются дополнительные заголовки. URL с распознаваемой схемой, отличной от HTTP (file://, s3://, az://, hdfs://, …), вместо этого передаётся соответствующему движку — см. маршрутизация по схеме URL ниже.

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

Маршрутизация по схеме URL

Движок URL — это единая обёртка над другими движками для файловых и объектных хранилищ: в зависимости от схемы URL он перенаправляет запрос в нужный движок. http/https (а также любая нераспознанная схема) обрабатываются самим движком URL; file:// — движком File; s3://, gs://, gcs://, oss:// — движком S3; az://, azure://, abfss://, abfs:// — движком AzureBlobStorage; а hdfs:// — движком HDFS.

Маршрутизируются только те схемы S3, которые сопоставитель S3 URI может разрешить в конкретную конечную точку без дополнительной конфигурации (s3, а также gs/gcs/oss). Другие схемы поставщиков, совместимых с S3 (cos, obs, eos, …), зависят от региона и не имеют сопоставления с конечной точкой по умолчанию, поэтому передача такого URL в движок URL считается нераспознанной схемой и приводит к ошибке; для таких хранилищ используйте движок S3 напрямую (с настроенным url_scheme_mappers).

Настройка url_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 удалённый сервер должен поддерживать Chunked transfer encoding.

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

Подстановочные шаблоны с 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. Создайте простой 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, передаваемых в движок.
Navigation