Если вы открыли эту дверь статью, то наверняка, вы уже имели дело с ClickHouse и можно упустить интересные подробности об его удобстве и скорости, а перейти сразу к делу – собственно, к тому, как создавать словари и работать с ними в ClickHouse. Словарь — это отображение данных в виде key → value. Появление словарей очень упростило использование сторонних источников данных в ClickHouse, автоматизировав все необходимые ETL-процессы для доставки данных в пригодную для запросов форму.
Из преимуществ использования словарей в ClickHouse можно выделить несколько пунктов: Подключить собственные словари можно из различных источников данных: локального текстового/исполняемого файла, HTTP(s) ресурса, другой СУБД и т.д. Конфигурация этих словарей может находиться в одном или нескольких xml-файлах, путь к которым указывается в параметре dictionaries_config в конфигурационном файле ClickHouse. Словари могут загружаться при старте сервера или при первом использовании, в зависимости от настройки dictionaries_lazy_load. Также обновление словарей (кроме загрузки при первом использовании) не блокирует запросы — во время обновления запросы используют старую версию словарей. Для просмотра информации о словарях, сконфигурированных на сервере, есть таблица system.dictionaries, в ней можно найти: На данный момент есть способ конфигурации словарей через xml файлы и через DDL-запросы. Вы можете использовать любой удобный для вас способ, но самый простой способ создавать и контролировать словари — это используя DDL-запросы. Общий внешний вид конфигурации xml словаря: Если вы выбрали создание словарей через DDL-запросы, то не задавайте конфигурацию словаря в конфигурации сервера. Пример конфигурации словаря: Поля настройки: Пример создания словаря через DDL-запрос: Внешние словари можно подключить через множество разных источников. Основные из них — это: Самые распространенные способы подключения словарей — через локальный файл либо СУБД, поэтому именно их мы и рассмотрим далее. Пример подключения словаря через локальный файл имеет следующий вид: Поля настройки: Или через DDL-запрос: Рассмотрим подключение СУБД на примере MySQL базы данных. Пример настройки: Или через DDL-запрос: Существует много способов хранения словарей в памяти ClickHouse: Самые популярные из них всего 3, поскольку скорость обработки словарей при этом максимальна, — это flat, hashed и complex_key_hashed. Давайте рассмотрим примеры этих способов хранения. Словари полностью хранятся в оперативной памяти в виде плоских массивов, при этом объем занятой памяти пропорционален размеру самого большого по размеру ключа словаря. Ключ словаря должен иметь тип UInt64 и не должен быть длиннее 500 000, иначе ClickHouse бросит исключение и не создаст словарь. Этот метод хранения обеспечивает максимальную производительность среди всех доступных способов хранения словаря. Пример конфигурации: или Словарь полностью хранится в оперативной памяти в виде хэш-таблиц и может содержать произвольное количество элементов с произвольными идентификаторами. На практике, количество ключей может достигать десятков миллионов элементов. Пример конфигурации: или Этот тип размещения предназначен для использования с составными ключами. Аналогичен hashed способу. Пример конфигурации: или Секция <structure> описывает ключ словаря и поля, доступные для запросов. Описание в формате XML: Поля настройки: ClickHouse поддерживает следующие виды ключей: Числовой ключ Тип: UInt64. Пример конфигурации: или Составной ключ Ключом может быть кортеж (tuple) из полей произвольных типов. В этом случае layout должен быть complex_key_hashed или complex_key_cache. Структура ключа задается в элементе <key>. Поля ключа задаются в том же формате, что и атрибуты словаря. Пример: или или Один из популярных кейсов использования словарей в ClickHouse — это агрегация данных по странам на основе IP (v4) адресов.  Представим, что перед нами задача: из данных колонки с ip String получить в запросе колонку с country String. Для решения данной задачи мы возьмем довольно популярные базы GeoIP2 от MaxMind. MaxMind предоставляет со своими .mmdb базами API для большинства популярных языков программирования. В ClickHouse нет возможности загрузить в словарь формат .mmdb, но нам это и не понадобится – MaxMind позволяет загрузить свои базы в виде нескольких CSV, чем мы и воспользуемся. Для того чтобы связать IP со страной, нам необходимо скачать следующие файлы: Далее, заведем соответствующие словари с помощью DDL: В словаре geoip_country_blocks_ipv4 мы должны указать два основных атрибута: Остальные атрибуты – в соответствии с заголовком в CSV. Чтобы ClickHouse мог корректно сопоставить префикс сети и ID, нам необходимо использовать тип размещения ip_trie. Для получения значений из такого словаря необходимо будет передавать IP адрес в числовом представлении. Теперь geoip_country_locations_en: Нам нужно связать ID и название страны. В заголовках GeoIP2-Country-Locations-en.csv можно найти следующие атрибуты: В качестве типа размещения указываем оптимизированный hashed. В каждом из словарей необходимо указать пути к соответствующим CSV файлам. Теперь, имея таблицу: Можем посчитать количество уникальных значений по странам. Один из способов это сделать – использовать функции для работы со словарями dictGet*: Ответ: Разберем данный запрос: Таким образом возможно сопоставлять не только названия стран. В тех же GeoIP2 базах есть много другой полезной информации, не бойтесь пробовать :) На этом первичное знакомство со словарями закончено. Надеюсь, что данная информация расширит ваши возможности использования ClickHouse и поможет правильно настраивать внешние источники данных.