SingleStore коннектор#

Примечание

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

The SingleStore (formerly known as MemSQL) connector allows querying and creating tables in an external SingleStore database.

Requirements#

To connect to SingleStore, you need:

SingleStore version 7.1.4 or higher.
Network access from the Trino coordinator and workers to SingleStore. Port 3306 is the default port.

Configuration#

To configure the SingleStore connector, create a catalog properties file in etc/catalog named, for example, example.properties, to mount the SingleStore connector as the example catalog. Create the file with the following contents, replacing the connection properties as appropriate for your setup:

connector.name=singlestore
connection-url=jdbc:singlestore://example.net:3306
connection-user=root
connection-password=secret

The connection-url defines the connection information and parameters to pass to the SingleStore JDBC driver. The supported parameters for the URL are available in the SingleStore JDBC driver documentation.

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.

Connection security#

If you have TLS configured with a globally-trusted certificate installed on your data source, you can enable TLS between your cluster and the data source by appending a parameter to the JDBC connection string set in the connection-url catalog configuration property.

Enable TLS between your cluster and SingleStore by appending the useSsl=true parameter to the connection-url configuration property:

connection-url=jdbc:singlestore://example.net:3306/?useSsl=true

For more information on TLS configuration options, see the JDBC driver documentation.

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

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

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 другие параметры аутентификации коннектора будут проигнорированы.

Multiple SingleStore servers#

You can have as many catalogs as you need, so if you have additional SingleStore servers, simply add another properties file to etc/catalog with a different name (making sure it ends in .properties). For example, if you name the property file sales.properties, Trino will create a catalog named sales using the configured connector.

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

Название	Описание	Значение по умолчанию
`case-insensitive-name-matching`	Включить поддержку case insensitive идентификаторов.	`false`
`case-insensitive-name-matching.cache-ttl`	Время жизни закэшированных метаданных о case insensitive идентификаторах. Значение имеет тип 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.cache-missing`	Кэшировать ли информацию о том, что для используемых таблиц и колонок отсутствуют статистики. Включение данного параметра может ускорить планирование некоторых запросов. Однако, если информация об отсутствии статистик для конкретного объекта СУБД закэширована, но статистики стали доступны позднее (например, была запущена команда `ANALYZE`), CedrusData не сможет использовать статистики, пока не истечет время жизни закэшированной записи в соответствии с `metadata.cache-ttl`.	`false`
`metadata.schemas.cache-ttl`	Время жизни закэшированных имен схем. Положительное значение включает кэширование. Допустимо только, если параметр `metadata.cache-ttl` имеет положительное значение. Значение имеет тип duration.	`0` (кэширование отключено)
`metadata.tables.cache-ttl`	Время жизни закэшированных имен таблиц. Положительное значение включает кэширование. Допустимо только, если параметр `metadata.cache-ttl` имеет положительное значение. Значение имеет тип duration.	`0` (кэширование отключено)
`metadata.statistics.cache-ttl`	Время жизни закэшированных статистик. Положительное значение включает кэширование. Допустимо только, если параметр `metadata.cache-ttl` имеет положительное значение. Значение имеет тип duration.	`0` (кэширование отключено)
`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

Неатомарный INSERT#

Коннектор поддерживает добавление записей в источник с помощью команды INSERT statements. По умолчанию CedrusData осуществляет запись данных, используя временную таблицу, что обеспечивает транзакционные гарантии: в источник будут записаны либо все данные, либо не будет записано ничего (в случае возникновения ошибки).

Вы можете осуществлять запись данных в таблицу источника напрямую, минуя временную таблицу. Для этого установите параметр конфигурации каталога insert.non-transactional-insert.enabled или свойство сессии non_transactional_insert в значение true. Изменение данного параметра может увеличить производительность записи, но может привести данные в источнике в неопределенное состояние при возникновении ошибки в момент записи. Например, если при вставке 10 записей в таблицу источника в середине процесса произошла ошибка, откат вставки уже сохраненных записей может оказаться невозможным, и после выполнения команды источник будет содержать только часть записей.

Querying SingleStore#

The SingleStore connector provides a schema for every SingleStore database. You can see the available SingleStore databases by running SHOW SCHEMAS:

SHOW SCHEMAS FROM example;

If you have a SingleStore database named web, you can view the tables in this database by running SHOW TABLES:

SHOW TABLES FROM example.web;

You can see a list of the columns in the clicks table in the web database using either of the following:

DESCRIBE example.web.clicks;
SHOW COLUMNS FROM example.web.clicks;

Finally, you can access the clicks table in the web database:

SELECT * FROM example.web.clicks;

If you used a different name for your catalog properties file, use that catalog name instead of example in the above examples.

Type mapping#

Because Trino and Singlestore each support types that the other does not, this connector modifies some types when reading or writing 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.

Singlestore to Trino type mapping#

The connector maps Singlestore types to the corresponding Trino types following this table:

