Skip to main content
Skip to main content
Edit this page

Источники внешних словарей

Внешний словарь можно подключить из множества источников.

Общий вид XML-конфигурации:

Аналогичный DDL-запрос:

Источник настраивается в разделе source.

Для типов источников Локальный файл, Исполняемый файл, HTTP(s), ClickHouse доступны дополнительные настройки:

или

Типы источников (source_type):

Локальный файл​

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

или

Поля настройки:

  • path — абсолютный путь к файлу.
  • format — формат файла. Поддерживаются все форматы, описанные в разделе Форматы.

Если словарь с источником FILE создается с помощью DDL-команды (CREATE DICTIONARY ...), источник словаря должен быть расположен в каталоге user_files. Иначе пользователи базы данных будут иметь доступ к произвольному файлу на узле ClickHouse.

Смотрите также

Исполняемый файл​

Работа с исполняемым файлом зависит от размещения словаря в памяти. Если тип размещения словаря cache и complex_key_cache, то ClickHouse запрашивает необходимые ключи, отправляя запрос в STDIN исполняемого файла.

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

Поля настройки:

  • command — абсолютный путь к исполняемому файлу или имя файла (если каталог программы прописан в PATH).
  • format — формат файла. Поддерживаются все форматы, описанные в разделе Форматы.
  • implicit_key — исходный исполняемый файл может возвращать только значения, а соответствие запрошенным ключам определено неявно — порядком строк в результате. Значение по умолчанию: false. Необязательный параметр.

Этот источник словаря может быть настроен только с помощью XML-конфигурации. Создание словарей с исполняемым источником с помощью DDL запрещено. Иначе пользователь сможет выполнить произвольный бинарный файл на сервере ClickHouse.

Исполняемый пул​

Исполняемый пул позволяет загружать данные из пула процессов. Этот источник не работает со словарями, которые требуют загрузки всех данных из источника. Исполняемый пул работает словарями, которые размещаются следующими способами: cache, complex_key_cache, ssd_cache, complex_key_ssd_cache, direct, complex_key_direct.

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

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

Поля настройки:

  • command — абсолютный путь к файлу или имя файла (если каталог программы записан в PATH).
  • format — формат файла. Поддерживаются все форматы, описанные в “Форматы”.
  • pool_size — размер пула. Если в поле pool_size указан 0, то размер пула не ограничен.
  • command_termination_timeout — скрипт исполняемого пула должен включать основной цикл чтения-записи. После уничтожения словаря канал закрывается. При этом исполняемый файл имеет command_termination_timeout секунд для завершения работы, прежде чем ClickHouse пошлет сигнал SIGTERM дочернему процессу. Указывается в секундах. Значение по умолчанию: 10. Необязательный параметр.
  • max_command_execution_time — максимальное количество времени для исполняемого скрипта на обработку блока данных. Указывается в секундах. Значение по умолчанию: 10. Необязательный параметр.
  • implicit_key — исходный исполняемый файл может возвращать только значения, а соответствие запрошенным ключам определено неявно — порядком строк в результате. Значение по умолчанию: false. Необязательный параметр.

Этот источник словаря может быть настроен только с помощью XML-конфигурации. Создание словарей с исполняемым источником с помощью DDL запрещено. Иначе пользователь сможет выполнить произвольный бинарный файл на сервере ClickHouse.

HTTP(s)​

Работа с HTTP(s) сервером зависит от размещения словаря в памяти. Если тип размещения словаря cache и complex_key_cache, то ClickHouse запрашивает необходимые ключи, отправляя запрос методом POST.

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

или

Чтобы ClickHouse смог обратиться к HTTPS-ресурсу, необходимо настроить openSSL в конфигурации сервера.

Поля настройки:

  • url — URL источника.
  • format — формат файла. Поддерживаются все форматы, описанные в разделе «Форматы».
  • credentials – базовая HTTP-аутентификация. Необязательный параметр.
  • user – имя пользователя, необходимое для аутентификации.
  • password – пароль, необходимый для аутентификации.
  • headers – все пользовательские записи HTTP-заголовков, используемые для HTTP-запроса. Необязательный параметр.
  • header – одна запись HTTP-заголовка.
  • name – идентифицирующее имя, используемое для отправки заголовка запроса.
  • value – значение, заданное для конкретного идентифицирующего имени.

