Redshift connector#
The Redshift connector allows querying and creating tables in an external Amazon Redshift cluster. This can be used to join data between different systems like Redshift and Hive, or between two different Redshift clusters.
Requirements#
To connect to Redshift, you need:
Network access from the Trino coordinator and workers to Redshift. Port 5439 is the default port.
Configuration#
To configure the Redshift connector, create a catalog properties file in
etc/catalog named, for example, example.properties, to mount the
Redshift connector as the example catalog. Create the file with the
following contents, replacing the connection properties as appropriate for your
setup:
connector.name=redshift
connection-url=jdbc:redshift://example.net:5439/database
connection-user=root
connection-password=secret
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.
For example, on version 2.1 of the Redshift JDBC driver, TLS/SSL is enabled by
default with the SSL parameter. You can disable or further configure TLS
by appending parameters to the connection-url configuration property:
connection-url=jdbc:redshift://example.net:5439/database;SSL=TRUE;
For more information on TLS configuration options, see the Redshift JDBC driver documentation.
Аутентификация источника данных#
Коннектор может передавать учетные данные для подключения к источнику данных несколькими способами:
непосредственно в файле конфигурации коннектора;
в отдельном файле свойств;
в файле хранилища ключей;
как дополнительные учетные данные, заданные при подключении к Trino.
Можно использовать секреты, чтобы не хранить конфиденциальные значения в файлах свойств каталога.
В следующей таблице описаны свойства конфигурации для учетных данных подключения:
Имя свойства |
Описание |
|---|---|
|
Тип поставщика учетных данных. Должен быть одним из |
|
Имя пользователя подключения. |
|
Пароль подключения. |
|
Имя свойства дополнительных учетных данных, значение которого используется
как имя пользователя. См. |
|
Имя свойства дополнительных учетных данных, значение которого используется как пароль. |
|
Расположение файла свойств, в котором находятся учетные данные. Он должен
содержать свойства |
|
Расположение файла Java Keystore, из которого считываются учетные данные. |
|
Формат файла хранилища ключей, например |
|
Пароль для хранилища ключей. |
|
Имя сущности хранилища ключей, используемой как имя пользователя. |
|
Пароль для сущности хранилища ключей с именем пользователя. |
|
Имя сущности хранилища ключей, используемой как пароль. |
|
Пароль для сущности хранилища ключей с паролем. |
Multiple Redshift databases or clusters#
The Redshift connector can only access a single database within a Redshift cluster. Thus, if you have multiple Redshift databases, or want to connect to multiple Redshift clusters, you must configure multiple instances of the Redshift connector.
To add another catalog, 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 creates a
catalog named sales using the configured connector.
Общие свойства конфигурации#
В следующей таблице описаны общие свойства конфигурации каталога для коннектора:
Имя свойства |
Описание |
|---|---|
|
Поддержка имен схем и таблиц без учета регистра. По умолчанию — |
|
Длительность, в течение которой кэшируются имена схем
и таблиц при сопоставлении без учета регистра. По умолчанию — |
|
Путь к конфигурационному файлу сопоставления имен в формате JSON, который
позволяет Trino различать схемы и таблицы с похожими именами в разных
регистрах. По умолчанию — |
|
Частота, с которой Trino проверяет конфигурационный файл сопоставления имен
на изменения. Значение длительности по умолчанию —
|
|
Длительность, в течение которой кэшируются
метаданные, включая статистику таблиц и столбцов. По умолчанию — |
|
Кэшировать факт недоступности метаданных, включая статистику таблиц и
столбцов. По умолчанию — |
|
Длительность, в течение которой кэшируются метаданные
схем. По умолчанию равно значению |
|
Длительность, в течение которой кэшируются метаданные
таблиц. По умолчанию равно значению |
|
Длительность, в течение которой кэшируется статистика
таблиц. По умолчанию равно значению |
|
Максимальное число объектов, хранящихся в кэше метаданных. По умолчанию —
|
|
Максимальное число операторов в пакетном выполнении. Не меняйте это
значение относительно значения по умолчанию. Нестандартные значения могут
отрицательно повлиять на производительность. По умолчанию — |
|
Проталкивать динамические фильтры в JDBC-запросы. По умолчанию — |
|
Максимальная длительность, в течение которой Trino
ожидает сбора динамических фильтров со стороны построения соединения перед
запуском JDBC-запроса. Большой тайм-аут потенциально может дать более
подробные динамические фильтры, но также может увеличить задержку некоторых
запросов. По умолчанию — |
Добавление метаданных запроса#
Необязательный параметр 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 можно
использовать для изменения значения по умолчанию
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
Fault-tolerant execution support#
The connector supports Fault-tolerant execution of query processing. Read and write operations are both supported with any retry policy.
Querying Redshift#
The Redshift connector provides a schema for every Redshift schema.
You can see the available Redshift schemas by running SHOW SCHEMAS:
SHOW SCHEMAS FROM example;
If you have a Redshift 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 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 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#
Свойства конфигурации сопоставления типов#
Следующие свойства можно использовать для настройки того, как типы данных из подключенного источника данных сопоставляются с типами данных Trino и как метаданные кэшируются в Trino.
Имя свойства |
Описание |
Значение по умолчанию |
|---|---|---|
|
Настраивает обработку неподдерживаемых типов данных столбцов:
Соответствующее свойство сеанса каталога — |
|
|
Позволяет принудительно сопоставлять списки типов данных, разделенные
запятыми, с неограниченным |
SQL support#
The connector provides read access and write access to data and metadata in Redshift. 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, see also Ограничение DELETE
Управление схемами и таблицами, see also:
Нетранзакционный 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
Ограничение DELETE#
Если указано предложение WHERE, операция DELETE работает только в том
случае, если предикат в предложении может быть полностью протолкнут в источник
данных.
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
ALTER SCHEMA limitation#
The connector supports renaming a schema with the ALTER SCHEMA RENAME
statement. ALTER SCHEMA SET AUTHORIZATION is not supported.
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 Redshift.
query(varchar) -> table#
The query function allows you to query the underlying database directly. It
requires syntax native to Redshift, because the full query is pushed down and
processed in Redshift. This can be useful for accessing native features which
are not implemented in Trino or for improving query performance in situations
where running a query natively may be faster.
Нативный запрос, переданный базовому источнику данных, должен возвращать таблицу как набор результатов. Проверку и контроль безопасности для таких запросов выполняет только источник данных, используя собственную конфигурацию. Trino не выполняет эти задачи. Используйте транзитные запросы только для чтения данных.
For example, query the example catalog and select the top 10 nations by
population:
SELECT
*
FROM
TABLE(
example.system.query(
query => 'SELECT
TOP 10 *
FROM
tpch.nation
ORDER BY
population DESC'
)
);
Note
Движок запросов не сохраняет порядок результатов этой функции. Если переданный
запрос содержит предложение ORDER BY, результат функции может быть
упорядочен не так, как ожидается.
Performance#
The connector includes a number of performance improvements, detailed in the following sections.
Parallel read via S3#
The connector supports the Redshift UNLOAD command to transfer data to Parquet
files on S3. This enables parallel read of the data in Trino instead of the
default, single-threaded JDBC-based connection to Redshift, used by the
connector.
Configure the required S3 location with redshift.unload-location to enable the
parallel read. Parquet files are automatically removed with query completion.
The Redshift cluster and the configured S3 bucket must use the same AWS region.
Property value |
Description |
|---|---|
|
A writeable location in Amazon S3 in the same AWS region as the Redshift
cluster. Used for temporary storage during query processing using the
|
|
Optional. Fully specified ARN of the IAM Role attached to the Redshift
cluster to use for the |
Use the unload_enabled catalog session property to
deactivate the parallel read during a client session for a specific query, and
potentially re-activate it again afterward.
Additionally, define further required S3 configuration such as IAM key, role,
or region, except fs.native-s3.enabled,