Внешние диски для хранения данных

Документация по highlight-next-line

Данные, обрабатываемые в ClickHouse, обычно хранятся в локальной файловой системе машины, на которой работает сервер ClickHouse. Для этого требуются диски большой емкости, которые могут быть дорогими. Чтобы не хранить данные локально, поддерживаются различные варианты хранилищ:

1. Объектное хранилище Amazon S3.
2. Azure Blob Storage.
3. Не поддерживается: Hadoop Distributed File System (HDFS)

ClickHouse также поддерживает внешние движки таблиц, которые отличаются от варианта внешнего хранилища, описанного на этой странице, поскольку позволяют читать данные, хранящиеся в распространенных файловых форматах (например, Parquet). На этой странице описывается конфигурация хранилища для таблиц семейства MergeTree или семейства Log.

1. для работы с данными, хранящимися на дисках Amazon S3, используйте движок таблицы S3.
2. для работы с данными, хранящимися в Azure Blob Storage, используйте движок таблицы AzureBlobStorage.
3. для работы с данными в Hadoop Distributed File System (не поддерживается) используйте движок таблицы HDFS.

​

Настройка внешнего хранилища

Семейства движков таблиц MergeTree и Log могут хранить данные в S3, AzureBlobStorage, HDFS (не поддерживается), используя соответственно диски типов s3, azure_blob_storage, hdfs (не поддерживается).

Для настройки диска требуется:

1. Раздел type со значением одного из следующих типов: s3, azure_blob_storage, hdfs (не поддерживается), local_blob_storage, web.
2. Конфигурация конкретного типа внешнего хранилища.

Начиная с версии ClickHouse 24.1 можно использовать новую опцию конфигурации. Для этого нужно указать:

1. type со значением object_storage
2. object_storage_type со значением одного из следующих типов: s3, azure_blob_storage (или просто azure, начиная с 24.3), hdfs (не поддерживается), local_blob_storage (или просто local, начиная с 24.3), web.

При необходимости можно указать metadata_type (по умолчанию используется значение local), также его можно задать как plain, web и, начиная с 24.4, plain_rewritable. Использование типа метаданных plain описано в разделе plain storage, тип метаданных web можно использовать только с типом объектного хранилища web, а тип метаданных local хранит файлы метаданных локально (каждый файл метаданных содержит сопоставление с файлами в объектном хранилище и некоторую дополнительную метаинформацию о них).

Например:

<s3>
    <type>s3</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3>

эквивалентна следующей конфигурации (начиная с версии 24.1):

<s3>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>local</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3>

Конфигурация ниже:

<s3_plain>
    <type>s3_plain</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

равно:

<s3_plain>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>plain</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

Полная конфигурация хранилища может выглядеть так:

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
                <use_environment_credentials>1</use_environment_credentials>
            </s3>
        </disks>
        <policies>
            <s3>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3>
        </policies>
    </storage_configuration>
</clickhouse>

Начиная с версии 24.1 это также может выглядеть так:

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>object_storage</type>
                <object_storage_type>s3</object_storage_type>
                <metadata_type>local</metadata_type>
                <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
                <use_environment_credentials>1</use_environment_credentials>
            </s3>
        </disks>
        <policies>
            <s3>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3>
        </policies>
    </storage_configuration>
</clickhouse>

Чтобы сделать определённый тип хранилища используемым по умолчанию для всех таблиц MergeTree, добавьте следующий раздел в конфигурационный файл:

<clickhouse>
    <merge_tree>
        <storage_policy>s3</storage_policy>
    </merge_tree>
</clickhouse>

Если вы хотите настроить определённую политику хранения для конкретной таблицы, её можно задать в настройках при создании таблицы:

CREATE TABLE test (a Int32, b String)
ENGINE = MergeTree() ORDER BY a
SETTINGS storage_policy = 's3';

Вы также можете использовать disk вместо storage_policy. В этом случае раздел storage_policy в файле конфигурации не нужен — достаточно раздела disk.

CREATE TABLE test (a Int32, b String)
ENGINE = MergeTree() ORDER BY a
SETTINGS disk = 's3';

​

refresh_parts_interval and table_disk

Эта настройка предназначена для нереплицируемых таблиц MergeTree, в которых части могут записываться извне и требуется обновлять обнаружение метаданных из хранилища.

Настройка MergeTree refresh_parts_interval включает периодическое обновление списка частей данных из нижележащего хранилища (например, чтобы подхватывать части, записанные извне). Ключевое различие здесь — общие метаданные для всех реплик и локальные метаданные реплики (например, S3 с локальными метаданными на каждой реплике): только при общих метаданных новые части будут видны всем репликам. Само по себе использование Объектного хранилища не означает, что метаданные общие.

