Druid коннектор#

Примечание

Ниже приведена оригинальная документация Trino. Скоро мы ее переведем на русский язык и дополним полезными примерами.

The Druid connector allows querying an Apache Druid database from Trino.

Requirements#

To connect to Druid, you need:

  • Druid version 0.18.0 or higher.

  • Network access from the Trino coordinator and workers to your Druid broker. Port 8082 is the default port.

Configuration#

Create a catalog properties file that specifies the Druid connector by setting the connector.name to druid and configuring the connection-url with the JDBC string to connect to Druid.

For example, to access a database as example, create the file etc/catalog/example.properties. Replace BROKER:8082 with the correct host and port of your Druid broker.

connector.name=druid
connection-url=jdbc:avatica:remote:url=http://BROKER:8082/druid/v2/sql/avatica/

You can add authentication details to connect to a Druid deployment that is secured by basic authentication by updating the URL and adding credentials:

connection-url=jdbc:avatica:remote:url=http://BROKER:port/druid/v2/sql/avatica/;authentication=BASIC
connection-user=root
connection-password=secret

Now you can access your Druid database in Trino with the example catalog name from the properties file.

The connection-user and connection-password are typically required and determine the user credentials for the connection, often a service user. You can use secrets to avoid actual values in the catalog properties files.

Аутентификация в источнике данных#

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

  • INLINE - в файле конфигурации каталога (в том числе, используя секреты, чтобы не хранить значения в открытом виде).

  • FILE - в отдельном properties файле.

  • KEYSTORE - в зашифрованном keystore файле.

  • Из extra credentials клиента CedrusData.

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

Название

Описание

credential-provider.type

Тип credential provider. Допустимые значения: INLINE (значение по умолчанию), FILE или KEYSTORE.

connection-user

Имя пользователя для подключения к источнику. Используется при credential-provider.type=INLINE.

connection-password

Пароль для подключения к источнику. Используется при credential-provider.type=INLINE.

connection-credential-file

Путь к properties файлу, содержащему параметры connection-user and connection-password. Используется при credential-provider.type=FILE.

keystore-file-path

Путь к keystore файлу, из которого следует прочитать имя пользователя и пароль. Используется при credential-provider.type=KEYSTORE.

keystore-type

Тип keystore файла. Например, JKS или PEM.

keystore-password

Пароль к keystore файлу.

keystore-user-credential-name

Имя keystore entity, содержащей имя пользователя для подключения к источнику.

keystore-user-credential-password

Пароль к keystore entity, содержащей имя пользователя для подключения к источнику

keystore-password-credential-name

Имя keystore entity, содержащей пароль для подключения к источнику.

keystore-password-credential-password

Пароль к keystore entity, содержащей пароль для подключения к источнику.

user-credential-name

Имя параметра extra credentials, значение которого следует использовать в качестве имени пользователя. См. extraCredentials в разделе Параметры подключения.

password-credential-name

Имя параметра extra credentials, значение которого следует использовать в качестве пароля. См. extraCredentials в разделе Параметры подключения.

Аутентификация в источнике данных от имени текущего пользователя#

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

Для использования данного типа аутентификации узел должен использовать PASSWORD аутентификацию с включенным параметром cedrusdata.http-server.authentication.password.populate-extra-credentials. Убедитесь, что файл config.properties содержит следующие параметры:

http-server.authentication.type=PASSWORD
cedrusdata.http-server.authentication.password.populate-extra-credentials=true

В файле конфигурации коннектора добавьте два параметра:

user-credential-name=cedrusdata.username
password-credential-name=cedrusdata.password

Теперь коннектор будет использовать имя и пароль текущего пользователя для аутентификации в источнике.

При использовании аутентификации от имени текущего пользователя CedrusData другие параметры аутентификации коннектора будут проигнорированы.

Общие параметры конфигурации#

Название

Описание

Значение по умолчанию

case-insensitive-name-matching

Включить поддержку case insensitive идентификаторов.

false

case-insensitive-name-matching.cache-ttl

