Snowflake connector

The Snowflake connector allows querying and creating tables in an external Snowflake account. This can be used to join data between different systems like Snowflake and Hive, or between two different Snowflake accounts.

Configuration

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

connector.name=snowflake
connection-url=jdbc:snowflake://<account>.snowflakecomputing.com
connection-user=root
connection-password=secret
snowflake.account=account
snowflake.database=database
snowflake.role=role
snowflake.warehouse=warehouse

The Snowflake connector uses Apache Arrow as the serialization format when reading from Snowflake. Add the following required, additional JVM argument to the JVM config:

--add-opens=java.base/java.nio=ALL-UNNAMED
--sun-misc-unsafe-memory-access=allow

Multiple Snowflake databases or accounts

The Snowflake connector can only access a single database within a Snowflake account. Thus, if you have multiple Snowflake databases, or want to connect to multiple Snowflake accounts, you must configure multiple instances of the Snowflake connector.

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

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

Имя свойства	Описание
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 можно использовать для изменения значения по умолчанию 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 Snowflake 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.

List of Snowflake data types.

Snowflake type to Trino type mapping

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

Snowflake type to Trino type mapping

Snowflake type	Trino type	Notes
BOOLEAN	BOOLEAN
INT, INTEGER, BIGINT, SMALLINT, TINYINT, BYTEINT	DECIMAL(38,0)	Synonymous with NUMBER(38,0). See Snowflake data types for fixed point numbers for more information.
FLOAT, FLOAT4, FLOAT8	DOUBLE	The names FLOAT, FLOAT4, and FLOAT8 are for compatibility with other systems; Snowflake treats all three as 64-bit floating-point numbers. See Snowflake data types for floating point numbers for more information.
DOUBLE, DOUBLE PRECISION, REAL	DOUBLE	Synonymous with FLOAT. See Snowflake data types for floating point numbers for more information.
NUMBER	DECIMAL	Default precision and scale are (38,0).
DECIMAL, NUMERIC	DECIMAL	Synonymous with NUMBER. See Snowflake data types for fixed point numbers for more information.
VARCHAR	VARCHAR
CHAR, CHARACTER	VARCHAR	Synonymous with VARCHAR except default length is VARCHAR(1). See Snowflake String & Binary Data Types for more information.
STRING, TEXT	VARCHAR	Synonymous with VARCHAR. See Snowflake String & Binary Data Types for more information.
BINARY	VARBINARY
VARBINARY	VARBINARY	Synonymous with BINARY. See Snowflake String & Binary Data Types for more information.
DATE	DATE
TIME	TIME
TIMESTAMP_NTZ	TIMESTAMP	TIMESTAMP with no time zone; time zone, if provided, is not stored. See Snowflake Date & Time Data Types for more information.
DATETIME	TIMESTAMP	Alias for TIMESTAMP_NTZ. See Snowflake Date & Time Data Types for more information.
TIMESTAMP	TIMESTAMP	Alias for one of the TIMESTAMP variations (TIMESTAMP_NTZ by default). This connector always sets TIMESTAMP_NTZ as the variant.
TIMESTAMP_TZ	TIMESTAMP WITH TIME ZONE	TIMESTAMP with time zone.

No other types are supported.

Trino type to Snowflake type mapping

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

Trino type to Snowflake type mapping

Trino type	Snowflake type	Notes
BOOLEAN	BOOLEAN
TINYINT	NUMBER(3, 0)
SMALLINT	NUMBER(5, 0)
INTEGER	NUMBER(10, 0)
BIGINT	NUMBER(19, 0)
REAL	DOUBLE
DOUBLE	DOUBLE
DECIMAL	NUMBER
VARCHAR	VARCHAR
CHAR	VARCHAR
VARBINARY	BINARY
VARBINARY	VARBINARY
DATE	DATE
TIME	TIME
TIMESTAMP	TIMESTAMP_NTZ
TIMESTAMP WITH TIME ZONE	TIMESTAMP_TZ

No other types are supported.

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

Следующие свойства можно использовать для настройки того, как типы данных из подключенного источника данных сопоставляются с типами данных 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 and write access to data and metadata in a Snowflake database. In addition to the globally available and read operation statements, the connector supports the following features:

• INSERT, see also Нетранзакционный INSERT

• DELETE

• TRUNCATE

• CREATE TABLE

• CREATE TABLE AS

• DROP TABLE

• ALTER TABLE

• CREATE SCHEMA

• DROP SCHEMA

• Procedures

• Table functions

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

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

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

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

query(varchar) -> table

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

Find details about the SQL support of Snowflake that you can use in the query in the Snowflake SQL Command Reference, including PIVOT, lateral joins and other statements and functions.

Нативный запрос, переданный базовому источнику данных, должен возвращать таблицу как набор результатов. Проверку и контроль безопасности для таких запросов выполняет только источник данных, используя собственную конфигурацию. 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 Snowflake SQL support for PIVOT to pivot on all distinct column values automatically with a dynamic pivot.

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => '
        SELECT *
        FROM quarterly_sales
          PIVOT(SUM(amount) FOR quarter IN (ANY ORDER BY quarter))
        ORDER BY empid;
      '
    )
  );

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:

• Проталкивание limit

• Проталкивание Top-N

Aggregate pushdown for the following functions:

• avg()

• count()

• max()

• min()

• sum()

• stddev()

• stddev_pop()

• stddev_samp()

• variance()

• var_pop()

• var_samp()

• covar_pop()

• covar_samp()

• corr()

• regr_intercept()

• regr_slope()

Note

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