• Объектное хранилище (например, disk = 's3') не означает, что метаданные общие. Когда метаданные по умолчанию хранятся локально на каждой реплике, каждая реплика независимо управляет своими указателями на blob-объекты в Объектном хранилище. Изменения, внесённые на одной реплике, не видны другим. В этом случае refresh_parts_interval не сделает новые части видимыми на всех репликах, потому что метаданные, которые читает каждая реплика, локальны для неё.

• Для автоматического обновления частей метаданные файловой системы должны быть общими (или таблица должна использовать собственные метаданные в режиме только для чтения, для которых применимо обновление). Установка table_disk = true вместе с локальным для таблицы диском (например, SETTINGS disk = disk(type=object_storage, ...), table_disk = true) — один из способов получить нужную семантику: таблица управляет жизненным циклом метаданных, а хранилище рассматривается как только для чтения, поэтому refresh_parts_interval работает, и части, добавленные извне, могут быть обнаружены.

• При глобально определённом диске (например, disk = 's3' в storage_configuration) и локальных метаданных по умолчанию каждая реплика имеет собственное состояние метаданных. Даже если blob-объекты находятся в S3, такое хранилище не считается общим для целей refresh_parts_interval, и новые части, созданные вне ClickHouse или на другой реплике, обнаружены не будут.

Чтобы автоматическое обновление частей работало, убедитесь, что метаданные являются общими, либо используйте диск уровня таблицы с table_disk = true, как показано выше. Если полагаться только на refresh_parts_interval при локальных метаданных реплики, части не будут обновляться должным образом.

refresh_parts_interval не используется для таблиц ReplicatedMergeTree. Реплицируемые таблицы уже синхронизируют части через механизм репликации. Эта настройка применима только к нереплицируемым таблицам MergeTree, в которых части записываются извне и требуется обновление метаданных.

​

Динамическая конфигурация

Конфигурацию хранилища также можно задать в файле конфигурации без предопределённого диска, а затем настроить её через параметры запроса CREATE/ATTACH.

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

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=web,
    endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
  );

В примере ниже к внешнему хранилищу добавляется кэш.

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=cache,
    max_size='1Gi',
    path='/var/lib/clickhouse/custom_disk_cache/',
    disk=disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      )
  );

В выделенных ниже настройках обратите внимание, что диск type=web вложен в диск type=cache.

В примере используется type=web, но в качестве динамического можно настроить любой тип диска, включая локальный диск. Для локальных дисков аргумент path должен находиться внутри каталога, заданного параметром конфигурации сервера custom_local_disks_base_directory. У этого параметра нет значения по умолчанию, поэтому при использовании локального диска его тоже нужно задать.

Также возможна комбинация конфигурации на основе config и конфигурации, определённой в SQL:

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=cache,
    max_size='1Gi',
    path='/var/lib/clickhouse/custom_disk_cache/',
    disk=disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      )
  );

где web берётся из файла конфигурации сервера:

<storage_configuration>
    <disks>
        <web>
            <type>web</type>
            <endpoint>'https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'</endpoint>
        </web>
    </disks>
</storage_configuration>

​

Использование хранилища S3

​

Обязательные параметры

Параметр	Описание
endpoint	URL конечной точки S3 в стиле path или virtual hosted. Должен включать бакет и корневой путь для хранения данных.
access_key_id	Идентификатор ключа доступа S3, используемый для аутентификации.
secret_access_key	Секретный ключ доступа S3, используемый для аутентификации.

​

Необязательные параметры

