Phoenix коннектор#

Примечание

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

The Phoenix connector allows querying data stored in Apache HBase using Apache Phoenix.

Requirements#

To query HBase data through Phoenix, you need:

Network access from the Trino coordinator and workers to the ZooKeeper servers. The default port is 2181.
A compatible version of Phoenix: all 5.x versions starting from 5.2.0 are supported.

Configuration#

To configure the Phoenix connector, create a catalog properties file etc/catalog/example.properties with the following contents, replacing host1,host2,host3 with a comma-separated list of the ZooKeeper nodes used for discovery of the HBase cluster:

connector.name=phoenix5
phoenix.connection-url=jdbc:phoenix:host1,host2,host3:2181:/hbase
phoenix.config.resources=/path/to/hbase-site.xml

The optional paths to Hadoop resource files, such as hbase-site.xml are used to load custom Phoenix client connection properties.

The following Phoenix-specific configuration properties are available:

Property name	Required	Description
`phoenix.connection-url`	Yes	`jdbc:phoenix[:zk_quorum][:zk_port][:zk_hbase_path]`. The `zk_quorum` is a comma separated list of ZooKeeper servers. The `zk_port` is the ZooKeeper port. The `zk_hbase_path` is the HBase root znode path, that is configurable using `hbase-site.xml`. By default the location is `/hbase`
`phoenix.config.resources`	No	Comma-separated list of configuration files (e.g. `hbase-site.xml`) to use for connection properties. These files must exist on the machines running Trino.
`phoenix.max-scans-per-split`	No	Maximum number of HBase scans that will be performed in a single split. Default is 20. Lower values will lead to more splits in Trino. Can also be set via session propery `max_scans_per_split`. For details see: https://phoenix.apache.org/update_statistics.html. (This setting has no effect when guideposts are disabled in Phoenix.)

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

Название	Описание	Значение по умолчанию
`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.

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 Phoenix tables#

The default empty schema in Phoenix maps to a schema named default in Trino. You can see the available Phoenix schemas by running SHOW SCHEMAS:

SHOW SCHEMAS FROM example;

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

SHOW TABLES FROM example.web;

You can see a list of the columns in the clicks table in the web schema 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 schema:

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 Phoenix 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.

Phoenix type to Trino type mapping#

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

Phoenix type to Trino type mapping#
Phoenix database type	Trino type
`BOOLEAN`	`BOOLEAN`
`TINYINT`	`TINYINT`
`UNSIGNED_TINYINT`	`TINYINT`
`SMALLINT`	`SMALLINT`
`UNSIGNED_SMALLINT`	`SMALLINT`
`INTEGER`	`INTEGER`
`UNSIGNED_INT`	`INTEGER`
`BIGINT`	`BIGINT`
`UNSIGNED_LONG`	`BIGINT`
`FLOAT`	`REAL`
`UNSIGNED_FLOAT`	`REAL`
`DOUBLE`	`DOUBLE`
`UNSIGNED_DOUBLE`	`DOUBLE`
`DECIMAL(p,s)`	`DECIMAL(p,s)`
`CHAR(n)`	`CHAR(n)`
`VARCHAR(n)`	`VARCHAR(n)`
`BINARY`	`VARBINARY`
`VARBINARY`	`VARBINARY`
`DATE`	`DATE`
`UNSIGNED_DATE`	`DATE`
`ARRAY`	`ARRAY`

No other types are supported.

Trino type to Phoenix type mapping#

The Phoenix fixed length BINARY data type is mapped to the Trino variable length VARBINARY data type. There is no way to create a Phoenix table in Trino that uses the BINARY data type, as Trino does not have an equivalent type.

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

Trino type to Phoenix type mapping#
Trino database type	Phoenix type
`BOOLEAN`	`BOOLEAN`
`TINYINT`	`TINYINT`
`SMALLINT`	`SMALLINT`
`INTEGER`	`INTEGER`
`BIGINT`	`BIGINT`
`REAL`	`FLOAT`
`DOUBLE`	`DOUBLE`
`DECIMAL(p,s)`	`DECIMAL(p,s)`
`CHAR(n)`	`CHAR(n)`
`VARCHAR(n)`	`VARCHAR(n)`
`VARBINARY`	`VARBINARY`
`DATE`	`DATE`
`ARRAY`	`ARRAY`

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` неограниченной длины (даже если указанный тип поддерживается коннектором).

Table properties - Phoenix#

Table property usage example:

CREATE TABLE example_schema.scientists (
  recordkey VARCHAR,
  birthday DATE,
  name VARCHAR,
  age BIGINT
)
WITH (
  rowkeys = 'recordkey,birthday',
  salt_buckets = 10
);

The following are supported Phoenix table properties from https://phoenix.apache.org/language/index.html#options

Property name	Default value	Description
`rowkeys`	`ROWKEY`	Comma-separated list of primary key columns. See further description below
`split_on`	(none)	List of keys to presplit the table on. See Split Point.
`salt_buckets`	(none)	Number of salt buckets for this table.
`disable_wal`	false	Whether to disable WAL writes in HBase for this table.
`immutable_rows`	false	Declares whether this table has rows which are write-once, append-only.
`default_column_family`	`0`	Default column family name to use for this table.

`rowkeys`#

This is a comma-separated list of columns to be used as the table’s primary key. If not specified, a BIGINT primary key column named ROWKEY is generated , as well as a sequence with the same name as the table suffixed with _seq (i.e. <schema>.<table>_seq) , which is used to automatically populate the ROWKEY for each row during insertion.

Table properties - HBase#

The following are the supported HBase table properties that are passed through by Phoenix during table creation. Use them in the same way as above: in the WITH clause of the CREATE TABLE statement.

Property name	Default value	Description
`versions`	`1`	The maximum number of versions of each cell to keep.
`min_versions`	`0`	The minimum number of cell versions to keep.
`compression`	`NONE`	Compression algorithm to use. Valid values are `NONE` (default), `SNAPPY`, `LZO`, `LZ4`, or `GZ`.
`data_block_encoding`	`FAST_DIFF`	Block encoding algorithm to use. Valid values are: `NONE`, `PREFIX`, `DIFF`, `FAST_DIFF` (default), or `ROW_INDEX_V1`.
`ttl`	`FOREVER`	Time To Live for each cell.
`bloomfilter`	`NONE`	Bloomfilter to use. Valid values are `NONE` (default), `ROW`, or `ROWCOL`.

SQL support#

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

DELETE#

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

Procedures#

`system.execute('query')`#

Процедура execute позволяет запустить SQL запрос к источнику в неизменном виде. Данная процедура полезна, когда вам требуется воспользоваться специфичным синтаксисом источника, который недоступен в CedrusData. В отличие от табличных функций query и raw_query данная процедура позволяет запускать SQL-запросы, который не возвращают записи (например, DML и DDL команды).

Запрос из процедуры будет исполнен в источнике как есть, без дополнительных проверок доступа к конкретным объектам источника на стороне CedrusData.

Пример использования процедуры для вызова команды ALTER TABLE на источнике:

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