Перейти к основному содержимому
Перейти к основному содержимому

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

равна конфигурации (с 24.1):

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

равна

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

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

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

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

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

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

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

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

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

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

примечание

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

Комбинация конфигурации на основе конфигурации и конфигурации, определённой с помощью SQL, также возможна:

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

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

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

  • endpoint — URL конечной точки S3 в path или виртуальном хостинге стилях. URL конечной точки должен содержать ведро и корневой путь для хранения данных.
  • access_key_id — ID ключа доступа S3.
  • secret_access_key — секретный ключ доступа S3.

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

  • region — название региона S3.
  • support_batch_delete — Этот параметр контролирует проверку на поддержку пакетных удалений. Установите это значение в false, когда используете Google Cloud Storage (GCS), так как GCS не поддерживает пакетные удаления, и предотвращение проверок предотвратит сообщение об ошибке в логах.
  • use_environment_credentials — Читает AWS учетные данные из переменных окружения AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY и AWS_SESSION_TOKEN, если они существуют. Значение по умолчанию false.
  • use_insecure_imds_request — Если установлено в true, клиент S3 будет использовать небезопасный запрос IMDS при получении учетных данных из метаданных Amazon EC2. Значение по умолчанию false.
  • expiration_window_seconds — Период времени для проверки, истекли ли учетные данные на основе срока действия. Необязательный, значение по умолчанию 120.
  • proxy — Конфигурация прокси для конечной точки S3. Каждый элемент uri внутри блока proxy должен содержать URL прокси.
  • connect_timeout_ms — Тайм-аут подключения сокета в миллисекундах. Значение по умолчанию 10 секунд.
  • request_timeout_ms — Тайм-аут запроса в миллисекундах. Значение по умолчанию 5 секунд.
  • retry_attempts — Количество попыток повторного запроса в случае неудачного запроса. Значение по умолчанию 10.
  • single_read_retries — Количество попыток повторного запроса в случае разрыва соединения во время чтения. Значение по умолчанию 4.
  • min_bytes_for_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 - Если указано вместе с server_side_encryption_kms_key_id, будет установлен указанный заголовок контекста шифрования для SSE-KMS. Необязательный.
  • server_side_encryption_kms_bucket_key_enabled - Если указано вместе с server_side_encryption_kms_key_id, будет установлен заголовок для включения ключей ведра S3 для SSE-KMS. Необязательный, может быть true или false, по умолчанию ничего не указывается (соответствует настройке на уровне ведра).
  • s3_max_put_rps — Максимальная скорость PUT-запросов в секунду перед ограничением. Значение по умолчанию 0 (без ограничений).
  • s3_max_put_burst — Максимальное количество запросов, которые могут быть выданы одновременно перед достижением ограничения запросов в секунду. По умолчанию (0) соответствует s3_max_put_rps.
  • s3_max_get_rps — Максимальная скорость GET-запросов в секунду перед ограничением. Значение по умолчанию 0 (без ограничений).
  • s3_max_get_burst — Максимальное количество запросов, которые могут быть выданы одновременно перед достижением ограничения запросов в секунду. По умолчанию (0) соответствует s3_max_get_rps.
  • read_resource — Имя ресурса, которое будет использоваться для планирования запросов на чтение к этому диску. Значение по умолчанию — пустая строка (IO-планирование не включено для этого диска).
  • write_resource — Имя ресурса, которое будет использоваться для планирования запросов на запись к этому диску. Значение по умолчанию — пустая строка (IO-планирование не включено для этого диска).
  • key_template — Определите формат, с помощью которого генерируются ключи объектов. По умолчанию Clickhouse берет root path из параметра endpoint и добавляет случайный суффикс. Этот суффикс — это директория с 3 случайными символами и имя файла из 29 случайных символов. С помощью этой опции вы имеете полный контроль над тем, как генерируются ключи объектов. Некоторые сценарии использования требуют наличия случайных символов в префиксе или в середине ключа объекта. Например: [a-z]{3}-prefix-random/constant-part/random-middle-[a-z]{3}/random-suffix-[a-z]{29}. Значение обрабатывается с использованием re2. Поддерживается только некоторый подмножество синтаксиса. Проверьте, поддерживается ли ваш предпочтительный формат, прежде чем использовать эту опцию. Диск не инициализируется, если clickhouse не может сгенерировать ключ по значению key_template. Это требует включенного флага функции storage_metadata_write_full_object_key. Он запрещает объявление root path в параметре endpoint. Требуется определение опции key_compatibility_prefix.
  • key_compatibility_prefix — Эта опция обязательна, когда используется опция key_template. Чтобы иметь возможность читать ключи объектов, которые были сохранены в метафайловых файлах с версией метаданных ниже VERSION_FULL_OBJECT_KEY, предыдущий root path из параметра endpoint должен быть установлен здесь.