Параметр	Описание	Значение по умолчанию
region	Имя региона S3.	-
support_batch_delete	Определяет, нужно ли проверять поддержку пакетного удаления. Установите false при использовании Google Cloud Storage (GCS), так как GCS не поддерживает пакетное удаление.	true
use_environment_credentials	Считывает учетные данные AWS из переменных окружения: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY и AWS_SESSION_TOKEN, если они заданы. Примечание: учетные данные из окружения используются всеми дисками S3 совместно. Чтобы использовать разные учетные данные для разных дисков, явно укажите access_key_id и secret_access_key для каждого диска.	false
use_insecure_imds_request	Если true, использует небезопасный запрос IMDS при получении учетных данных из метаданных Amazon EC2.	false
expiration_window_seconds	Льготный период (в секундах) для проверки того, не истекли ли учетные данные с ограниченным сроком действия.	120
proxy	Конфигурация прокси для конечной точки S3. Каждый элемент uri внутри блока proxy должен содержать URL прокси.	-
connect_timeout_ms	Тайм-аут подключения сокета в миллисекундах.	10000 (10 секунд)
request_timeout_ms	Тайм-аут запроса в миллисекундах.	5000 (5 секунд)
retry_attempts	Количество повторных попыток для неудачных запросов.	10
single_read_retries	Количество повторных попыток при разрыве соединения во время чтения.	4
min_bytes_for_seek	Минимальное количество байт, при котором используется операция seek вместо последовательного чтения.	1 MB
metadata_path	Путь в локальной файловой системе для хранения файлов метаданных S3.	/var/lib/clickhouse/disks/<disk_name>/
skip_access_check	Если true, пропускает проверку доступа к диску при запуске.	false
header	Добавляет указанный HTTP-заголовок в запросы. Можно указывать несколько раз.	-
server_side_encryption_customer_key_base64	Обязательные заголовки для доступа к объектам S3 с шифрованием SSE-C.	-
server_side_encryption_kms_key_id	Обязательные заголовки для доступа к объектам S3 с шифрованием SSE-KMS. Пустая строка означает использование управляемого AWS ключа S3.	-
server_side_encryption_kms_encryption_context	Заголовок контекста шифрования для SSE-KMS (используется вместе с server_side_encryption_kms_key_id).	-
server_side_encryption_kms_bucket_key_enabled	Включает ключи S3 бакета для SSE-KMS (используется вместе с server_side_encryption_kms_key_id).	Соответствует настройке на уровне бакета
s3_max_put_rps	Максимальное число PUT-запросов в секунду до применения ограничения скорости.	0 (без ограничений)
s3_max_put_burst	Максимальное число одновременных PUT-запросов до достижения лимита RPS.	То же, что и s3_max_put_rps
s3_max_get_rps	Максимальное число GET-запросов в секунду до применения ограничения скорости.	0 (без ограничений)
s3_max_get_burst	Максимальное число одновременных GET-запросов до достижения лимита RPS.	То же, что и s3_max_get_rps
read_resource	Имя ресурса для планирования запросов чтения.	Пустая строка (отключено)
write_resource	Имя ресурса для планирования запросов записи.	Пустая строка (отключено)
key_template	Определяет формат генерации ключей объектов с использованием синтаксиса re2. Требует флага storage_metadata_write_full_object_key. Несовместим с root path в endpoint. Требует key_compatibility_prefix.	-
key_compatibility_prefix	Требуется вместе с key_template. Указывает предыдущий root path из endpoint для чтения старых версий метаданных.	-
read_only	Разрешает только чтение с диска.	-

Google Cloud Storage (GCS) также поддерживается с типом s3. См. MergeTree с хранилищем GCS.

​

Использование Plain Storage

В 22.10 появился новый тип диска s3_plain, который предоставляет хранилище с однократной записью. Параметры его конфигурации такие же, как у типа диска s3. В отличие от типа диска s3, он хранит данные в исходном виде. Иными словами, вместо случайно сгенерированных имен blob-объектов он использует обычные имена файлов (так же, как ClickHouse хранит файлы на локальном диске) и не хранит локально никаких метаданных. Например, метаданные восстанавливаются по данным в s3.

Этот тип диска позволяет хранить статическую версию таблицы, поскольку он не позволяет выполнять слияние существующих данных и не поддерживает вставку новых данных. Один из сценариев использования этого типа диска — создание на нем резервных копий, что можно сделать с помощью BACKUP TABLE data TO Disk('plain_disk_name', 'backup_name'). После этого можно выполнить RESTORE TABLE data AS data_restored FROM Disk('plain_disk_name', 'backup_name') или использовать ATTACH TABLE data (...) ENGINE = MergeTree() SETTINGS disk = 'plain_disk_name'.

Конфигурация:

<s3_plain>
    <type>s3_plain</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

Начиная с версии 24.1 можно настроить любой диск Объектного хранилища (s3, azure, hdfs (не поддерживается), local) с использованием типа метаданных plain.

Конфигурация:

<s3_plain>
    <type>object_storage</type>
    <object_storage_type>azure</object_storage_type>
    <metadata_type>plain</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

​

Использование простого перезаписываемого хранилища в S3

Новый тип диска s3_plain_rewritable появился в версии 24.4. Как и тип диска s3_plain, он не требует дополнительного хранилища для файлов метаданных. Вместо этого метаданные хранятся в S3. В отличие от типа диска s3_plain, s3_plain_rewritable позволяет выполнять слияние и поддерживает операции INSERT. Мутации и репликация таблиц не поддерживаются.

Этот тип диска можно использовать для таблиц MergeTree без репликации. Хотя тип диска s3 подходит для таблиц MergeTree без репликации, можно выбрать тип диска s3_plain_rewritable, если вам не нужны локальные метаданные таблицы и вы готовы мириться с ограниченным набором операций. Это может быть полезно, например, для системных таблиц.

Конфигурация:

<s3_plain_rewritable>
    <type>s3_plain_rewritable</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain_rewritable>

равно

<s3_plain_rewritable>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>plain_rewritable</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain_rewritable>

