url - ClickHouse Documentation

Функция url создаёт таблицу по URL с указанными format и structure. Функция url может использоваться в запросах SELECT и INSERT для работы с данными в таблицах URL.

Синтаксис

url(URL [,format] [,structure] [,headers])

Параметры

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

Возвращаемое значение

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

Примеры

Получение первых 3 строк таблицы, содержащей столбцы типа String и UInt32, с HTTP-сервера, который возвращает данные в формате CSV.

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

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

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;

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

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

Scheme	Dispatches to
`http`, `https` (and any unrecognized scheme)	сам движок `URL` (HTTP `GET`/`POST`)
`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 вида cos://… рассматривается как URL с нераспознанной схемой и возвращает ошибку; для таких backend используйте функцию s3 напрямую (с настроенным url_scheme_mappers). Для file:// относительный путь (file://data.csv) разрешается внутри каталога user_files, а абсолютный путь (file:///home/user/data.csv) должен, как обычно, указывать внутрь него. Аргументы format, structure и compression_method, а также настройка url_base работают одинаково независимо от цели перенаправления.

SELECT * FROM url('file://data.csv', CSV, 'a UInt32, b String');
SELECT * FROM url('s3://clickhouse-public-datasets/hits_compatible/hits.csv');

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

Глоб-шаблоны в URL

Шаблоны в { } используются для генерации набора сегментов или для указания адресов аварийного переключения. Поддерживаемые типы шаблонов и примеры см. в описании функции remote. Символ | внутри шаблонов используется для указания адресов аварийного переключения. Они перебираются в том же порядке, в котором перечислены в шаблоне. Количество сгенерированных адресов ограничено настройкой glob_expansion_max_elements. Сведения о синтаксисе глоб-шаблонов в пути URL (например, *, {a,b}, {N..M} и **) см. в разделе Глоб-шаблоны в пути. Обратите внимание, что ? начинает строку запроса в URL и не может использоваться как подстановочный знак в компоненте пути.

Подстановочные шаблоны с HTTP-страницами индекса

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

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

Пример:

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;

Виртуальные столбцы

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

настройка use_hive_partitioning

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

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

Разрешение относительных URL

Настройка url_base позволяет передавать в функцию url относительный URL. Когда задан url_base и аргумент функции представляет собой относительную ссылку, она разрешается относительно базового URL в соответствии с RFC 3986. Правила разрешения:

Относительный путь (например, 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 игнорируется.

Пример

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

Настройки хранилища

engine_url_skip_empty_files - позволяет пропускать пустые файлы при чтении. По умолчанию отключено.
enable_url_encoding - позволяет включать и отключать декодирование/кодирование пути в URI. По умолчанию включено.
url_base - базовый URL для разрешения относительных URL, передаваемых в функцию url.

Разрешения

Для функции url требуется разрешение CREATE TEMPORARY TABLE. Поэтому она не будет работать для пользователей с настройкой readonly = 1. Требуется значение readonly не ниже 2.

Виртуальные столбцы

​Синтаксис

​Параметры

​Возвращаемое значение

​Примеры

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

​Глоб-шаблоны в URL

​Подстановочные шаблоны с HTTP-страницами индекса

​Виртуальные столбцы

​настройка use_hive_partitioning

​Разрешение относительных URL

​Настройки хранилища

​Разрешения

​Связанные материалы