Exasol connector#

The Exasol connector allows querying an Exasol database.

Requirements#

To connect to Exasol, you need:

Exasol database version 8.34.0 or higher.
Network access from the Trino coordinator and workers to Exasol. Port 8563 is the default port.

Configuration#

To configure the Exasol connector as the example catalog, create a file named example.properties in etc/catalog. Include the following connection properties in the file:

connector.name=exasol
connection-url=jdbc:exa:exasol.example.com:8563
connection-user=user
connection-password=secret

The connection-url defines the connection information and parameters to pass to the JDBC driver. See the Exasol JDBC driver documentation for more information.

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 using actual values in catalog properties files.

Note

If your Exasol database uses a self-signed TLS certificate you must specify the certificate’s fingerprint in the JDBC URL using parameter fingerprint, e.g.: jdbc:exa:exasol.example.com:8563;fingerprint=ABC123.

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

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

непосредственно в файле конфигурации коннектора;
в отдельном файле свойств;
в файле хранилища ключей;
как дополнительные учетные данные, заданные при подключении к Trino.

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

В следующей таблице описаны свойства конфигурации для учетных данных подключения:

Имя свойства	Описание
`credential-provider.type`	Тип поставщика учетных данных. Должен быть одним из `INLINE`, `FILE` или `KEYSTORE`; по умолчанию — `INLINE`.
`connection-user`	Имя пользователя подключения.
`connection-password`	Пароль подключения.
`user-credential-name`	Имя свойства дополнительных учетных данных, значение которого используется как имя пользователя. См. `extraCredentials` в справочнике параметров.
`password-credential-name`	Имя свойства дополнительных учетных данных, значение которого используется как пароль.
`connection-credential-file`	Расположение файла свойств, в котором находятся учетные данные. Он должен содержать свойства `connection-user` и `connection-password`.
`keystore-file-path`	Расположение файла Java Keystore, из которого считываются учетные данные.
`keystore-type`	Формат файла хранилища ключей, например `JKS` или `PEM`.
`keystore-password`	Пароль для хранилища ключей.
`keystore-user-credential-name`	Имя сущности хранилища ключей, используемой как имя пользователя.
`keystore-user-credential-password`	Пароль для сущности хранилища ключей с именем пользователя.
`keystore-password-credential-name`	Имя сущности хранилища ключей, используемой как пароль.
`keystore-password-credential-password`	Пароль для сущности хранилища ключей с паролем.

Общие свойства конфигурации#

В следующей таблице описаны общие свойства конфигурации каталога для коннектора:

Имя свойства	Описание
`case-insensitive-name-matching`	Поддержка имен схем и таблиц без учета регистра. По умолчанию — `false`.
`case-insensitive-name-matching.cache-ttl`	Длительность, в течение которой кэшируются имена схем и таблиц при сопоставлении без учета регистра. По умолчанию — `1m`.
`case-insensitive-name-matching.config-file`	Путь к конфигурационному файлу сопоставления имен в формате JSON, который позволяет Trino различать схемы и таблицы с похожими именами в разных регистрах. По умолчанию — `null`.
`case-insensitive-name-matching.config-file.refresh-period`	Частота, с которой Trino проверяет конфигурационный файл сопоставления имен на изменения. Значение длительности по умолчанию — `0s` (обновление отключено).
`metadata.cache-ttl`	Длительность, в течение которой кэшируются метаданные, включая статистику таблиц и столбцов. По умолчанию — `0s` (кэширование отключено).
`metadata.cache-missing`	Кэшировать факт недоступности метаданных, включая статистику таблиц и столбцов. По умолчанию — `false`.
`metadata.schemas.cache-ttl`	Длительность, в течение которой кэшируются метаданные схем. По умолчанию равно значению `metadata.cache-ttl`.
`metadata.tables.cache-ttl`	Длительность, в течение которой кэшируются метаданные таблиц. По умолчанию равно значению `metadata.cache-ttl`.
`metadata.statistics.cache-ttl`	Длительность, в течение которой кэшируется статистика таблиц. По умолчанию равно значению `metadata.cache-ttl`.
`metadata.cache-maximum-size`	Максимальное число объектов, хранящихся в кэше метаданных. По умолчанию — `10000`.
`write.batch-size`	Максимальное число операторов в пакетном выполнении. Не меняйте это значение относительно значения по умолчанию. Нестандартные значения могут отрицательно повлиять на производительность. По умолчанию — `1000`.
`dynamic-filtering.enabled`	Проталкивать динамические фильтры в JDBC-запросы. По умолчанию — `true`.
`dynamic-filtering.wait-timeout`	Максимальная длительность, в течение которой Trino ожидает сбора динамических фильтров со стороны построения соединения перед запуском JDBC-запроса. Большой тайм-аут потенциально может дать более подробные динамические фильтры, но также может увеличить задержку некоторых запросов. По умолчанию — `20s`.

Порог компактирования домена#

Проталкивание большого списка предикатов в источник данных может ухудшить производительность. По умолчанию Trino компактирует большие предикаты в более простой предикат диапазона, чтобы сохранить баланс между производительностью и проталкиванием предикатов. При необходимости порог такого компактирования можно увеличить, чтобы повысить производительность, когда источник данных способен эффективно использовать большие предикаты. Увеличение этого порога может улучшить проталкивание больших динамических фильтров. Свойство конфигурации каталога domain-compaction-threshold или свойство сеанса каталога domain_compaction_threshold можно использовать для изменения значения по умолчанию 256 для этого порога.

Сопоставление без учета регистра#