Время жизни закэшированных метаданных о case insensitive идентификаторах. Значение имеет тип {ref{prop-type-duration.

1m

case-insensitive-name-matching.config-file

Путь к файлу конфигурации в формате JSON, который позволяет разрешать конфликты имен между case insensitive схемами и таблицами.

null

case-insensitive-name-matching.config-file.refresh-period

Частота проверки обновлений файла case-insensitive-name-matching.config-file.

0 (обновление отключено)

metadata.cache-ttl

Время жизни закэшированных метаданных (дескрипторы таблицы и колонок, статистики). Положительное значение включает кэширование. Значение имеет тип duration.

0 (кэширование отключено)

metadata.schemas.cache-ttl

Время жизни закэшированных имен схем. Положительное значение включает кэширование. Допустимо только, если параметр metadata.cache-ttl имеет положительное значение. Значение имеет тип {ref{prop-type-duration.

0 (кэширование отключено)

metadata.tables.cache-ttl

Время жизни закэшированных имен таблиц. Положительное значение включает кэширование. Допустимо только, если параметр metadata.cache-ttl имеет положительное значение. Значение имеет тип {ref{prop-type-duration.

0 (кэширование отключено)

metadata.cache-missing

Кэшировать ли информацию о том, что для используемых таблиц и колонок отсутствуют статистики. Включение данного параметра может ускорить планирование некоторых запросов. Однако, если информация об отсутствии статистик для конкретного объекта СУБД закэширована, но статистики стали доступны позднее (например, была запущена команда ANALYZE), CedrusData не сможет использовать статистики, пока не истечет время жизни закэшированной записи в соответствии с metadata.cache-ttl.

false

metadata.cache-maximum-size

Максимальное количество объектов, хранящихся в metadata cache.

10000

write.batch-size

Максимальное количество команд в batch операциях записи данных. Изменение данного параметра не рекомендовано, так как оно может негативно сказаться на производительности.

1000

dynamic-filtering.enabled

Использовать ли динамические фильтры при работе с JDBC источником.

true

dynamic-filtering.wait-timeout

Максимальное время ожидания готовности динамических фильтров с build стороны оператора join перед запуском JDBC запроса к источнику. Увеличение таймаута может позволить CedrusData выполнить запрос к источнику с более селективными фильтрами, но в то же время может увеличить latency некоторых запросов. Значение имеет тип duration.

20s

Добавление комментариев к SQL-запросам к источнику#

Опциональный параметр query.comment-format позволяет добавить комментарий, который будет добавлен к каждому SQL-запросу, отправляемому из CedrusData в источник. Значение параметра может содержать произвольные символы, а так же набор специальных выражений, которые будут автоматически заменены CedrusData:

  • $QUERY_ID: Уникальный идентификатор запроса.

  • $USER: Имя пользователя CedrusData, который инициировал выполнение запроса.

  • $SOURCE: Идентификатор клиентского приложения. Например, trino-cli.

  • $TRACE_TOKEN: Trace token, заданный клиентским приложением.

Вы так же можете добавить в комментарий значения переменных окружений CedrusData с помощью синтаксиса ${ENV:VARIABLE-NAME}.

Пример ниже добавляет комментарий «Query sent by Trino» к каждому запросу к SQL-источнику:

query.comment-format=Query sent by Trino

Пример SQL-запроса, отправленного к источнику:

SELECT * FROM example_table; /*Query sent by Trino.*/

Пример ниже добавляет специальные выражения в строку комментария:

query.comment-format=Query $QUERY_ID sent by user $USER from Trino.

Если пользователь Jane отправил запрос с идентификатором 20230622_180528_00000_bkizg, то источник получит SQL-запрос со следующим комментарием:

SELECT * FROM example_table; /*Query 20230622_180528_00000_bkizg sent by user Jane from Trino.*/

Примечание

Некоторые JDBC-драйвера могут автоматически удалять комментарии.

Domain compaction threshold#

CedrusData позволяет делегировать применение предикатов источнику данных (pushdown). Во многих случаях это существенно уменьшает количество записей, которые возвращает источник, и улучшает производительность. Однако, pushdown сложных предикатов (например, выражение IN со множеством значений) может негативно сказаться на производительности. При достижении порога сложности предиката, CedrusData автоматически преобразует предикат к более компактной форме. Например, предикат a IN (1, 2, ..., 100) может быть преобразован в a BETWEEN 1 AND 100. В большинстве случаев такое преобразование улучшает производительность запросов. Однако, в некоторых случаях может быть предпочтительнее передать сложный предикат в неизменном виде, так как источник данных может его обработать эффективнее, чем преобразованный предикат.

Вы можете увеличить значение порога сложности, чтобы CedrusData передавал предикат в источник без изменений. Используйте для этого параметр конфигурации каталога domain-compaction-threshold или свойство сессии domain_compaction_threshold.

Процедуры#

  • system.flush_metadata_cache()

    Очистить кэш JDBC метаданных. Команда ниже очищает кэш метаданных всех схем в каталоге example.

    USE example.example_schema;
    CALL system.flush_metadata_cache();
    

Case insensitive идентификаторы#

Когда параметр конфигурации case-insensitive-name-matching установлен в true, CedrusData может обращаться к схемам и таблицам источника, имена которых не являются lowercase. Для этого CedrusData сопоставляет lowercase название схемы или таблицы с ее реальным названием в источнике данных. Например, если таблица в источнике данных имеет название Customers, CedrusData позволяет обратиться к ней по имени customers.

В случае, если источник имеет несколько объектов, имена которых отличаются только регистром (например, Customer и customer), CedrusData не может автоматически определить, к какому объекту обращаться.

В этом случае вы можете явно задать сопоставление имен с помощью файла в JSON формате, путь к которому следует указать в параметре конфигурации каталога case-insensitive-name-matching.config-file. Например:

{
  "schemas": [
    {
      "remoteSchema": "CaseSensitiveName",
      "mapping": "case_insensitive_1"
    },
    {
      "remoteSchema": "cASEsENSITIVEnAME",
      "mapping": "case_insensitive_2"
    }],
  "tables": [
    {
      "remoteSchema": "CaseSensitiveName",
      "remoteTable": "tablex",
      "mapping": "table_1"
    },
    {
      "remoteSchema": "CaseSensitiveName",
      "remoteTable": "TABLEX",
      "mapping": "table_2"
    }]
}

В данном случае, при обращении из CedrusData к схеме case_insensitive_1, запрос будет переадресован к схеме источника CaseSensitiveName, а при обращении из CedrusData к таблице case_insensitive_1.table_1 запрос будет переадресован к таблице источника CaseSensitiveName.tablex.

По умолчанию если вы изменяете содержимое данного файла, экземпляр CedrusData должен быть перезапущен, чтобы применить изменения. Если вы хотите изменять содержимое файла без перезапуска CedrusData, вы можете установить параметр конфигурации case-insensitive-name-mapping.refresh-period, который определяет частоту повторного чтения данного файла.

case-insensitive-name-mapping.refresh-period=30s

Type mapping#

Because Trino and Druid each support types that the other does not, this connector modifies some types when reading data.

Druid type to Trino type mapping#

The connector maps Druid types to the corresponding Trino types according to the following table:

Druid type to Trino type mapping#

Druid type

Trino type

Notes

STRING

VARCHAR

FLOAT

REAL

DOUBLE

DOUBLE

LONG

BIGINT

Except for the special _time column, which is mapped to TIMESTAMP.

TIMESTAMP

TIMESTAMP

Only applicable to the special _time column.

No other data types are supported.

Druid does not have a real NULL value for any data type. By default, Druid treats NULL as the default value for a data type. For example, LONG would be 0, DOUBLE would be 0.0, STRING would be an empty string '', and so forth.

Конфигурация сопоставления типов#

Следующие параметры конфигурации могут быть использованы для изменения логики приведения типов.

Название

Описание

Значение по умолчанию

unsupported-type-handling

Как обрабатывать колонки неподдерживаемых типов: IGNORE - не обрабатывать колонку; CONVERT_TO_VARCHAR - привести значение колонки к VARCHAR неограниченной длины. Параметр сессии: unsupported_type_handling.

IGNORE

jdbc-types-mapped-to-varchar

Список типов данных источника, которые должны быть принудительно приведены к VARCHAR неограниченной длины (даже если указанный тип поддерживается коннектором).

SQL support#

The connector provides globally available and read operation statements to access data and metadata in the Druid database.

Table functions#

The connector provides specific table functions to access Druid.

query(varchar) -> table#

The query function allows you to query the underlying database directly. It requires syntax native to Druid, because the full query is pushed down and processed in Druid. This can be useful for accessing native features which are not available in Trino or for improving query performance in situations where running a query natively may be faster.

Предупреждение

Нативный запрос, переданный в источник, должен возвращать набор записей (result set). CedrusData не осуществляет проверку доступа текущего пользователя к объектам источника, задействованным в нативном запросе. Используйте нативные запросы только для чтения данных.

As an example, query the example catalog and use STRING_TO_MV and MV_LENGTH from Druid SQL’s multi-value string functions to split and then count the number of comma-separated values in a column:

SELECT
  num_reports
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        MV_LENGTH(
          STRING_TO_MV(direct_reports, ",")
        ) AS num_reports
      FROM company.managers'
    )
  );

Примечание

Полиморфные табличные функции не сохраняют оригинальный порядок записей в результате запроса. Есть переданный запрос содержит запрос выражение ORDER BY, функция может вернуть записи в ином порядке. Для восстановления требуемого порядка используйте ORDER BY в запросе CedrusData.