Начиная с версии 24.5, можно настроить любой диск объектного хранилища (s3, azure, local), используя тип метаданных plain_rewritable.

​

Использование Azure Blob Storage

Движки таблиц семейства MergeTree могут хранить данные в Azure Blob Storage с помощью диска типа azure_blob_storage.

Разметка конфигурации:

<storage_configuration>
    ...
    <disks>
        <blob_storage_disk>
            <type>azure_blob_storage</type>
            <storage_account_url>http://account.blob.core.windows.net</storage_account_url>
            <container_name>container</container_name>
            <account_name>account</account_name>
            <account_key>pass123</account_key>
            <metadata_path>/var/lib/clickhouse/disks/blob_storage_disk/</metadata_path>
            <cache_path>/var/lib/clickhouse/disks/blob_storage_disk/cache/</cache_path>
            <skip_access_check>false</skip_access_check>
        </blob_storage_disk>
    </disks>
    ...
</storage_configuration>

​

Параметры подключения

Параметр	Описание	Значение по умолчанию
storage_account_url (обязательный)	URL учетной записи Azure Blob Storage. Примеры: http://account.blob.core.windows.net или http://azurite1:10000/devstoreaccount1.	-
container_name	Имя целевого контейнера.	default-container
container_already_exists	Управляет поведением при создании контейнера: - false: создает новый контейнер - true: подключается напрямую к существующему контейнеру - Не задан: проверяет, существует ли контейнер, и при необходимости создает его	-

Параметры аутентификации (диск попробует все доступные методы, а также Managed Identity Credential):

Параметр	Описание
connection_string	Для аутентификации с использованием строки подключения.
account_name	Для аутентификации с использованием Shared Key (используется с account_key).
account_key	Для аутентификации с использованием Shared Key (используется с account_name).

​

Параметры ограничений

Параметр	Описание
s3_max_single_part_upload_size	Максимальный размер однократной загрузки блока в Blob Storage.
min_bytes_for_seek	Минимальный размер области, в которой возможно позиционирование.
max_single_read_retries	Максимальное число попыток чтения фрагмента данных из Blob Storage.
max_single_download_retries	Максимальное число попыток скачать буфер, доступный для чтения, из Blob Storage.
thread_pool_size	Максимальное число потоков для создания экземпляров IDiskRemote.
s3_max_inflight_parts_for_one_file	Максимальное число параллельных PUT-запросов для одного объекта.

​

Другие параметры

Параметр	Описание	Значение по умолчанию
metadata_path	Путь в локальной файловой системе для хранения файлов метаданных Blob Storage.	/var/lib/clickhouse/disks/<disk_name>/
skip_access_check	Если true, пропускает проверку доступа к диску при запуске.	false
read_resource	Имя ресурса для планирования запросов на чтение.	Пустая строка (отключено)
write_resource	Имя ресурса для планирования запросов на запись.	Пустая строка (отключено)
metadata_keep_free_space_bytes	Объём свободного места на диске метаданных, который нужно зарезервировать.	-

Примеры рабочих конфигураций можно найти в каталоге интеграционных тестов (см., например, test_merge_tree_azure_blob_storage или test_azure_blob_storage_zero_copy_replication).

Репликация zero-copy не готова к промышленной эксплуатации

В ClickHouse версии 22.8 и выше репликация zero-copy по умолчанию отключена. Эта возможность не рекомендуется для использования в production.

​

Использование хранилища HDFS (не поддерживается)

В этой примерной конфигурации:

• диск имеет тип hdfs (не поддерживается)
• данные хранятся по адресу hdfs://hdfs1:9000/clickhouse/

Кстати, HDFS не поддерживается, поэтому при его использовании возможны проблемы. Если столкнётесь с ними, можете отправить pull request с исправлением.

<clickhouse>
    <storage_configuration>
        <disks>
            <hdfs>
                <type>hdfs</type>
                <endpoint>hdfs://hdfs1:9000/clickhouse/</endpoint>
                <skip_access_check>true</skip_access_check>
            </hdfs>
            <hdd>
                <type>local</type>
                <path>/</path>
            </hdd>
        </disks>
        <policies>
            <hdfs>
                <volumes>
                    <main>
                        <disk>hdfs</disk>
                    </main>
                    <external>
                        <disk>hdd</disk>
                    </external>
                </volumes>
            </hdfs>
        </policies>
    </storage_configuration>
</clickhouse>

Имейте в виду, что HDFS может не работать в некоторых нестандартных сценариях.

​

Использование шифрования данных

Вы можете шифровать данные, хранящиеся на внешних дисках S3 или HDFS (не поддерживается), а также на локальном диске. Чтобы включить режим шифрования, в конфигурационном файле необходимо определить диск типа encrypted и выбрать диск, на котором будут сохраняться данные. Диск encrypted шифрует все записываемые файлы на лету, а при чтении файлов с диска encrypted автоматически расшифровывает их. Таким образом, с диском encrypted можно работать как с обычным диском.