Когда case-insensitive-name-matching установлено в true, Trino может запрашивать схемы и таблицы с именами не только в нижнем регистре, поддерживая сопоставление имени в нижнем регистре с фактическим именем в удаленной системе. Однако если две схемы и/или таблицы имеют имена, различающиеся только регистром, например “customers” и “Customers”, Trino не сможет запрашивать их из-за неоднозначности.

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

{
  "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"
    }]
}

Запросы к одной из таблиц или схем, заданных в атрибутах mapping, выполняются к соответствующей удаленной сущности. Например, запрос к таблицам в схеме case_insensitive_1 перенаправляется в схему CaseSensitiveName, а запрос к case_insensitive_2 — в схему cASEsENSITIVEnAME.

На уровне сопоставления таблиц запрос к case_insensitive_1.table_1 в приведенной выше конфигурации перенаправляется к CaseSensitiveName.tablex, а запрос к case_insensitive_1.table_2 — к CaseSensitiveName.TABLEX.

По умолчанию после изменения конфигурационного файла сопоставления Trino нужно перезапустить, чтобы загрузить изменения. При необходимости можно задать case-insensitive-name-matching.config-file.refresh-period, чтобы Trino обновлял свойства без перезапуска:

case-insensitive-name-matching.config-file.refresh-period=30s

Type mapping#

Because Trino and Exasol each support types that the other does not, this connector modifies some types when reading data. Data types may not map the same way in both directions between Trino and the data source. Refer to the following sections for type mapping in each direction.

Exasol to Trino type mapping#

Trino supports selecting Exasol database types. This table shows the Exasol to Trino data type mapping:

Exasol to Trino type mapping#
Exasol database type	Trino type	Notes
`BOOLEAN`	`BOOLEAN`
`DOUBLE PRECISION`	`REAL`
`DECIMAL(p, s)`	`DECIMAL(p, s)`	See Mapping numeric types
`CHAR(n)`	`CHAR(n)`
`VARCHAR(n)`	`VARCHAR(n)`
`DATE`	`DATE`
`HASHTYPE`	`VARBINARY`

No other types are supported.

Mapping numeric types#

An Exasol DECIMAL(p, s) maps to Trino’s DECIMAL(p, s) and vice versa except in these conditions:

No precision is specified for the column (example: DECIMAL or DECIMAL(*)).
Scale (s) is greater than precision.
Precision (p) is greater than 36.
Scale is negative.

Mapping character types#

Trino’s VARCHAR(n) maps to VARCHAR(n) and vice versa if n is no greater than 2000000. Exasol does not support longer values. If no length is specified, the connector uses 2000000.

Trino’s CHAR(n) maps to CHAR(n) and vice versa if n is no greater than 2000. Exasol does not support longer values.

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

Следующие свойства можно использовать для настройки того, как типы данных из подключенного источника данных сопоставляются с типами данных Trino и как метаданные кэшируются в Trino.

Имя свойства

Описание

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

unsupported-type-handling

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

IGNORE — столбец недоступен.
CONVERT_TO_VARCHAR — столбец преобразуется в неограниченный VARCHAR.

Соответствующее свойство сеанса каталога — unsupported_type_handling.

IGNORE

jdbc-types-mapped-to-varchar

Позволяет принудительно сопоставлять списки типов данных, разделенные запятыми, с неограниченным VARCHAR.

SQL support#

The connector provides read access to data and metadata in Exasol. In addition to the globally available and read operation statements, the connector supports the following features:

Procedures
Table functions

Procedures#

`system.flush_metadata_cache()`#

Очищает кэши метаданных JDBC. Например, следующий системный вызов очищает кэши метаданных для всех схем в каталоге example:

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

`system.execute('query')`#

Процедура execute позволяет выполнить запрос напрямую в базовом источнике данных. Запрос должен использовать поддерживаемый синтаксис подключенного источника данных. Используйте процедуру для доступа к возможностям, которые недоступны в Trino, или для выполнения запросов, которые не возвращают набор результатов и поэтому не могут использоваться с транзитной табличной функцией query или raw_query. Типичные случаи применения — операторы, создающие или изменяющие объекты и требующие нативных возможностей, таких как ограничения, значения по умолчанию, автоматическое создание идентификаторов или индексы. Запросы также могут вызывать операторы, которые вставляют, обновляют или удаляют данные и не возвращают данных в результате.

Текст запроса не разбирается Trino, а только передается дальше, поэтому он подчиняется только правилам безопасности и контроля доступа базового источника данных.

В следующем примере текущая база данных устанавливается в example_schema каталога example. Затем в этой схеме вызывается процедура, чтобы удалить значение по умолчанию из your_column в таблице your_table с помощью стандартного SQL-синтаксиса в значении параметра query:

USE example.example_schema;
CALL system.execute(query => 'ALTER TABLE your_table ALTER COLUMN your_column DROP DEFAULT');

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

Table functions#

The connector provides specific table functions to access Exasol.

`query(varchar) -> table`#

The query function allows you to query the underlying database directly. It requires syntax native to Exasol, because the full query is pushed down and processed in Exasol. 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.

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

As a simple example, query the example catalog and select an entire table::

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        *
      FROM
        tpch.nation'
    )
  );

As a practical example, you can use the WINDOW clause from Exasol:

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        id, department, hire_date, starting_salary,
        AVG(starting_salary) OVER w2 AVG,
        MIN(starting_salary) OVER w2 MIN_STARTING_SALARY,
        MAX(starting_salary) OVER (w1 ORDER BY hire_date)
      FROM employee_table
      WINDOW w1 as (PARTITION BY department), w2 as (w1 ORDER BY hire_date)
      ORDER BY department, hire_date'
    )
  );

Note

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

Performance#

The connector includes a number of performance improvements, detailed in the following sections.

Pushdown#

The connector supports pushdown for a number of operations: