> ## 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.

> Создаёт таблицу по `URL` с указанными `format` и `structure`

# url

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Не поддерживается в ClickHouse Cloud
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Экспериментальная возможность. <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">Подробнее.</a></u>
        </div>;
};

Функция `url` создаёт таблицу по `URL` с указанными `format` и `structure`.

Функция `url` может использоваться в запросах `SELECT` и `INSERT` для работы с данными в таблицах [URL](/docs/ru/reference/engines/table-engines/special/url).

<div id="syntax">
  ## Синтаксис
</div>

```sql theme={null}
url(URL [,format] [,structure] [,headers])
```

<div id="parameters">
  ## Параметры
</div>

| Параметр    | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `URL`       | `URL` в одинарных кавычках, схема которого определяет backend. `URL` с `http`/`https` (или нераспознанной схемой) — это адрес сервера, принимающего запросы `GET` или `POST` (для запросов `SELECT` и `INSERT` соответственно); `URL` с распознанной схемой, отличной от HTTP (`file://`, `s3://`, `az://`, `hdfs://`, …), делегируется соответствующей табличной функции — см. [Маршрутизация по схеме URL](#scheme-dispatch). Тип: [String](/docs/ru/reference/data-types/string). |
| `format`    | [Формат](/docs/ru/reference/formats/index) данных. Тип: [String](/docs/ru/reference/data-types/string).                                                                                                                                                                                                                                                                                                                                                                                   |
| `structure` | Структура таблицы в формате `'UserID UInt64, Name String'`. Определяет имена и типы столбцов. Тип: [String](/docs/ru/reference/data-types/string).                                                                                                                                                                                                                                                                                                                                   |
| `headers`   | Заголовки в формате `'headers('key1'='value1', 'key2'='value2')'`. Позволяет задать заголовки для HTTP-запроса.                                                                                                                                                                                                                                                                                                                                                                 |

<div id="returned_value">
  ## Возвращаемое значение
</div>

Таблица в указанном формате и с указанной структурой, содержащая данные из заданного `URL`.

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

Получение первых 3 строк таблицы, содержащей столбцы типа `String` и [UInt32](/docs/ru/reference/data-types/int-uint), с HTTP-сервера, который возвращает данные в формате [CSV](/docs/ru/reference/formats/CSV/CSV).

```sql theme={null}
SELECT * FROM url('http://127.0.0.1:12345/', CSV, 'column1 String, column2 UInt32', headers('Accept'='text/csv; charset=utf-8')) LIMIT 3;
```

Вставка данных из `URL` в таблицу:

```sql theme={null}
CREATE TABLE test_table (column1 String, column2 UInt32) ENGINE=Memory;
INSERT INTO FUNCTION url('http://127.0.0.1:8123/?query=INSERT+INTO+test_table+FORMAT+CSV', 'CSV', 'column1 String, column2 UInt32') VALUES ('http interface', 42);
SELECT * FROM test_table;
```

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

Функция `url` выступает как единая обёртка над другими табличными функциями для файловых и объектных хранилищ: она перенаправляет вызов в нужный backend в зависимости от схемы URL. Это позволяет читать данные из любого поддерживаемого источника, используя единый синтаксис.

| Scheme                                        | Dispatches to                                                                          |
| --------------------------------------------- | -------------------------------------------------------------------------------------- |
| `http`, `https` (and any unrecognized scheme) | сам движок `URL` (HTTP `GET`/`POST`)                                                   |
| `file`                                        | функция [`file`](/docs/ru/reference/functions/table-functions/file)                         |
| `s3`, `gs`, `gcs`, `oss`                      | функция [`s3`](/docs/ru/reference/functions/table-functions/s3)                             |
| `az`, `azure`, `abfss`, `abfs`                | функция [`azureBlobStorage`](/docs/ru/reference/functions/table-functions/azureBlobStorage) |
| `hdfs`                                        | функция [`hdfs`](/docs/ru/reference/functions/table-functions/hdfs)                         |

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

Для `file://` относительный путь (`file://data.csv`) разрешается внутри каталога [user\_files](/docs/ru/reference/settings/server-settings/settings#user_files_path), а абсолютный путь (`file:///home/user/data.csv`) должен, как обычно, указывать внутрь него.

Аргументы `format`, `structure` и `compression_method`, а также настройка [url\_base](#resolving-relative-urls) работают одинаково независимо от цели перенаправления.

```sql theme={null}
SELECT * FROM url('file://data.csv', CSV, 'a UInt32, b String');
SELECT * FROM url('s3://clickhouse-public-datasets/hits_compatible/hits.csv');
```

Поддержка схем URL в [`urlCluster`](/docs/ru/reference/functions/table-functions/urlCluster) пока не реализована: если передать в `urlCluster` схему, отличную от `http(s)`, функция вернёт ошибку. Для таких backend-соединений используйте соответствующую кластерную функцию (`s3Cluster`, `azureBlobStorageCluster`, `hdfsCluster`, …).

<div id="globs-in-url">
  ## Глоб-шаблоны в URL
</div>

Шаблоны в `{ }` используются для генерации набора сегментов или для указания адресов аварийного переключения. Поддерживаемые типы шаблонов и примеры см. в описании функции [remote](/docs/ru/reference/functions/table-functions/remote#globs-in-addresses).
Символ `|` внутри шаблонов используется для указания адресов аварийного переключения. Они перебираются в том же порядке, в котором перечислены в шаблоне. Количество сгенерированных адресов ограничено настройкой [glob\_expansion\_max\_elements](/docs/ru/reference/settings/session-settings#glob_expansion_max_elements).
Сведения о синтаксисе глоб-шаблонов в пути URL (например, `*`, `{a,b}`, `{N..M}` и `**`) см. в разделе [Глоб-шаблоны в пути](/docs/ru/reference/functions/table-functions/file#globs-in-path). Обратите внимание, что `?` начинает строку запроса в URL и не может использоваться как подстановочный знак в компоненте пути.

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

Для `url` и движка таблицы `URL` ClickHouse может разворачивать подстановочные шаблоны, получая HTTP-страницы индекса (HTML или plaintext) и извлекая URL из тела ответа. Это позволяет использовать шаблоны вида `/**/`, если сервер предоставляет листинг каталогов.

Примечания:

* Относительные URL разрешаются относительно URL страницы индекса.
* Шаблоны `URL` разворачиваются до получения страниц индекса, включая раскрытие сегментов, заданных через запятые и числовые диапазоны, а также варианты аварийного переключения `|` вне компонента пути.
* Шаблоны аварийного переключения `|` внутри компонента пути не поддерживаются при раскрытии HTTP-страниц индекса.
* Сопоставление с подстановочными шаблонами применяется к компоненту пути URL.
* Если URL в списке уже содержит строку запроса или фрагмент, они имеют приоритет над значениями из исходного URL. В противном случае используются строка запроса и фрагмент из исходного URL.
* Пустой список допустим; HTTP-ошибки (например, 404) для страниц индекса вызывают исключения.
* Максимальный размер страницы индекса ограничен параметром [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).

Пример:

```sql theme={null}
SELECT count()
FROM url('https://ftp.gnu.org/gnu/wget/wget-1.21*.tar.gz', 'RawBLOB')
SETTINGS max_threads = 1, allow_experimental_url_wildcard_from_index_pages = 1;
```

<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="hive-style-partitioning">
  ## настройка use\_hive\_partitioning
</div>

Если настройка `use_hive_partitioning` имеет значение 1, ClickHouse распознаёт партиционирование в стиле Hive в пути (`/name=value/`) и позволяет использовать столбцы партиций в качестве виртуальных столбцов в запросе. Эти виртуальные столбцы будут иметь те же имена, что и в пути с партициями.

**Пример**

Используйте виртуальный столбец, созданный при партиционировании в стиле Hive

```sql theme={null}
SELECT * FROM url('http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;
```

<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).

Правила разрешения:

* **Относительный путь** (например, `data.csv`): объединяется с путем базового URL — всё после последнего `/` в базовом пути заменяется. Наличие завершающего слеша имеет значение: `https://example.com/dir/` + `data.csv` дает `https://example.com/dir/data.csv`, а `https://example.com/dir` + `data.csv` дает `https://example.com/data.csv`. Сегменты с точками (`./` и `../`) нормализуются.
* **Относительный к хосту** (например, `/test/data.csv`): разрешается с использованием схемы и хоста базового URL.
* **Относительный к схеме** (например, `//other.com/test/data.csv`): разрешается с использованием схемы базового URL.
* **Только запрос** (например, `?x=1`): добавляется к полному базовому пути, заменяя существующие запрос или фрагмент.
* **Только фрагмент** (например, `#frag`): добавляется к базовому URL с сохранением запроса и заменой существующего фрагмента.
* **Пустой**: возвращает базовый URL без фрагмента.
* **Абсолютный URL**: передается без изменений; `url_base` игнорируется.

**Пример**

```sql theme={null}
SET url_base = 'https://raw.githubusercontent.com/ClickHouse/ClickHouse/master/';
SELECT * FROM url('tests/queries/0_stateless/data_csv/data.csv', CSV) LIMIT 3;
```

<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, передаваемых в функцию `url`.

<div id="permissions">
  ## Разрешения
</div>

Для функции `url` требуется разрешение `CREATE TEMPORARY TABLE`. Поэтому она не будет работать для пользователей с настройкой [readonly](/docs/ru/concepts/features/configuration/settings/permissions-for-queries#readonly) = 1. Требуется значение readonly не ниже 2.

<div id="related">
  ## Связанные материалы
</div>

* [Виртуальные столбцы](/docs/ru/reference/engines/table-engines/index#table_engines-virtual_columns)