Пример конфигурации диска:

<disks>
  <disk1>
    <type>local</type>
    <path>/path1/</path>
  </disk1>
  <disk2>
    <type>encrypted</type>
    <disk>disk1</disk>
    <path>path2/</path>
    <key>_16_ascii_chars_</key>
  </disk2>
</disks>

Например, когда ClickHouse записывает данные из некоторой таблицы в файл store/all_1_1_0/data.bin на disk1, фактически этот файл будет записан на физический диск по пути /path1/store/all_1_1_0/data.bin.

При записи того же файла на disk2 он фактически будет записан на физический диск по пути /path1/path2/store/all_1_1_0/data.bin в зашифрованном виде.

​

Обязательные параметры

Параметр	Тип	Описание
type	String	Для создания зашифрованного диска необходимо задать значение encrypted.
disk	String	Тип диска, используемого для нижележащего хранилища.
key	Uint64	Ключ для шифрования и дешифрования. Может быть указан в шестнадцатеричном формате с помощью key_hex. Несколько ключей можно указать с помощью атрибута id.

​

Необязательные параметры

Параметр	Тип	По умолчанию	Описание
path	String	Корневой каталог	Место на диске, где будут сохраняться данные.
current_key_id	String	-	Идентификатор ключа, используемого для шифрования. Все указанные ключи можно использовать для расшифровки.
algorithm	Enum	AES_128_CTR	Алгоритм шифрования. Доступные варианты: - AES_128_CTR (ключ длиной 16 байт) - AES_192_CTR (ключ длиной 24 байта) - AES_256_CTR (ключ длиной 32 байта)

Пример конфигурации диска:

<clickhouse>
    <storage_configuration>
        <disks>
            <disk_s3>
                <type>s3</type>
                <endpoint>...
            </disk_s3>
            <disk_s3_encrypted>
                <type>encrypted</type>
                <disk>disk_s3</disk>
                <algorithm>AES_128_CTR</algorithm>
                <key_hex id="0">00112233445566778899aabbccddeeff</key_hex>
                <key_hex id="1">ffeeddccbbaa99887766554433221100</key_hex>
                <current_key_id>1</current_key_id>
            </disk_s3_encrypted>
        </disks>
    </storage_configuration>
</clickhouse>

​

Использование локального кэша

Начиная с версии 22.3 в конфигурации хранилища можно настроить локальный кэш для дисков. Для версий 22.3–22.7 кэш поддерживается только для дисков типа s3. Для версий >= 22.8 кэш поддерживается для любых типов дисков: S3, Azure, Local, Encrypted и т. д. Для версий >= 23.5 кэш поддерживается только для удалённых типов дисков: S3, Azure, HDFS (не поддерживается). Кэш использует политику LRU.

Пример конфигурации для версий 22.8 и выше:

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>...</endpoint>
                ... s3 configuration ...
            </s3>
            <cache>
                <type>cache</type>
                <disk>s3</disk>
                <path>/s3_cache/</path>
                <max_size>10Gi</max_size>
            </cache>
        </disks>
        <policies>
            <s3_cache>
                <volumes>
                    <main>
                        <disk>cache</disk>
                    </main>
                </volumes>
            </s3_cache>
        <policies>
    </storage_configuration>

Пример конфигурации для версий до 22.8:

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>...</endpoint>
                ... s3 configuration ...
                <data_cache_enabled>1</data_cache_enabled>
                <data_cache_max_size>10737418240</data_cache_max_size>
            </s3>
        </disks>
        <policies>
            <s3_cache>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3_cache>
        <policies>
    </storage_configuration>

Настройки дисковой конфигурации File Cache:

Эти настройки должны быть заданы в разделе конфигурации диска.

Параметр	Тип	По умолчанию	Описание
path	String	-	Обязательно. Путь к каталогу, где будет храниться кэш.
max_size	Size	-	Обязательно. Максимальный размер кэша в байтах или в удобочитаемом формате (например, 10Gi). При достижении лимита файлы вытесняются по политике LRU. Поддерживаются форматы ki, Mi, Gi (начиная с v22.10).
cache_on_write_operations	Boolean	false	Включает сквозное кэширование для запросов INSERT и фоновых слияний. Может быть переопределено для конкретного запроса с помощью enable_filesystem_cache_on_write_operations.
enable_filesystem_query_cache_limit	Boolean	false	Включает ограничение размера кэша для каждого запроса на основе max_query_cache_size.
enable_cache_hits_threshold	Boolean	false	Если параметр включен, данные кэшируются только после нескольких чтений.
cache_hits_threshold	Integer	0	Количество чтений, необходимое перед кэшированием данных (требуется enable_cache_hits_threshold).
enable_bypass_cache_with_threshold	Boolean	false	Пропускает кэш для больших диапазонов чтения.
bypass_cache_threshold	Size	256Mi	Размер диапазона чтения, при котором кэш обходится (требуется enable_bypass_cache_with_threshold).
max_file_segment_size	Size	8Mi	Максимальный размер одного файла кэша в байтах или в удобочитаемом формате.
max_elements	Integer	10000000	Максимальное количество файлов кэша.
load_metadata_threads	Integer	16	Количество потоков для загрузки метаданных кэша при запуске.
use_split_cache	Boolean	false	Использовать разделение файлов на системные и данные.
split_cache_ratio	Double	0.1	Отношение системного сегмента к общему размеру кэша для split_cache.