примечание

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

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

В 22.10 был введен новый тип диска s3_plain, который предоставляет хранилище с записыванием только один раз. Параметры конфигурации такие же, как для типа диска s3. В отличие от типа диска s3, он хранит данные как есть, например, вместо случайно сгенерированных имен блобов, он использует обычные имена файлов (так же, как 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. Мутации и репликация таблиц не поддерживаются.

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

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

равно

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

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

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

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

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

  • 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, в учетной записи хранилища создается новый контейнер container_name, если установлено в true, диск подключается напрямую к контейнеру, а если не установлено, диск подключается к учетной записи, проверяет, существует ли контейнер container_name, и создает его, если он ещё не существует.

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

  • connection_string - Для аутентификации с использованием строки подключения.
  • account_name и account_key - Для аутентификации с использованием общего ключа.

Параметры ограничения (в основном для внутреннего использования):

  • 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 — Имя ресурса, которое будет использоваться для планирования запросов на чтение к этому диску. Значение по умолчанию — пустая строка (IO-планирование не включено для этого диска).
  • write_resource — Имя ресурса, которое будет использоваться для планирования запросов на запись к этому диску. Значение по умолчанию — пустая строка (IO-планирование не включено для этого диска).
  • metadata_keep_free_space_bytes - количество свободного места на диске для метаданных, которое нужно зарезервировать.

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

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

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

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

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

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

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

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

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

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

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

Например, когда 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 — encrypted. В противном случае зашифрованный диск не создается.
  • disk — Тип диска для хранения данных.
  • key — Ключ для шифрования и дешифрования. Тип: Uint64. Вы можете использовать параметр key_hex для кодирования ключа в шестнадцатеричной форме. Вы можете указать несколько ключей, используя атрибут id (см. пример ниже).

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

  • path — Путь к месту на диске, где будут сохранены данные. Если не указано, данные будут сохранены в корневом каталоге.
  • current_key_id — Ключ, используемый для шифрования. Все указанные ключи могут быть использованы для дешифрования, и вы всегда можете переключаться на другой ключ, сохраняя доступ к ранее зашифрованным данным.
  • algorithm — Алгоритм для шифрования. Возможные значения: AES_128_CTR, AES_192_CTR или AES_256_CTR. Значение по умолчанию: AES_128_CTR. Длина ключа зависит от алгоритма: AES_128_CTR — 16 байт, AES_192_CTR — 24 байта, AES_256_CTR — 32 байта.

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

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

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

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

Пример конфигурации для версий, предшествующих 22.8:

Настройки конфигурации диска кэша:

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

  • path - путь к каталогу с кэшем. По умолчанию: None, эта настройка обязательна.

  • max_size - максимальный размер кэша в байтах или в удобочитаемом формате, например, ki, Mi, Gi и т. д.. Пример: 10Gi (такой формат работает, начиная с версии 22.10). Когда лимит будет достигнут, файлы кэша удаляются в соответствии с политикой выброса кэша. По умолчанию: None, эта настройка обязательна.

  • cache_on_write_operations - возможность включить кэш write-through (кэширование данных при любых операциях записи: запросы INSERT, фоновое слияние). По умолчанию: false. Кэш write-through можно отключить для конкретного запроса с помощью настройки enable_filesystem_cache_on_write_operations (данные кэшируются только при включении как настроек кэша, так и соответствующей настройки запроса).

  • enable_filesystem_query_cache_limit - возможность ограничить размер кэша, который загружается в рамках каждого запроса (зависит от пользовательской настройки max_query_cache_size). По умолчанию: false.

  • enable_cache_hits_threshold - число, определяющее, сколько раз некоторые данные должны быть прочитаны, прежде чем они будут закэшированы. По умолчанию: false. Этот порог может быть задействован с помощью cache_hits_threshold. По умолчанию: 0, например, данные кэшируются с первой попытки их прочитать.

  • enable_bypass_cache_with_threshold - позволяет полностью пропустить кэш, если запрашиваемый диапазон чтения превышает порог. По умолчанию: false. Этот порог может быть определен с помощью bypass_cache_threashold. По умолчанию: 268435456 (256Mi).

  • max_file_segment_size - максимальный размер одного файла кэша в байтах или в удобочитаемом формате (ki, Mi, Gi и т. д., пример 10Gi). По умолчанию: 8388608 (8Mi).

  • max_elements - лимит на количество файлов кэша. По умолчанию: 10000000.

  • load_metadata_threads - количество потоков, используемых для загрузки метаданных кэша в момент запуска. По умолчанию: 16.

Настройки запросов/профилей кэша:

Некоторые из этих настроек отключат функции кэша для запроса/профиля, которые включены по умолчанию или в настройках конфигурации диска. Например, вы можете включить кэш в конфигурации диска и отключить его для конкретного запроса/профиля, установив enable_filesystem_cache в false. Также установка cache_on_write_operations в true в конфигурации диска означает, что кэш "write-through" включен. Но если вам нужно отключить эту общую настройку для конкретных запросов, установка enable_filesystem_cache_on_write_operations в false означает, что кэширование операций записи будет отключено для конкретного запроса/профиля.

  • enable_filesystem_cache - позволяет отключить кэш для запроса, даже если политика хранения была настроена с типом диска cache. По умолчанию: true.

  • read_from_filesystem_cache_if_exists_otherwise_bypass_cache - позволяет использовать кэш в запросе только в случае его существования, в противном случае данные запроса не будут записаны в локальное хранилище кэша. По умолчанию: false.

  • enable_filesystem_cache_on_write_operations - включает кэш write-through. Эта настройка работает только если настройка cache_on_write_operations в конфигурации кэша активирована. По умолчанию: false. Значение по умолчанию в облаке: true.

  • enable_filesystem_cache_log - включает логирование в таблицу system.filesystem_cache_log. Предоставляет детальное представление о использовании кэша для каждого запроса. Может быть включено для определенных запросов или активировано в профиле. По умолчанию: false.

  • max_query_cache_size - лимит для размера кэша, который может быть записан в локальное хранилище кэша. Требуется включенная enable_filesystem_query_cache_limit в конфигурации кэша. По умолчанию: false.

  • skip_download_if_exceeds_query_cache - позволяет изменить поведение настройки max_query_cache_size. По умолчанию: true. Если эта настройка включена и лимит загрузки кэша во время запроса достигнут, больше кэша не будет загружено в хранилище кэша. Если эта настройка отключена и лимит загрузки кэша во время запроса достигнут, кэш все равно будет записываться за счет вытеснения ранее загруженных (в рамках текущего запроса) данных. Например, второе поведение позволяет сохранить поведение "последнего использованного".

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

Системные таблицы кэша:

  • system.filesystem_cache - системные таблицы, которые показывают текущее состояние кэша.

  • system.filesystem_cache_log - системная таблица, которая показывает детальное использование кэша по запросу. Требуется, чтобы настройка enable_filesystem_cache_log была установлена в true.

Команды кэша:

  • SYSTEM DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER) -- ON CLUSTER поддерживается только если <cache_name> не указан

  • SHOW FILESYSTEM CACHES -- показать список файловых систем кэша, которые были настроены на сервере. (Для версий <= 22.8 команда называется SHOW CACHES)

Результат:

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

Текущие метрики кэша:

  • FilesystemCacheSize

  • FilesystemCacheElements

Асинхронные метрики кэша:

  • FilesystemCacheBytes

  • FilesystemCacheFiles

События профиля кэша:

  • CachedReadBufferReadFromSourceBytes, CachedReadBufferReadFromCacheBytes,

  • CachedReadBufferReadFromSourceMicroseconds, CachedReadBufferReadFromCacheMicroseconds

  • CachedReadBufferCacheWriteBytes, CachedReadBufferCacheWriteMicroseconds

  • CachedWriteBufferCacheWriteBytes, CachedWriteBufferCacheWriteMicroseconds

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

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

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

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

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

подсказка

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

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

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

А затем выполните этот запрос:

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

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

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

  • min_bytes_for_seek — минимальное количество байт, для использования операции поиска вместо последовательного чтения. Значение по умолчанию: 1 Мб.
  • 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-чтения.

Репликация без копирования (не готово к производству)​

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

Репликация без копирования не готова к производству

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