> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

Запрашивает данные с удалённого HTTP/HTTPS-сервера и отправляет их на него. Этот движок похож на движок [File](/docs/ru/reference/engines/table-engines/special/file).

Движок `URL` также представляет собой унифицированную обёртку, которая направляет запросы в нужный backend в зависимости от схемы URL, поэтому распознанная схема, отличная от HTTP, передаётся соответствующему движку — см. [маршрутизация по схеме URL](#scheme-dispatch) ниже.

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

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

* `Format` должен поддерживаться ClickHouse в запросах `SELECT` и, при необходимости, в операциях `INSERT`. Полный список поддерживаемых форматов см. в разделе [Formats](/docs/ru/reference/formats/index#formats-overview).

  Если этот аргумент не указан, 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` не соответствует ни одному из указанных выше методов сжатия。

<div id="scheme-dispatch">
  ## Маршрутизация по схеме URL
</div>

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

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

Настройка [url\_base](/docs/ru/reference/settings/session-settings#url_base) применяется до маршрутизации по схеме, поэтому относительная ссылка сначала разрешается относительно базового адреса, а затем направляется в соответствующий движок.

```sql theme={null}
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);
```

<div id="using-the-engine-in-the-clickhouse-server">
  ## Использование
</div>

Запросы `INSERT` и `SELECT` преобразуются в запросы `POST` и `GET`
соответственно. Для обработки запросов `POST` удалённый сервер должен поддерживать
[Chunked transfer encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding).

Вы можете ограничить максимальное количество переходов по HTTP GET-перенаправлениям с помощью настройки [max\_http\_get\_redirects](/docs/ru/reference/settings/session-settings#max_http_get_redirects).

<div id="wildcards-with-http-index-pages">
  ## Подстановочные шаблоны с HTTP-индексными страницами
</div>

Когда включен параметр [allow\_experimental\_url\_wildcard\_from\_index\_pages](/docs/ru/reference/settings/session-settings#allow_experimental_url_wildcard_from_index_pages), движок таблицы `URL` может раскрывать подстановочные шаблоны, загружая HTTP-индексные страницы и извлекая из них ссылки.
Это тот же механизм, что используется в табличной функции [`url`](/docs/ru/reference/functions/table-functions/url#wildcards-with-http-index-pages).

Раскрытие ограничено параметром [max\_http\_index\_page\_size](/docs/ru/reference/settings/server-settings/settings#max_http_index_page_size) для каждой загружаемой индексной страницы и параметром [url\_wildcard\_max\_directories\_to\_read](/docs/ru/reference/settings/session-settings#url_wildcard_max_directories_to_read) для рекурсивного обхода каталогов.

<div id="example">
  ## Пример
</div>

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

```sql theme={null}
CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)
```

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

```python3 theme={null}
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()
```

```bash theme={null}
$ python3 server.py
```

**3.** Запросите данные:

```sql theme={null}
SELECT * FROM url_engine_table
```

```text theme={null}
┌─word──┬─value─┐
│ Hello │     1 │
│ World │     2 │
└───────┴───────┘
```

<div id="details-of-implementation">
  ## Детали реализации
</div>

* Чтение и запись могут выполняться параллельно
* Не поддерживаются:
  * Операции `ALTER` и `SELECT...SAMPLE`.
  * Индексы.
  * Репликация.

<div id="virtual-columns">
  ## Виртуальные столбцы
</div>

* `_path` — Путь к `URL`. Тип: `LowCardinality(String)`.
* `_file` — Имя ресурса `URL`. Тип: `LowCardinality(String)`.
* `_size` — Размер ресурса в байтах. Тип: `Nullable(UInt64)`. Если размер неизвестен, значение — `NULL`.
* `_time` — Время последнего изменения файла. Тип: `Nullable(DateTime)`. Если время неизвестно, значение — `NULL`.
* `_headers` - HTTP-заголовки ответа. Тип: `Map(LowCardinality(String), LowCardinality(String))`.

<div id="resolving-relative-urls">
  ## Разрешение относительных URL
</div>

Настройка [url\_base](/docs/ru/reference/settings/session-settings#url_base) позволяет использовать относительный URL в движке `URL`. Если задан `url_base`, URL, переданный в движок, разрешается относительно него в соответствии с [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). Полное описание правил разрешения приведено в [документации по табличной функции url](/docs/ru/reference/functions/table-functions/url#resolving-relative-urls).

**Пример**

```sql theme={null}
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;
```

<div id="storage-settings">
  ## Настройки хранилища
</div>

* [engine\_url\_skip\_empty\_files](/docs/ru/reference/settings/session-settings#engine_url_skip_empty_files) - позволяет пропускать пустые файлы при чтении. По умолчанию отключено.
* [enable\_url\_encoding](/docs/ru/reference/settings/session-settings#enable_url_encoding) - позволяет включать/отключать декодирование/кодирование пути в URI. По умолчанию включено.
* [url\_base](/docs/ru/reference/settings/session-settings#url_base) - базовый URL для разрешения относительных URL, передаваемых в движок.