Примечание: Для значений размера поддерживаются единицы измерения ki, Mi, Gi и т. д. (например, 10Gi).

​

Настройки запросов/профилей для File Cache

Setting	Type	Default	Description
enable_filesystem_cache	Boolean	true	Включает или отключает использование кэша для отдельного запроса, даже при использовании диска типа cache.
read_from_filesystem_cache_if_exists_otherwise_bypass_cache	Boolean	false	Если включено, использует кэш только при наличии данных; новые данные кэшироваться не будут.
enable_filesystem_cache_on_write_operations	Boolean	false (Cloud: true)	Включает сквозное кэширование при операциях записи. Требует cache_on_write_operations в конфигурации кэша.
enable_filesystem_cache_log	Boolean	false	Включает подробное логирование использования кэша в system.filesystem_cache_log.
filesystem_cache_allow_background_download	Boolean	true	Разрешает завершать загрузку частично загруженных сегментов в фоновом режиме. Отключите этот параметр, чтобы загрузка выполнялась в рамках текущего запроса/сеанса.
max_query_cache_size	Size	false	Максимальный размер кэша для одного запроса. Требует enable_filesystem_query_cache_limit в конфигурации кэша.
filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit	Boolean	true	Определяет поведение при достижении max_query_cache_size: - true: Прекращает загрузку новых данных - false: Вытесняет старые данные, чтобы освободить место для новых

Параметры конфигурации кэша и параметры кэша запросов соответствуют последней версии ClickHouse; в более ранних версиях некоторые возможности могут не поддерживаться.

​

Системные таблицы файлового кэша

Имя таблицы	Описание	Требования
system.filesystem_cache	Отображает текущее состояние файлового кэша.	Нет
system.filesystem_cache_log	Показывает подробную статистику использования кэша по каждому запросу.	Требуется enable_filesystem_cache_log = true

​

Команды управления кэшем

SYSTEM CLEAR|DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER) — ON CLUSTER

Эта команда поддерживается только без указания <cache_name>

SHOW FILESYSTEM CACHES

Выводит список файловых кэшей, настроенных на сервере. (В версиях 22.8 и ниже команда называется SHOW CACHES)

Query

SHOW FILESYSTEM CACHES

Response

┌─Caches────┐
│ s3_cache  │
└───────────┘

DESCRIBE FILESYSTEM CACHE '<cache_name>'

Показывает конфигурацию кэша и некоторую общую статистику для указанного кэша. Имя кэша можно получить с помощью команды SHOW FILESYSTEM CACHES. (Для версий ниже или равных 22.8 команда называется DESCRIBE CACHE)

Query

DESCRIBE FILESYSTEM CACHE 's3_cache'

Response

┌────max_size─┬─max_elements─┬─max_file_segment_size─┬─boundary_alignment─┬─cache_on_write_operations─┬─cache_hits_threshold─┬─current_size─┬─current_elements─┬─path───────┬─background_download_threads─┬─enable_bypass_cache_with_threshold─┐
│ 10000000000 │      1048576 │             104857600 │            4194304 │                         1 │                    0 │         3276 │               54 │ /s3_cache/ │                           2 │                                  0 │
└─────────────┴──────────────┴───────────────────────┴────────────────────┴───────────────────────────┴──────────────────────┴──────────────┴──────────────────┴────────────┴─────────────────────────────┴────────────────────────────────────┘

Текущие метрики кэша	Асинхронные метрики кэша	События profile для кэша
FilesystemCacheSize	FilesystemCacheBytes	CachedReadBufferReadFromSourceBytes, CachedReadBufferReadFromCacheBytes
FilesystemCacheElements	FilesystemCacheFiles	CachedReadBufferReadFromSourceMicroseconds, CachedReadBufferReadFromCacheMicroseconds
		CachedReadBufferCacheWriteBytes, CachedReadBufferCacheWriteMicroseconds
		CachedWriteBufferCacheWriteBytes, CachedWriteBufferCacheWriteMicroseconds

​

Использование статического Web-хранилища (только для чтения)