При создании словаря с помощью DDL-команды (CREATE DICTIONARY ...) удаленные хосты для HTTP-словарей проверяются в разделе remote_url_allow_hosts из конфигурации сервера. Иначе пользователи базы данных будут иметь доступ к произвольному HTTP-серверу.

Выявленная уязвимость в функционировании ODBC словарей​

Внимание

При соединении с базой данных через ODBC можно заменить параметр соединения Servername. В этом случае, значения USERNAME и PASSWORD из odbc.ini отправляются на удаленный сервер и могут быть скомпрометированы.

Пример небезопасного использования

Сконфигурируем unixODBC для работы с PostgreSQL. Содержимое /etc/odbc.ini:

Если выполнить запрос вида:

то ODBC драйвер отправит значения USERNAME и PASSWORD из odbc.ini на some-server.com.

Пример подключения PostgreSQL​

ОС Ubuntu.

Установка unixODBC и ODBC-драйвера для PostgreSQL: :

Настройка /etc/odbc.ini (или ~/.odbc.ini):

Конфигурация словаря в ClickHouse:

или

Может понадобиться в odbc.ini указать полный путь до библиотеки с драйвером DRIVER=/usr/local/lib/psqlodbcw.so.

Пример подключения MS SQL Server​

ОС Ubuntu.

Установка драйвера:

Настройка драйвера:

Примечание:

  • чтобы определить самую раннюю версию TDS, которая поддерживается определенной версией SQL Server, обратитесь к документации продукта или посмотрите на MS-TDS Product Behavior

Настройка словаря в ClickHouse:

или

СУБД​

ODBC​

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

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

или

Поля настройки:

  • db — имя базы данных. Не указывать, если имя базы задано в параметрах. <connection_string>.
  • table — имя таблицы и схемы, если она есть.
  • connection_string — строка соединения.
  • invalidate_query — запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе Обновление словарей.
  • query – пользовательский запрос. Необязательный параметр.
Примечание

Поля table и query не могут быть использованы вместе. Также обязательно должен быть один из источников данных: table или query.

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

Если у вас есть проблемы с кодировками при использовании Oracle, ознакомьтесь с соответствующим разделом FAQ.

MySQL​

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

или

Поля настройки:

  • port — порт сервера MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри <replica>).

  • user — имя пользователя MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри <replica>).

  • password — пароль пользователя MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри <replica>).

  • replica — блок конфигурации реплики. Блоков может быть несколько.

    • replica/host — хост MySQL.
    • replica/priority — приоритет реплики. При попытке соединения ClickHouse обходит реплики в соответствии с приоритетом. Чем меньше цифра, тем выше приоритет.

  • db — имя базы данных.

  • table — имя таблицы.

  • where — условие выбора. Синтаксис условия совпадает с синтаксисом секции WHERE в MySQL, например, id > 10 AND id < 20. Необязательный параметр.

  • invalidate_query — запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе Обновление словарей.

  • fail_on_connection_loss – параметр конфигурации, контролирующий поведение сервера при потере соединения. Если значение true, то исключение генерируется сразу же, если соединение между клиентом и сервером было потеряно. Если значение false, то сервер повторно попытается выполнить запрос три раза прежде чем сгенерировать исключение. Имейте в виду, что повторные попытки могут увеличить время выполнения запроса. Значение по умолчанию: false.

  • query – пользовательский запрос. Необязательный параметр.

Примечание

Поля table или where не могут быть использованы вместе с полем query. Также обязательно должен быть один из источников данных: table или query. Явный параметр secure отсутствует. Автоматически поддержана работа в обоих случаях: когда установка SSL-соединения необходима и когда нет.

MySQL можно подключить на локальном хосте через сокеты, для этого необходимо задать host и socket.

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

или

ClickHouse​

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

или

