Ignite connector#

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

Requirements#

To connect to an Ignite server, you need:

Ignite version 2.9.0 or latter
Network access from the Trino coordinator and workers to the Ignite server. Port 10800 is the default port.
Specify --add-opens=java.base/java.nio=ALL-UNNAMED in the jvm.config when starting the Trino server.

Configuration#

The Ignite connector expose public schema by default.

The connector can query an Ignite instance. Create a catalog properties file that specifies the Ignite connector by setting the connector.name to ignite.

For example, to access an instance as example, create the file etc/catalog/example.properties. Replace the connection properties as appropriate for your setup:

connector.name=ignite
connection-url=jdbc:ignite:thin://host1:10800/
connection-user=exampleuser
connection-password=examplepassword

The connection-url defines the connection information and parameters to pass to the Ignite JDBC driver. The parameters for the URL are available in the Ignite JDBC driver documentation. Some parameters can have adverse effects on the connector behavior or not work with the connector.

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.

Multiple Ignite servers#

If you have multiple Ignite servers you need to configure one catalog for each server. To add another catalog:

Add another properties file to etc/catalog
Save it with a different name that ends in .properties

For example, if you name the property file sales.properties, Trino uses the configured connector to create a catalog named sales.

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

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

Имя свойства	Описание
`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`.

Добавление метаданных запроса#

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

$QUERY_ID: идентификатор запроса.
$USER: имя пользователя, отправившего запрос в Trino.
$SOURCE: идентификатор клиентского инструмента, использованного для отправки запроса, например trino-cli.
$TRACE_TOKEN: токен трассировки, настроенный в клиентском инструменте.

Комментарий может предоставить больше контекста о запросе. Эта дополнительная информация доступна в журналах источника данных. Чтобы включить в комментарий переменные окружения из кластера Trino, используйте синтаксис ${ENV:VARIABLE-NAME}.

Следующий пример задает простой комментарий, идентифицирующий каждый запрос, отправленный Trino:

query.comment-format=Query sent by Trino.

С такой конфигурацией запрос вроде SELECT * FROM example_table; отправляется источнику данных с добавленным комментарием:

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, источнику данных отправляется следующая строка комментария:

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

Note

Некоторые настройки драйвера JDBC и конфигурации журналирования могут привести к удалению комментария.

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

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

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

Когда 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

Table properties#

Table property usage example:

CREATE TABLE public.person (
  id BIGINT NOT NULL,
  birthday DATE NOT NULL,
  name VARCHAR(26),
  age BIGINT,
  logdate DATE
)
WITH (
  primary_key = ARRAY['id', 'birthday']
);

The following are supported Ignite table properties from https://ignite.apache.org/docs/latest/sql-reference/ddl

Property name	Required	Description
`primary_key`	No	The primary key of the table, can choose multi columns as the table primary key. Table at least contains one column not in primary key.

`primary_key`#

This is a list of columns to be used as the table’s primary key. If not specified, a VARCHAR primary key column named DUMMY_ID is generated, the value is derived from the value generated by the UUID function in Ignite.

Type mapping#

The following are supported Ignite SQL data types from https://ignite.apache.org/docs/latest/sql-reference/data-types

Ignite SQL data type name	Map to Trino type	Possible values
`BOOLEAN`	`BOOLEAN`	`TRUE` and `FALSE`
`BIGINT`	`BIGINT`	`-9223372036854775808`, `9223372036854775807`, etc.
`DECIMAL`	`DECIMAL`	Data type with fixed precision and scale
`DOUBLE`	`DOUBLE`	`3.14`, `-10.24`, etc.
`INT`	`INT`	`-2147483648`, `2147483647`, etc.
`REAL`	`REAL`	`3.14`, `-10.24`, etc.
`SMALLINT`	`SMALLINT`	`-32768`, `32767`, etc.
`TINYINT`	`TINYINT`	`-128`, `127`, etc.
`CHAR`	`CHAR`	`hello`, `Trino`, etc.
`VARCHAR`	`VARCHAR`	`hello`, `Trino`, etc.
`DATE`	`DATE`	`1972-01-01`, `2021-07-15`, etc.
`BINARY`	`VARBINARY`	Represents a byte array.

SQL support#

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

INSERT, see also Нетранзакционный INSERT
UPDATE, see also Ограничение UPDATE
DELETE
MERGE, see also Нетранзакционный MERGE
CREATE TABLE
CREATE TABLE AS
DROP TABLE
ALTER TABLE, see also ALTER TABLE RENAME TO limitation
Procedures

Нетранзакционный INSERT#

Коннектор поддерживает добавление строк с помощью операторов INSERT. По умолчанию вставка данных выполняется путем записи данных во временную таблицу. Этот шаг можно пропустить, чтобы повысить производительность и писать напрямую в целевую таблицу. Установите свойство каталога insert.non-transactional-insert.enabled или соответствующее свойство сеанса каталога non_transactional_insert в true.

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

Ограничение UPDATE#

Поддерживаются только операторы UPDATE с константными присваиваниями и предикатами. Например, следующий оператор поддерживается, потому что присваиваемые значения являются константами:

UPDATE table SET col1 = 1 WHERE col3 = 1

Арифметические выражения, вызовы функций и другие неконстантные операторы UPDATE не поддерживаются. Например, следующий оператор не поддерживается, поскольку арифметические выражения нельзя использовать с командой SET:

UPDATE table SET col1 = col2 + 2 WHERE col3 = 1

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

UPDATE table SET col1 = 1, col2 = 2, col3 = 3 WHERE col3 = 1

Нетранзакционный MERGE#

Коннектор поддерживает добавление, обновление и удаление строк с помощью операторов MERGE, если свойство каталога merge.non-transactional-merge.enabled или соответствующее свойство сеанса каталога non_transactional_merge_enabled установлено в true. Merge поддерживается только для непосредственного изменения целевых таблиц.

В редких случаях во время операции merge могут возникать исключения, что потенциально приводит к частичному обновлению.

ALTER TABLE RENAME TO limitation#

The connector does not support renaming tables across multiple schemas. For example, the following statement is supported:

ALTER TABLE example.schema_one.table_one RENAME TO example.schema_one.table_two

The following statement attempts to rename a table across schemas, and therefore is not supported:

ALTER TABLE example.schema_one.table_one RENAME TO example.schema_two.table_two

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');

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

Pushdown#

The connector supports pushdown for a number of operations:

Aggregate pushdown for the following functions:

Поддержка проталкивания предикатов#

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

В следующем примере предикат не проталкивается ни для одного запроса, поскольку name — столбец типа VARCHAR:

SELECT * FROM nation WHERE name > 'CANADA';
SELECT * FROM nation WHERE name = 'CANADA';