Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Прямые запросы к открытым табличным форматам

View as MarkdownEdit this pageReport an issueSet up docs MCP

ClickHouse предоставляет табличные функции для выполнения запросов к данным, хранящимся в открытых табличных форматах, непосредственно в объектном хранилище. Для этого не требуется подключаться к внешнему каталогу — данные запрашиваются на месте, подобно тому, как AWS Athena читает их из S3.

Вы передаёте путь в хранилище и учётные данные прямо в вызове функции, а ClickHouse берёт на себя всё остальное. Доступны весь синтаксис и все функции ClickHouse SQL, а запросы получают преимущества от параллельного выполнения в ClickHouse и эффективного нативного ридера Parquet.

В следующих примерах используется датасет hits, хранящийся в S3 в каждом формате lakehouse. Для каждого формата lakehouse существуют отдельные функции для каждого провайдера объектного хранилища.

Табличная функция iceberg (псевдоним icebergS3) читает таблицы Iceberg напрямую из объектного хранилища. Для каждого бэкенда хранилища предусмотрены свои варианты: icebergS3, icebergAzure, icebergHDFS и icebergLocal.

Пример синтаксиса:

icebergS3(url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method])

icebergAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

icebergLocal(path_to_table, [,format] [,compression_method])

Пример:

SELECT
    url,
    count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url
ORDER BY cnt DESC
LIMIT 5
┌─url────────────────────────────────────────────────┬─────cnt─┐
│ http://liver.ru/belgorod/page/1006.jки/доп_приборы │ 3288173 │ -- 3.29 million
│ http://kinopoisk.ru                                │ 1625250 │ -- 1.63 million
│ http://bdsm_po_yers=0&with_video                   │  791465 │
│ http://video.yandex                                │  582400 │
│ http://smeshariki.ru/region                        │  514984 │
└────────────────────────────────────────────────────┴─────────┘

5 rows in set. Elapsed: 3.375 sec. Processed 100.00 million rows, 9.98 GB (29.63 million rows/s., 2.96 GB/s.)
Peak memory usage: 10.48 GiB.

Кластерный вариант

Функция icebergS3Cluster распределяет операции чтения между несколькими узлами кластера ClickHouse. Узел-инициатор устанавливает соединения со всеми узлами и динамически распределяет файлы данных. Каждый узел-воркер запрашивает и обрабатывает задачи до тех пор, пока не будут прочитаны все файлы. icebergCluster — псевдоним для icebergS3Cluster. Также существуют варианты для Azure (icebergAzureCluster) и HDFS (icebergHDFSCluster).

Пример синтаксиса:

icebergS3Cluster(cluster_name, url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method])
-- icebergCluster is an alias for icebergS3Cluster

icebergAzureCluster(cluster_name, connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

Пример (ClickHouse Cloud):

SELECT
    url,
    count() AS cnt
FROM icebergS3Cluster(
    'default',
    'https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/'
)
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Движок таблицы

В качестве альтернативы использованию табличной функции в каждом запросе можно создать постоянную таблицу с помощью движка таблиц Iceberg. Данные по-прежнему хранятся в объектном хранилище и считываются по требованию — никакие данные не копируются в ClickHouse. Преимущество заключается в том, что определение таблицы хранится в ClickHouse и доступно всем пользователям в разных сеансах без необходимости каждый раз указывать путь к хранилищу и учётные данные. Для каждого backend-хранилища предусмотрены варианты движка: IcebergS3 (или псевдоним Iceberg), IcebergAzure, IcebergHDFS и IcebergLocal.

И движок таблицы, и табличная функция поддерживают кэширование данных, используя тот же механизм кэширования, что и движки хранилища S3, AzureBlobStorage и HDFS. Кроме того, кэш метаданных хранит в памяти информацию из файлов манифестов, сокращая повторные чтения метаданных Iceberg. Этот кэш включён по умолчанию через настройку use_iceberg_metadata_files_cache.

Пример синтаксиса:

Движок таблицы Iceberg — это псевдоним для IcebergS3.

CREATE TABLE iceberg_table
    ENGINE = IcebergS3(url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,compression_method])

CREATE TABLE iceberg_table
    ENGINE = IcebergAzure(connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression])

CREATE TABLE iceberg_table
    ENGINE = IcebergLocal(path_to_table, [,format] [,compression_method])

Пример:

CREATE TABLE hits_iceberg
    ENGINE = IcebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
GROUP BY url
ORDER BY cnt DESC
LIMIT 5
┌─url────────────────────────────────────────────────┬─────cnt─┐
│ http://liver.ru/belgorod/page/1006.jки/доп_приборы │ 3288173 │
│ http://kinopoisk.ru                                │ 1625250 │
│ http://bdsm_po_yers=0&with_video                   │  791465 │
│ http://video.yandex                                │  582400 │
│ http://smeshariki.ru/region                        │  514984 │
└────────────────────────────────────────────────────┴─────────┘

5 rows in set. Elapsed: 2.737 sec. Processed 100.00 million rows, 9.98 GB (36.53 million rows/s., 3.64 GB/s.)
Peak memory usage: 10.53 GiB.

Список поддерживаемых возможностей, включая отсечение партиций, эволюцию схемы, перемещение во времени, кэширование и другое, см. в матрице поддержки. Полную справочную информацию см. в документации по табличной функции iceberg и движку таблиц Iceberg.

Navigation