Поля настройки:

  • host — хост ClickHouse. Если host локальный, то запрос выполняется без сетевого взаимодействия. Чтобы повысить отказоустойчивость решения, можно создать таблицу типа Distributed и прописать её в дальнейших настройках.
  • port — порт сервера ClickHouse.
  • user — имя пользователя ClickHouse.
  • password — пароль пользователя ClickHouse.
  • db — имя базы данных.
  • table — имя таблицы.
  • where — условие выбора. Может отсутствовать.
  • invalidate_query — запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе Обновление словарей.
  • secure - флаг, разрешающий или не разрешающий защищённое SSL-соединение.
  • query – пользовательский запрос. Необязательный параметр.
Примечание

Поля table или where не могут быть использованы вместе с полем query. Также обязательно должен быть один из источников данных: table или query.

MongoDB​

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

или

Поля настройки:

  • host — хост MongoDB.
  • port — порт сервера MongoDB.
  • user — имя пользователя MongoDB.
  • password — пароль пользователя MongoDB.
  • db — имя базы данных.
  • collection — имя коллекции.

Redis​

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

или

Поля настройки:

  • host – хост Redis.
  • port – порт сервера Redis.
  • storage_type – способ хранения ключей. Необходимо использовать simple для источников с одним столбцом ключей, hash_map – для источников с двумя столбцами ключей. Источники с более, чем двумя столбцами ключей, не поддерживаются. Может отсутствовать, значение по умолчанию simple.
  • db_index – номер базы данных. Может отсутствовать, значение по умолчанию 0.

Cassandra​

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

Поля настройки:

  • host – имя хоста с установленной Cassandra или разделенный через запятую список хостов.
  • port – порт на серверах Cassandra. Если не указан, используется значение по умолчанию: 9042.
  • user – имя пользователя для соединения с Cassandra.
  • password – пароль для соединения с Cassandra.
  • keyspace – имя keyspace (база данных).
  • column_family – имя семейства столбцов (таблица).
  • allow_filtering – флаг, разрешающий или не разрешающий потенциально дорогостоящие условия на кластеризации ключевых столбцов. Значение по умолчанию: 1.
  • partition_key_prefix – количество партиций ключевых столбцов в первичном ключе таблицы Cassandra. Необходимо для составления ключей словаря. Порядок ключевых столбцов в определении словаря должен быть таким же, как в Cassandra. Значение по умолчанию: 1 (первый ключевой столбец - это ключ партицирования, остальные ключевые столбцы - ключи кластеризации).
  • consistency – уровень консистентности. Возможные значения: One, Two, Three, All, EachQuorum, Quorum, LocalQuorum, LocalOne, Serial, LocalSerial. Значение по умолчанию: One.
  • where – опциональный критерий выборки.
  • max_threads – максимальное количество тредов для загрузки данных из нескольких партиций в словарь.
  • query – пользовательский запрос. Необязательный параметр.
Примечание

Поля column_family или where не могут быть использованы вместе с полем query. Также обязательно должен быть один из источников данных: column_family или query.

PostgreSQL​

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

или

Поля настройки:

  • host – хост для соединения с PostgreSQL. Вы можете указать его для всех реплик или задать индивидуально для каждой релпики (внутри <replica>).
  • port – порт для соединения с PostgreSQL. Вы можете указать его для всех реплик или задать индивидуально для каждой релпики (внутри <replica>).
  • user – имя пользователя для соединения с PostgreSQL. Вы можете указать его для всех реплик или задать индивидуально для каждой релпики (внутри <replica>).
  • password – пароль для пользователя PostgreSQL.
  • replica – раздел конфигурации реплик. Может быть несколько.
    • replica/host – хост PostgreSQL.
    • replica/port – порт PostgreSQL .
    • replica/priority – приоритет реплики. Во время попытки соединения ClickHouse будет перебирать реплики в порядке приоритета. Меньшее значение означает более высокий приоритет.
  • db – имя базы данных.
  • table – имя таблицы.
  • where – условие выборки. Синтаксис для условий такой же, как для выражения WHERE в PostgreSQL. Например, id > 10 AND id < 20. Необязательный параметр.
  • invalidate_query – запрос для проверки условия загрузки словаря. Необязательный параметр. Более подробную информацию смотрите в разделе обновление словарей.
  • query – пользовательский запрос. Необязательный параметр.
Примечание

Поля table или where не могут быть использованы вместе с полем query. Также обязательно должен быть один из источников данных: table или query.