Singlestore to Trino type mapping#
Singlestore type	Trino type	Notes
`BIT`	`BOOLEAN`
`BOOLEAN`	`BOOLEAN`
`TINYINT`	`TINYINT`
`TINYINT UNSIGNED`	`SMALLINT`
`SMALLINT`	`SMALLINT`
`SMALLINT UNSIGNED`	`INTEGER`
`INTEGER`	`INTEGER`
`INTEGER UNSIGNED`	`BIGINT`
`BIGINT`	`BIGINT`
`BIGINT UNSIGNED`	`DECIMAL(20, 0)`
`DOUBLE`	`DOUBLE`
`REAL`	`DOUBLE`
`DECIMAL(p, s)`	`DECIMAL(p, s)`	See Singlestore DECIMAL type handling
`CHAR(n)`	`CHAR(n)`
`TINYTEXT`	`VARCHAR(255)`
`TEXT`	`VARCHAR(65535)`
`MEDIUMTEXT`	`VARCHAR(16777215)`
`LONGTEXT`	`VARCHAR`
`VARCHAR(n)`	`VARCHAR(n)`
`LONGBLOB`	`VARBINARY`
`DATE`	`DATE`
`TIME`	`TIME(0)`
`TIME(6)`	`TIME(6)`
`DATETIME`	`TIMESTAMP(0)`
`DATETIME(6)`	`TIMESTAMP(6)`
`JSON`	`JSON`

No other types are supported.

Trino to Singlestore type mapping#

The connector maps Trino types to the corresponding Singlestore types following this table:

Trino to Singlestore type mapping#
Trino type	Singlestore type	Notes
`BOOLEAN`	`BOOLEAN`
`TINYINT`	`TINYINT`
`SMALLINT`	`SMALLINT`
`INTEGER`	`INTEGER`
`BIGINT`	`BIGINT`
`DOUBLE`	`DOUBLE`
`REAL`	`FLOAT`
`DECIMAL(p, s)`	`DECIMAL(p, s)`	See Singlestore DECIMAL type handling
`CHAR(n)`	`CHAR(n)`
`VARCHAR(65535)`	`TEXT`
`VARCHAR(16777215)`	`MEDIUMTEXT`
`VARCHAR`	`LONGTEXT`
`VARCHAR(n)`	`VARCHAR(n)`
`VARBINARY`	`LONGBLOB`
`DATE`	`DATE`
`TIME(0)`	`TIME`
`TIME(6)`	`TIME(6)`
`TIMESTAMP(0)`	`DATETIME`
`TIMESTAMP(6)`	`DATETIME(6)`
`JSON`	`JSON`

No other types are supported.

Обработка DECIMAL типов#

CedrusData по умолчанию игнорирует колонки с типом данных DECIMAL без явного указания precision или scale. Если значение параметра конфигурации коннектора decimal-mapping (или параметра сессии decimal_mapping) равно allow_overflow, то колонки с типом данных DECIMAL без явного указания precision или scale будут отображены и сопоставлены с типом данных CedrusData DECIMAL(38,0). Используйте параметр конфигурации коннектора decimal-default-scale (или параметр сессии decimal_default_scale), чтобы задать другое значение scale. Значение precision всегда равно 38.

Если DECIMAL значение не умещается в заданные precision и scale без округления, CedrusData вернет ошибку. Вы можете изменить данное поведение, разрешив автоматическое округление значение с помощью параметра конфигурации коннектора decimal-rounding-mode или параметра сессии decimal_rounding_mode. Допустимые значения: UNNECESSARY (значение по умолчанию), UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN. Данные значения соответствуют поведению RoundingMode в Java 17.

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

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

Название	Описание	Значение по умолчанию
`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 and write access to data and metadata in a SingleStore database. In addition to the globally available and read operation statements, the connector supports the following features:

UPDATE#

Команда UPDATE позволяет изменять значения колонок только на константные значения:

UPDATE table SET col1 = 1 WHERE col3 = 1

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

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

Операторы =, !=, >, <, >=, <=, IN, NOT IN поддерживаются в WHERE. Следующий запрос вернет ошибку, потому что оператор AND не поддерживается в WHERE:

UPDATE table SET col1 = 1 WHERE col3 = 1 AND col2 = 3

Все колонки записи таблицы не могут быть обновлены одновременно. Например, если таблица table содержит три колонки, следующий запрос вернет ошибку:

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

DELETE#

Команда DELETE с выражением WHERE работает только в случае, когда выполнение предиката может быть полностью делегировано источнику.

ALTER TABLE RENAME TO#

Коннектор поддерживает переименование таблиц только в пределах одной схемы.

Следующая команда поддерживается коннектором, так как переименовывает таблицу в пределах одной схемы.

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

Следующая команда не поддерживается коннектором, так как меняет схему таблицы:

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

Performance#

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

Pushdown#

The connector supports pushdown for a number of operations:

Примечание

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

Join pushdown#

The join-pushdown.enabled catalog configuration property or join_pushdown_enabled catalog session property control whether the connector pushes down join operations. The property defaults to false, and enabling join pushdowns may negatively impact performance for some queries.

Поддержка predicate pushdown#

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

-- Not pushed down
SELECT * FROM nation WHERE name > 'CANADA';
SELECT * FROM nation WHERE name = 'CANADA';