Это диск в режиме только для чтения. Данные на нем можно только читать, но нельзя изменять. Новая таблица подключается к этому диску с помощью запроса ATTACH TABLE (см. пример ниже). Локальный диск фактически не используется: каждый запрос SELECT приводит к http-запросу для получения необходимых данных. Любое изменение данных таблицы приведет к исключению, то есть следующие типы запросов не допускаются: CREATE TABLE, ALTER TABLE, RENAME TABLE, DETACH TABLE и TRUNCATE TABLE. Web-хранилище можно использовать только для чтения. Например, для размещения образцов данных или для миграции данных. Для этого существует инструмент clickhouse-static-files-uploader, который подготавливает каталог данных для заданной таблицы (SELECT data_paths FROM system.tables WHERE name = 'table_name'). Для каждой нужной таблицы создается каталог с файлами. Эти файлы можно загрузить, например, на веб-сервер со статическими файлами. После такой подготовки вы сможете подключить эту таблицу к любому серверу ClickHouse через DiskWeb.

В этой примерной конфигурации:

• диск имеет тип web
• данные размещены по адресу http://nginx:80/test1/
• используется кэш в локальном хранилище

<clickhouse>
    <storage_configuration>
        <disks>
            <web>
                <type>web</type>
                <endpoint>http://nginx:80/test1/</endpoint>
            </web>
            <cached_web>
                <type>cache</type>
                <disk>web</disk>
                <path>cached_web_cache/</path>
                <max_size>100000000</max_size>
            </cached_web>
        </disks>
        <policies>
            <web>
                <volumes>
                    <main>
                        <disk>web</disk>
                    </main>
                </volumes>
            </web>
            <cached_web>
                <volumes>
                    <main>
                        <disk>cached_web</disk>
                    </main>
                </volumes>
            </cached_web>
        </policies>
    </storage_configuration>
</clickhouse>

Хранилище также можно временно настроить в рамках запроса, если веб-датасет не предполагается использовать регулярно; см. динамическую конфигурацию и пропустите редактирование конфигурационного файла.

На GitHub размещён демо-набор данных. Чтобы подготовить собственные таблицы для веб- хранилища, см. инструмент clickhouse-static-files-uploader

В этом запросе ATTACH TABLE указанный UUID совпадает с именем каталога с данными, а конечная точка — это URL исходного содержимого GitHub.

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      );

Готовый тестовый сценарий. Вам нужно добавить эту конфигурацию в config:

<clickhouse>
    <storage_configuration>
        <disks>
            <web>
                <type>web</type>
                <endpoint>https://clickhouse-datasets.s3.yandex.net/disk-with-static-files-tests/test-hits/</endpoint>
            </web>
        </disks>
        <policies>
            <web>
                <volumes>
                    <main>
                        <disk>web</disk>
                    </main>
                </volumes>
            </web>
        </policies>
    </storage_configuration>
</clickhouse>

Затем выполните следующий запрос:

