SQL Server коннектор#

Примечание

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

The SQL Server connector allows querying and creating tables in an external Microsoft SQL Server database. This can be used to join data between different systems like SQL Server and Hive, or between two different SQL Server instances.

Requirements#

To connect to SQL Server, you need:

  • SQL Server 2012 or higher, or Azure SQL Database.

  • Network access from the Trino coordinator and workers to SQL Server. Port 1433 is the default port.

Configuration#

The connector can query a single database on a given SQL Server instance. Create a catalog properties file that specifies the SQL server connector by setting the connector.name to sqlserver.

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

connector.name=sqlserver
connection-url=jdbc:sqlserver://<host>:<port>;databaseName=<databaseName>;encrypt=false
connection-user=root
connection-password=secret

The connection-url defines the connection information and parameters to pass to the SQL Server JDBC driver. The supported parameters for the URL are available in the SQL Server 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#

The JDBC driver, and therefore the connector, automatically use Transport Layer Security (TLS) encryption and certificate validation. This requires a suitable TLS certificate configured on your SQL Server database host.

If you do not have the necessary configuration established, you can disable encryption in the connection string with the encrypt property:

connection-url=jdbc:sqlserver://<host>:<port>;databaseName=<databaseName>;encrypt=false

Further parameters like trustServerCertificate, hostNameInCertificate, trustStore, and trustStorePassword are details in the TLS section of SQL Server 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 SQL Server databases or servers#

The SQL Server connector can only access a single SQL Server database within a single catalog. Thus, if you have multiple SQL Server databases, or want to connect to multiple SQL Server instances, you must configure multiple instances of the SQL Server 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.

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

Название

Описание

Значение по умолчанию

case-insensitive-name-matching

Включить поддержку case insensitive идентификаторов.

false

case-insensitive-name-matching.cache-ttl

