- Объектное хранилище Amazon S3.
- Azure Blob Storage.
- Не поддерживается: Hadoop Distributed File System (HDFS)
ClickHouse также поддерживает внешние движки таблиц, которые отличаются от
варианта внешнего хранилища, описанного на этой странице, поскольку позволяют читать данные,
хранящиеся в распространенных файловых форматах (например, Parquet). На этой странице описывается
конфигурация хранилища для таблиц семейства
MergeTree или семейства Log.- для работы с данными, хранящимися на дисках
Amazon S3, используйте движок таблицы S3. - для работы с данными, хранящимися в Azure Blob Storage, используйте движок таблицы AzureBlobStorage.
- для работы с данными в Hadoop Distributed File System (не поддерживается) используйте движок таблицы HDFS.
Настройка внешнего хранилища
Семейства движков таблицMergeTree и Log
могут хранить данные в S3, AzureBlobStorage, HDFS (не поддерживается), используя соответственно диски типов s3,
azure_blob_storage, hdfs (не поддерживается).
Тип диска
s3 также можно использовать с провайдерами S3-совместимого объектного хранилища, такими как Alibaba Cloud Object Storage Service. Настройте endpoint, указав S3-совместимую конечную точку провайдера, и учитывайте все специфические для провайдера требования совместимости.- Раздел
typeсо значением одного из следующих типов:s3,azure_blob_storage,hdfs(не поддерживается),local_blob_storage,web. - Конфигурация конкретного типа внешнего хранилища.
typeсо значениемobject_storageobject_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 хранит файлы метаданных локально (каждый файл метаданных содержит сопоставление с файлами в объектном хранилище и некоторую дополнительную метаинформацию о них).
Например:
24.1):
MergeTree,
добавьте следующий раздел в конфигурационный файл:
disk вместо storage_policy. В этом случае раздел storage_policy в файле конфигурации не нужен —
достаточно раздела disk.
refresh_parts_interval and table_disk
Эта настройка предназначена для нереплицируемых таблиц MergeTree, в которых части могут записываться извне и требуется обновлять обнаружение метаданных из хранилища. Настройка MergeTreerefresh_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.
type=web вложен
в диск type=cache.
В примере используется
type=web, но в качестве динамического можно настроить любой тип диска,
включая локальный диск. Для локальных дисков аргумент path должен находиться внутри
каталога, заданного параметром конфигурации сервера custom_local_disks_base_directory.
У этого параметра нет значения по умолчанию, поэтому при использовании локального диска
его тоже нужно задать.web берётся из файла конфигурации сервера:
Использование хранилища S3
Обязательные параметры
Необязательные параметры
Google Cloud Storage (GCS) также поддерживается при использовании типа
s3. См. GCS backed MergeTree.Использование 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'.
Конфигурация:
24.1 можно настроить любой диск Объектного хранилища (s3, azure, hdfs (не поддерживается), local) с использованием
типа метаданных plain.
Конфигурация:
Использование обычного хранилища с поддержкой перезаписи в S3
Новый тип дискаs3_plain_rewritable появился в версии 24.4.
Как и тип диска s3_plain, он не требует дополнительного хранилища для
файлов метаданных. Вместо этого метаданные хранятся в S3.
В отличие от типа диска s3_plain, s3_plain_rewritable позволяет выполнять слияние
и поддерживает операции INSERT.
Репликация таблиц не поддерживается.
Мутации и операции ALTER
поддерживаются, если жёсткие ссылки не отключены с помощью enable_hard_links (см. ниже).
Этот тип диска можно использовать для нереплицируемых таблиц MergeTree. Хотя
тип диска s3 подходит для нереплицируемых таблиц MergeTree, можно выбрать
тип диска s3_plain_rewritable, если вам не нужны локальные метаданные
таблицы. Это может быть полезно, например, для системных таблиц.
Конфигурация:
24.5, можно настроить любой диск объектного хранилища
(s3, azure, local), используя тип метаданных plain_rewritable.
Снимок метаданных
Метаданные дискаplain_rewritable хранятся в объектном хранилище в виде
объекта prefix.path для каждого каталога. Чтобы построить по этим объектам состояние в оперативной памяти,
нужно получить список содержимого каталога метаданных, прочитать каждый prefix.path
и получить список содержимого каждого каталога — это десятки тысяч запросов даже для
диска с единственной таблицей.
Чтобы ускорить этот процесс, диск, записывающий данные, дополнительно записывает компактный
снимок всего состояния в __meta/snapshot.bin (версионируемый бинарный
формат, сжатый с помощью ZSTD) для дисков только для чтения, указывающих на то же
расположение (readonly установлен в true или диск подключён с read_only, установленным
в true).
Диск только для чтения загружает всё состояние из снимка одним запросом,
а при периодических обновлениях (см. настройку MergeTree refresh_parts_interval)
проверяет снимок и перечитывает его, только если он был переписан. Такой диск вообще не получает
список содержимого каталога метаданных и не читает prefix.path: единственный запрос списка касается
маркеров незавершённых операций и выполняется одним запросом — это нужно, чтобы файл,
который пишущая сторона заменяет в данный момент, читался из резервной копии. Диск только для чтения в любом случае работает с
отложенным состоянием, полагаясь на время жизни старых частей таблиц MergeTree,
и снимок — это отложенное состояние того же рода: изменения
пишущей стороны становятся видны считывателям, когда пишущая сторона переписывает снимок.
Это касается и файлов, которые пишущая сторона заменила или переписала на месте: пока
снимок не переписан, считыватель видит их с прежним размером и
бинарным объектом, который, возможно, уже перезаписан или удалён, — ровно так же, как их до следующего обновления видит считыватель,
получающий список содержимого объектного хранилища. Снимок лишь
расширяет это окно не более чем на metadata_snapshot_write_delay_ms.
Диск только для чтения получает список содержимого объектного хранилища, только если снимка нет (например, у пишущей стороны он отключён или она работает
на более старой версии) или его не удаётся прочитать.
Пишущая сторона должна располагать актуальным и точным состоянием, поэтому она никогда не читает
снимок: при запуске она, как обычно, получает список содержимого объектного хранилища и лишь затем записывает
снимок. Пишущая сторона, у которой metadata_snapshot_enabled установлен в false,
при запуске удаляет оставшийся с прошлого раза снимок, чтобы диски только для чтения
не продолжали использовать устаревшее состояние. Если снимок не удаётся прочитать или
маркер незавершённой операции повреждён, диск только для чтения получает список содержимого
объектного хранилища и не использует этот снимок, пока он не будет переписан.
Снимок используется только в объектных хранилищах, атомарно заменяющих объект,
чтобы диск только для чтения никогда не увидел частично записанный снимок:
S3, Azure Blob Storage и локальное хранилище. На HDFS и на конечных точках Azure Data Lake Storage
Gen2 (например, OneLake) снимок не записывается и не читается, и
диски получают список содержимого объектного хранилища так же, как без снимка; оставшийся
там с прошлого раза снимок удаляется пишущей стороной при запуске.
Обе настройки читаются только при создании диска: изменение вступает в силу
после перезапуска сервера,
SYSTEM RELOAD CONFIG его не применяет. То же
относится и к роли диска: будет ли он записывать или читать снимок,
определяется параметром readonly при создании диска, поэтому изменение readonly также требует
перезапуска сервера.
Более старые версии игнорируют __meta/snapshot.bin: они его не читают, не переписывают и не
удаляют. Поэтому если версию пишущей стороны понизили до версии без поддержки снимков,
а диски только для чтения продолжают работать на более новой версии, снимок, оставленный
пишущей стороной, нужно вывести из использования — иначе диски только для чтения продолжат его использовать и не
увидят изменений, сделанных после понижения версии. Либо удалите
__meta/snapshot.bin после остановки более новой пишущей стороны и до запуска
более старой, либо установите metadata_snapshot_enabled в false на дисках только для чтения
и перезапустите их, чтобы они получали список содержимого объектного хранилища.
DiskPlainRewritableSnapshotRead, DiskPlainRewritableSnapshotWritten
и DiskPlainRewritableSnapshotWriteFailed в
system.events позволяют отслеживать, как используется снимок.
Жёсткие ссылки на обычных дисках с поддержкой перезаписи
ОперацииALTER и мутации таблицы MergeTree не копируют неизменённые файлы,
а используют их совместно в исходной части и в её мутированной версии с помощью жёстких ссылок.
Настройка enable_hard_links (по умолчанию 1) позволяет диску с
метаданными plain_rewritable создавать настоящие жёсткие ссылки, благодаря чему становятся доступны
эти операции. Установите её в 0, чтобы диск оставался доступным для чтения серверами версий ниже 26.10;
в этом случае жёсткие ссылки эмулируются копированием, а операции ALTER, изменяющие
данные, и мутации не поддерживаются:
- Сервер, в котором нет настройки
enable_hard_links, не может прочитать каталог в таком формате — он считывает все метаданные каталога как его логический путь. Поэтому после понижения версии до такой диск с подобными каталогами становится недоступным для чтения, и его нельзя использовать совместно с этой версией. Каталоги, в которых никогда не было жёстких ссылок, сохраняют прежнюю структуру, поэтому диск остаётся доступным для чтения более старыми серверами до первой операции, создающей жёсткую ссылку, — мутации,ALTER,FREEZEили резервного копирования. Повторное отключение настройки не преобразует существующие каталоги обратно. - Настройка считывается только при создании диска: изменение вступает в силу после
перезапуска сервера,
SYSTEM RELOAD CONFIGего не применяет. - Объект, последняя ссылка на который удалена, удаляется в два шага: сначала перезаписываются метаданные каталога, а затем удаляется сам объект. Если работа сервера будет принудительно завершена между этими шагами, объект останется в бакете, и на него ничто не будет ссылаться, поэтому его придётся удалить вручную.
Использование Azure Blob Storage
Движки таблиц семействаMergeTree могут хранить данные в Azure Blob Storage
с помощью диска типа azure_blob_storage.
Разметка конфигурации:
Параметры подключения
Параметры аутентификации (диск попробует все доступные методы, а также Managed Identity Credential):
Параметры ограничений
Другие параметры
Примеры рабочих конфигураций можно найти в каталоге интеграционных тестов (см., например, test_merge_tree_azure_blob_storage или test_azure_blob_storage_zero_copy_replication).
Репликация zero-copy не готова к промышленной эксплуатацииВ ClickHouse версии 22.8 и выше репликация zero-copy по умолчанию отключена. Эта возможность не рекомендуется для использования в продакшне.
Использование хранилища HDFS (не поддерживается)
В этой примерной конфигурации:- диск имеет тип
hdfs(не поддерживается) - данные хранятся по адресу
hdfs://hdfs1:9000/clickhouse/
Использование шифрования данных
Вы можете шифровать данные, хранящиеся на внешних дисках S3 или HDFS (не поддерживается), а также на локальном диске. Чтобы включить режим шифрования, в конфигурационном файле необходимо определить диск типаencrypted и выбрать диск, на котором будут сохраняться данные. Диск encrypted шифрует все записываемые файлы на лету, а при чтении файлов с диска encrypted автоматически расшифровывает их. Таким образом, с диском encrypted можно работать как с обычным диском.
Пример конфигурации диска:
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 в зашифрованном виде.
Обязательные параметры
Необязательные параметры
Пример конфигурации диска:
Использование локального кэша
Начиная с версии 22.3 в конфигурации хранилища можно настроить локальный кэш для дисков. Для версий 22.3–22.7 кэш поддерживается только для дисков типаs3. Для версий >= 22.8 кэш поддерживается для любых типов дисков: S3, Azure, Local, Encrypted и т. д.
Для версий >= 23.5 кэш поддерживается только для удалённых типов дисков: S3, Azure, HDFS (не поддерживается).
Для вытеснения кэш использует политику, заданную настройкой cache_policy (по умолчанию SLRU); её значение можно посмотреть в system.filesystem_cache_settings. Полный список настроек диска кэша приведён в system.filesystem_cache_settings.
Пример конфигурации для версий 22.8 и выше:
system.filesystem_cache_settings.
Примечание: Для значений размера поддерживаются единицы измеренияki,Mi,Giи т. д. (например,10Gi).
Настройки запросов/профилей для File Cache
Системные таблицы файлового кэша
Команды управления кэшем
Эта команда поддерживается только без указания<cache_name>
Выводит список файловых кэшей, настроенных на сервере.
(В версиях 22.8 и ниже команда называется SHOW CACHES)
Query
Response
SHOW FILESYSTEM CACHES. (Для версий ниже
или равных 22.8 команда называется DESCRIBE CACHE)
Query
Response
Использование статического 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/ - используется кэш в локальном хранилище
ATTACH TABLE указанный UUID совпадает с именем каталога с данными, а конечная точка — это URL исходного содержимого GitHub.
Обязательные параметры
Необязательные параметры
Бэкенд объектного хранилищаweb использует только параметр endpoint. Дополнительные необязательные параметры, относящиеся только к web, отсутствуют; общие параметры диска по-прежнему применяются.
Если запрос завершается исключением 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_tries, чтобы ограничить количество попыток HTTP-чтения, включая первоначальную попытку. Используйте http_retry_initial_backoff_ms и http_retry_max_backoff_ms, чтобы настроить начальную и максимальную задержки между повторными попытками.
Репликация без копирования (не готово к использованию в production)
Репликация без копирования возможна, но не рекомендуется для дисковS3 и HDFS (не поддерживается). Репликация без копирования означает, что если данные удалённо хранятся на нескольких машинах и их нужно синхронизировать, то реплицируются только метаданные (пути к частям данных), а не сами данные.
Репликация без копирования не готова к использованию в productionВ ClickHouse версии 22.8 и выше репликация без копирования по умолчанию отключена. Эта возможность не рекомендуется для использования в production.