ATTACH TABLE test_hits UUID '1ae36516-d62d-4218-9ae3-6516d62da218'
(
    WatchID UInt64,
    JavaEnable UInt8,
    Title String,
    GoodEvent Int16,
    EventTime DateTime,
    EventDate Date,
    CounterID UInt32,
    ClientIP UInt32,
    ClientIP6 FixedString(16),
    RegionID UInt32,
    UserID UInt64,
    CounterClass Int8,
    OS UInt8,
    UserAgent UInt8,
    URL String,
    Referer String,
    URLDomain String,
    RefererDomain String,
    Refresh UInt8,
    IsRobot UInt8,
    RefererCategories Array(UInt16),
    URLCategories Array(UInt16),
    URLRegions Array(UInt32),
    RefererRegions Array(UInt32),
    ResolutionWidth UInt16,
    ResolutionHeight UInt16,
    ResolutionDepth UInt8,
    FlashMajor UInt8,
    FlashMinor UInt8,
    FlashMinor2 String,
    NetMajor UInt8,
    NetMinor UInt8,
    UserAgentMajor UInt16,
    UserAgentMinor FixedString(2),
    CookieEnable UInt8,
    JavascriptEnable UInt8,
    IsMobile UInt8,
    MobilePhone UInt8,
    MobilePhoneModel String,
    Params String,
    IPNetworkID UInt32,
    TraficSourceID Int8,
    SearchEngineID UInt16,
    SearchPhrase String,
    AdvEngineID UInt8,
    IsArtifical UInt8,
    WindowClientWidth UInt16,
    WindowClientHeight UInt16,
    ClientTimeZone Int16,
    ClientEventTime DateTime,
    SilverlightVersion1 UInt8,
    SilverlightVersion2 UInt8,
    SilverlightVersion3 UInt32,
    SilverlightVersion4 UInt16,
    PageCharset String,
    CodeVersion UInt32,
    IsLink UInt8,
    IsDownload UInt8,
    IsNotBounce UInt8,
    FUniqID UInt64,
    HID UInt32,
    IsOldCounter UInt8,
    IsEvent UInt8,
    IsParameter UInt8,
    DontCountHits UInt8,
    WithHash UInt8,
    HitColor FixedString(1),
    UTCEventTime DateTime,
    Age UInt8,
    Sex UInt8,
    Income UInt8,
    Interests UInt16,
    Robotness UInt8,
    GeneralInterests Array(UInt16),
    RemoteIP UInt32,
    RemoteIP6 FixedString(16),
    WindowName Int32,
    OpenerName Int32,
    HistoryLength Int16,
    BrowserLanguage FixedString(2),
    BrowserCountry FixedString(2),
    SocialNetwork String,
    SocialAction String,
    HTTPError UInt16,
    SendTiming Int32,
    DNSTiming Int32,
    ConnectTiming Int32,
    ResponseStartTiming Int32,
    ResponseEndTiming Int32,
    FetchTiming Int32,
    RedirectTiming Int32,
    DOMInteractiveTiming Int32,
    DOMContentLoadedTiming Int32,
    DOMCompleteTiming Int32,
    LoadEventStartTiming Int32,
    LoadEventEndTiming Int32,
    NSToDOMContentLoadedTiming Int32,
    FirstPaintTiming Int32,
    RedirectCount Int8,
    SocialSourceNetworkID UInt8,
    SocialSourcePage String,
    ParamPrice Int64,
    ParamOrderID String,
    ParamCurrency FixedString(3),
    ParamCurrencyID UInt16,
    GoalsReached Array(UInt32),
    OpenstatServiceName String,
    OpenstatCampaignID String,
    OpenstatAdID String,
    OpenstatSourceID String,
    UTMSource String,
    UTMMedium String,
    UTMCampaign String,
    UTMContent String,
    UTMTerm String,
    FromTag String,
    HasGCLID UInt8,
    RefererHash UInt64,
    URLHash UInt64,
    CLID UInt32,
    YCLID UInt64,
    ShareService String,
    ShareURL String,
    ShareTitle String,
    ParsedParams Nested(
        Key1 String,
        Key2 String,
        Key3 String,
        Key4 String,
        Key5 String,
        ValueDouble Float64),
    IslandID FixedString(16),
    RequestNum UInt32,
    RequestTry UInt8
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(EventDate)
ORDER BY (CounterID, EventDate, intHash32(UserID))
SAMPLE BY intHash32(UserID)
SETTINGS storage_policy='web';

​

Обязательные параметры

Параметр	Описание
type	web. В противном случае диск не будет создан.
endpoint	URL конечной точки в формате path. URL конечной точки должен содержать корневой путь для хранения данных, в который они были загружены.

​

Необязательные параметры

Параметр	Описание	Значение по умолчанию
min_bytes_for_seek	Минимальное количество байтов, при котором используется операция seek вместо последовательного чтения	1 MB
remote_fs_read_backoff_threashold	Максимальное время ожидания при попытке чтения данных с удалённого диска	10000 секунд
remote_fs_read_backoff_max_tries	Максимальное количество попыток чтения с задержкой	5

Если запрос завершается исключением DB:Exception Unreachable URL, попробуйте изменить настройки: http_connection_timeout, http_receive_timeout, keep_alive_timeout.

Чтобы получить файлы для загрузки, выполните: clickhouse static-files-disk-uploader --metadata-path <path> --output-dir <dir> (--metadata-path можно найти с помощью запроса SELECT data_paths FROM system.tables WHERE name = 'table_name').

При загрузке файлов по endpoint их нужно помещать в каталог <endpoint>/store/, но в конфигурации должен быть указан только endpoint.

Если при загрузке диска URL недоступен в момент, когда сервер поднимает таблицы, все ошибки перехватываются. В этом случае при наличии ошибок таблицы можно перезагрузить (снова сделать видимыми) через DETACH TABLE table_name -> ATTACH TABLE table_name. Если метаданные были успешно загружены при запуске сервера, таблицы становятся доступными сразу.

Используйте настройку http_max_single_read_retries, чтобы ограничить максимальное количество повторных попыток в рамках одного HTTP-чтения.

​

Репликация без копирования (не готово к использованию в production)

Репликация без копирования возможна, но не рекомендуется для дисков S3 и HDFS (не поддерживается). Репликация без копирования означает, что если данные удалённо хранятся на нескольких машинах и их нужно синхронизировать, то реплицируются только метаданные (пути к частям данных), а не сами данные.

Репликация без копирования не готова к использованию в production

В ClickHouse версии 22.8 и выше репликация без копирования по умолчанию отключена. Эта возможность не рекомендуется для использования в production.