Время жизни закэшированных метаданных о case insensitive идентификаторах. Значение имеет тип {ref{prop-type-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.schemas.cache-ttl

Время жизни закэшированных имен схем. Положительное значение включает кэширование. Допустимо только, если параметр metadata.cache-ttl имеет положительное значение. Значение имеет тип {ref{prop-type-duration.

0 (кэширование отключено)

metadata.tables.cache-ttl

Время жизни закэшированных имен таблиц. Положительное значение включает кэширование. Допустимо только, если параметр metadata.cache-ttl имеет положительное значение. Значение имеет тип {ref{prop-type-duration.

0 (кэширование отключено)

metadata.cache-missing

Кэшировать ли информацию о том, что для используемых таблиц и колонок отсутствуют статистики. Включение данного параметра может ускорить планирование некоторых запросов. Однако, если информация об отсутствии статистик для конкретного объекта СУБД закэширована, но статистики стали доступны позднее (например, была запущена команда ANALYZE), CedrusData не сможет использовать статистики, пока не истечет время жизни закэшированной записи в соответствии с metadata.cache-ttl.

false

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.

Specific configuration properties#

The SQL Server connector supports additional catalog properties to configure the behavior of the connector and the issues queries to the database.

Property name

Description

sqlserver.snapshot-isolation.disabled

Control the automatic use of snapshot isolation for transactions issued by Trino in SQL Server. Defaults to false, which means that snapshot isolation is enabled.

Процедуры#

  • 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 SQL Server#

The SQL Server connector provides access to all schemas visible to the specified user in the configured database. For the following examples, assume the SQL Server catalog is example.

You can see the available schemas by running SHOW SCHEMAS:

SHOW SCHEMAS FROM example;

If you have a 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 query 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 SQL Server 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.

SQL Server type to Trino type mapping#

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

SQL Server type to Trino type mapping#

SQL Server database type

Trino type

Notes

BIT

BOOLEAN

TINYINT

SMALLINT

SQL Server TINYINT is actually unsigned TINYINT

SMALLINT

SMALLINT

INTEGER

INTEGER

BIGINT

BIGINT

DOUBLE PRECISION

DOUBLE

FLOAT[(n)]

REAL or DOUBLE

See Numeric type mapping

REAL

REAL

DECIMAL[(p[, s])], NUMERIC[(p[, s])]

DECIMAL(p, s)

CHAR[(n)]

CHAR(n)

1 <= n <= 8000

NCHAR[(n)]

CHAR(n)

1 <= n <= 4000

VARCHAR[(n | max)], NVARCHAR[(n | max)]

VARCHAR(n)

1 <= n <= 8000, max = 2147483647

TEXT

VARCHAR(2147483647)

NTEXT

VARCHAR(1073741823)

VARBINARY[(n | max)]

VARBINARY

1 <= n <= 8000, max = 2147483647

DATE

DATE

TIME[(n)]

TIME(n)

0 <= n <= 7

DATETIME2[(n)]

TIMESTAMP(n)

0 <= n <= 7

SMALLDATETIME

TIMESTAMP(0)

DATETIMEOFFSET[(n)]

TIMESTAMP(n) WITH TIME ZONE

0 <= n <= 7

Trino type to SQL Server type mapping#

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

Trino type to SQL Server type mapping#

Trino type

SQL Server type

Notes

BOOLEAN

BIT

TINYINT

TINYINT

Trino only supports writing values belonging to [0, 127]

SMALLINT

SMALLINT

INTEGER

INTEGER

BIGINT

BIGINT

REAL

REAL

DOUBLE

DOUBLE PRECISION

DECIMAL(p, s)

DECIMAL(p, s)

CHAR(n)

NCHAR(n) or NVARCHAR(max)

See Character type mapping

VARCHAR(n)

NVARCHAR(n) or NVARCHAR(max)

See Character type mapping

VARBINARY

VARBINARY(max)

DATE

DATE

TIME(n)

TIME(n)

0 <= n <= 7

TIMESTAMP(n)

DATETIME2(n)

0 <= n <= 7

Complete list of SQL Server data types.

Numeric type mapping#

For SQL Server FLOAT[(n)]:

  • If n is not specified maps to Trino Double

  • If 1 <= n <= 24 maps to Trino REAL

  • If 24 < n <= 53 maps to Trino DOUBLE

Character type mapping#

For Trino CHAR(n):

  • If 1 <= n <= 4000 maps SQL Server NCHAR(n)

  • If n > 4000 maps SQL Server NVARCHAR(max)

For Trino VARCHAR(n):

  • If 1 <= n <= 4000 maps SQL Server NVARCHAR(n)

  • If n > 4000 maps SQL Server NVARCHAR(max)

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

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

Название

Описание

Значение по умолчанию

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 SQL Server. 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

Fault-tolerant execution support#

The connector supports Fault-tolerant execution of query processing. Read and write operations are both supported with any retry policy.

Table functions#

The connector provides specific table functions to access SQL Server.

query(varchar) -> table#

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

Предупреждение

Нативный запрос, переданный в источник, должен возвращать набор записей (result set). CedrusData не осуществляет проверку доступа текущего пользователя к объектам источника, задействованным в нативном запросе. Используйте нативные запросы только для чтения данных.

For example, query the example catalog and select the top 10 percent of nations by population:

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        TOP(10) PERCENT *
      FROM
        tpch.nation
      ORDER BY
        population DESC'
    )
  );

procedure(varchar) -> table#

The procedure function allows you to run stored procedures on the underlying database directly. It requires syntax native to SQL Server, because the full query is pushed down and processed in SQL Server. In order to use this table function set sqlserver.experimental.stored-procedure-table-function-enabled to true.

Примечание

The procedure function does not support running StoredProcedures that return multiple statements, use a non-select statement, use output parameters, or use conditional statements.

Предупреждение

This feature is experimental only. The function has security implication and syntax might change and be backward incompatible.

The follow example runs the stored procedure employee_sp in the example catalog and the example_schema schema in the underlying SQL Server database:

SELECT
  *
FROM
  TABLE(
    example.system.procedure(
      query => 'EXECUTE example_schema.employee_sp'
    )
  );

If the stored procedure employee_sp requires any input append the parameter value to the procedure statement:

SELECT
  *
FROM
  TABLE(
    example.system.procedure(
      query => 'EXECUTE example_schema.employee_sp 0'
    )
  );

Примечание

Полиморфные табличные функции не сохраняют оригинальный порядок записей в результате запроса. Есть переданный запрос содержит запрос выражение ORDER BY, функция может вернуть записи в ином порядке. Для восстановления требуемого порядка используйте ORDER BY в запросе CedrusData.

Performance#

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

Пул соединений (connection pool)#

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

CedrusData создает по одному пулу соединений на каждого пользователя, который подключается к источнику:

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

  • Если вы используете Аутентификация в коннекторах от имени текущего пользователя, то будет создано по одному пулу на каждого активного пользователя CedrusData, но не более cedrusdata.jdbc.connection-pool.max-users. Создание большого количества соединений может негативно сказать на источнике. Мы рекомендуем вам провести нагрузочное тестирование, чтобы убедиться, что преимущества пула соединений перевешивают риски, при использовании совместно с аутентификацией в источнике от имени текущего пользователя.

Каждый пул может содержать до cedrusdata.jdbc.connection-pool.max-user-connections соединений.

Название

Описание

Значение по умолчанию

cedrusdata.jdbc.connection-pool.enabled

Использовать ли пул соединений при подключении к источнику.

false

cedrusdata.jdbc.connection-pool.max-users

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

100

cedrusdata.jdbc.connection-pool.max-user-connections

Максимальное количество подключений к источнику в рамках одного пула.

Равно количеству процессорных ядер

cedrusdata.jdbc.connection-pool.user-ttl

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

5m (пять минут)

cedrusdata.jdbc.connection-pool.connection-ttl

Как долго удерживать соединение открытым в случае отсутствия активности.

5m (пять минут)

Table statistics#

The SQL Server connector can use table and column statistics for cost based optimizations, to improve query processing performance based on the actual data in the data source.

The statistics are collected by SQL Server and retrieved by the connector.

The connector can use information stored in single-column statistics. SQL Server Database can automatically create column statistics for certain columns. If column statistics are not created automatically for a certain column, you can create them by executing the following statement in SQL Server Database.

CREATE STATISTICS example_statistics_name ON table_schema.table_name (column_name);

SQL Server Database routinely updates the statistics. In some cases, you may want to force statistics update (e.g. after defining new column statistics or after changing data in the table). You can do that by executing the following statement in SQL Server Database.

UPDATE STATISTICS table_schema.table_name;

Refer to SQL Server documentation for information about options, limitations and additional considerations.

Pushdown#

The connector supports pushdown for a number of operations:

Aggregate pushdown for the following functions:

Примечание

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

Cost-based join pushdown#

Коннектор поддерживает Join pushdown в режимах AUTOMATIC (значение по умолчанию) и EAGER.

В режиме AUTOMATIC коннектор принимает решение о join pushdown на основе предполагаемой стоимости запроса с и без join pushdown. Join pushdown происходит только тогда, когда доступные Table statistics позволяют предположить, что join pushdown приведет к улучшению производительности. Если статистики задействованных таблиц и колонок недоступны, join pushdown не будет произведен, чтобы избежать потенциального ухудшения производительности.

В режиме EAGER join pushdown происходит всегда, когда это допустимо коннектором с точки зрения корректности, даже если соответствующие статистики недоступны. Использование режима EAGER рекомендовано только для тестирования и отладки.

Таблица ниже содержит параметры конфигурации, относящиеся к cost-based join pushdown:

Название

Описание

Значение по умолчанию

join-pushdown.enabled

Разрешать :ref:join pushdown <join-pushdown> или нет. Параметр сессии: join_pushdown_enabled.

true

join-pushdown.strategy

Стратегия принятия решения о join pushdown. Допустимые значения: AUTOMATIC, EAGER.

AUTOMATIC

Predicate pushdown support#

The connector supports pushdown of predicates on VARCHAR and NVARCHAR columns if the underlying columns in SQL Server use a case-sensitive collation.

The following operators are pushed down:

  • =

  • <>

  • IN

  • NOT IN

To ensure correct results, operators are not pushed down for columns using a case-insensitive collation.

Bulk insert#

You can optionally use the bulk copy API to drastically speed up write operations.

Enable bulk copying and a lock on the destination table to meet minimal logging requirements.

The following table shows the relevant catalog configuration properties and their default values:

Bulk load properties#

Property name

Description

Default

sqlserver.bulk-copy-for-write.enabled

Use the SQL Server bulk copy API for writes. The corresponding catalog session property is bulk_copy_for_write.

false

sqlserver.bulk-copy-for-write.lock-destination-table

Obtain a bulk update lock on the destination table for write operations. The corresponding catalog session property is bulk_copy_for_write_lock_destination_table. Setting is only used when bulk-copy-for-write.enabled=true.

false

Limitations:

  • Column names with leading and trailing spaces are not supported.

Data compression#

You can specify the data compression policy for SQL Server tables with the data_compression table property. Valid policies are NONE, ROW or PAGE.

Example:

CREATE TABLE example_schema.scientists (
  recordkey VARCHAR,
  name VARCHAR,
  age BIGINT,
  birthday DATE
)
WITH (
  data_compression = 'ROW'
);