Запрос данных в Azure Synapse Analytics

Это важно

Устаревшая документация по федерации запросов была снята с употребления и возможно, больше не будет обновляться. Продукты, услуги или технологии, упомянутые в этом контенте, официально не поддерживаются или проверяются Databricks. См. раздел "Что такое федерация Lakehouse?".

Доступ к Azure Synapse из Azure Databricks можно получить с помощью соединителя Azure Synapse, который использует инструкцию COPY в Azure Synapse для эффективной передачи больших объемов данных между кластером Azure Databricks и экземпляром Azure Synapse с помощью учетной записи хранения Azure Data Lake Storage для временного промежуточного хранения.

Это важно

Конфигурации, описанные в этой статье, являются экспериментальными. Экспериментальные функции предоставляются в имеющемся виде и не поддерживаются Databricks в рамках технической поддержки клиентов. Чтобы получить полную поддержку федерации запросов, следует использовать Lakehouse Federation, которая позволяет пользователям Azure Databricks воспользоваться синтаксисом Unity Catalog и средствами управления данными.

Azure Synapse Analytics — это облачное хранилище корпоративных данных, которое использует массовую параллельную обработку (MPP) для быстрого выполнения сложных запросов в петабайтах данных.

Это важно

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

Примечание.

COPY доступна только в экземплярах Azure Data Lake Storage. Если вы ищете подробные сведения о работе с Polybase, см . статью "Подключение Azure Databricks и Azure Synapse с PolyBase (устаревшая версия)".

Пример синтаксиса для Synapse

Synapse можно запросить с помощью Scala, Python, SQL и R. В следующих примерах кода используются ключи учетной записи хранения, и учетные данные хранения перенаправляются из Azure Databricks в Synapse.

Примечание.

Используйте строку подключения, предоставленную порталом Azure, которая обеспечивает шифрование протокола SSL для всех данных, отправленных между драйвером Spark и экземпляром Azure Synapse через подключение JDBC. Чтобы убедиться, что шифрование SSL включено, найдите подстроку encrypt=true в строке подключения.

Это важно

Внешние расположения, определенные в Unity Catalog, не поддерживаются в качестве tempDir расположений.

Databricks рекомендует использовать самый безопасный поток проверки подлинности. Поток проверки подлинности, описанный в этом примере, несет риски, которые отсутствуют в других потоках. Этот поток следует использовать только в том случае, если другие более безопасные потоки, такие как управляемые удостоверения, не являются осуществимыми.

Scala

// Set up the storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

// Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 11.3 LTS and above.
val df: DataFrame = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") /* Optional - will use default port 1433 if not specified. */
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") /* If schemaName not provided, default to "dbo". */
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

// Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .load()

// Load data from an Azure Synapse query.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("query", "select x, count(*) as cnt from table group by x")
  .load()

// Apply some transformations to the data, then use the
// Data Source API to write the data back to another table in Azure Synapse.

df.write
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .save()

Питон

# Set up the storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

# Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 11.3 LTS and above.
df = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") # Optional - will use default port 1433 if not specified.
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") # If schemaName not provided, default to "dbo".
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

# Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
df = spark.read \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("dbTable", "<your-table-name>") \
  .load()

# Load data from an Azure Synapse query.
df = spark.read \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("query", "select x, count(*) as cnt from table group by x") \
  .load()

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse.

df.write \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("dbTable", "<your-table-name>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .save()

SQL

-- Set up the storage account access key in the notebook session conf.
SET fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net=<your-storage-account-access-key>;

-- Read data using SQL. The following example applies to Databricks Runtime 11.3 LTS and above.
CREATE TABLE example_table_in_spark_read
USING sqldw
OPTIONS (
  host '<hostname>',
  port '<port>' /* Optional - will use default port 1433 if not specified. */
  user '<username>',
  password '<password>',
  database '<database-name>'
  dbtable '<schema-name>.<table-name>', /* If schemaName not provided, default to "dbo". */
  forwardSparkAzureStorageCredentials 'true',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Read data using SQL. The following example applies to Databricks Runtime 10.4 LTS and below.
CREATE TABLE example_table_in_spark_read
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbtable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Write data using SQL.
-- Create a new table, throwing an error if a table with the same name already exists:

CREATE TABLE example_table_in_spark_write
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbTable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
)
AS SELECT * FROM table_to_save_in_spark;

Р

# Load SparkR
library(SparkR)

# Set up the storage account access key in the notebook session conf.
conf <- sparkR.callJMethod(sparkR.session(), "conf")
sparkR.callJMethod(conf, "set", "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net", "<your-storage-account-access-key>")

# Get some data from an Azure Synapse table.
df <- read.df(
   source = "com.databricks.spark.sqldw",
   url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
   forward_spark_azure_storage_credentials = "true",
   dbTable = "<your-table-name>",
   tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

# Load data from an Azure Synapse query.
df <- read.df(
   source = "com.databricks.spark.sqldw",
   url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
   forward_spark_azure_storage_credentials = "true",
   query = "select x, count(*) as cnt from table group by x",
   tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse.

write.df(
  df,
  source = "com.databricks.spark.sqldw",
  url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
  forward_spark_azure_storage_credentials = "true",
  dbTable = "<your-table-name>",
  tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

Как работает проверка подлинности между Azure Databricks и Synapse?

Соединитель Azure Synapse использует три типа сетевых подключений:

• Драйвер Spark для Azure Synapse
• Кластер Spark в учетную запись хранения Azure
• Из Azure Synapse в учетную запись хранения Azure

Настройка доступа к хранилищу Azure

Azure Databricks и Synapse нуждаются в привилегированном доступе к учетной записи хранения Azure для временного хранения данных.

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

• Используйте ключ учетной записи и секрет для учетной записи хранения и установите forwardSparkAzureStorageCredentials в true. Сведения о настройке учетных данных Azure для доступа к хранилищу Azure см. в разделе "Настройка свойств Spark".
• Используйте Azure Data Lake Storage с проверкой подлинности OAuth 2.0 и задайте для enableServicePrincipalAuth значение true. См. Руководство по настройке подключения из Azure Databricks к Synapse с использованием OAuth 2.0 и учетной записи службы.
• Настройте экземпляр Azure Synapse, чтобы он имел управляемую учетную запись службы, и установите useAzureMSI на true.

Обязательные разрешения Azure Synapse

Поскольку Azure Synapse использует COPY в фоновом режиме, соединитель Azure Synapse требует, чтобы пользователь подключения JDBC имел разрешение на выполнение следующих команд в подключенном экземпляре Azure Synapse:

• COPY INTO

Если целевая таблица не существует в Azure Synapse, в дополнение к приведенной выше команде необходимо разрешение на выполнение следующей команды:

• CREATE TABLE

В следующей таблице приведены сведения о разрешениях, необходимых для записи с COPY:

Разрешения (вставка в существующую таблицу)	Разрешения (вставка в новую таблицу)
УПРАВЛЕНИЕ МАССОВЫМИ ОПЕРАЦИЯМИ С БАЗОЙ ДАННЫХ INSERT	УПРАВЛЕНИЕ МАССОВЫМИ ОПЕРАЦИЯМИ С БАЗОЙ ДАННЫХ INSERT CREATE TABLE ИЗМЕНИТЬ НА SCHEMA :: dbo

Конфигурации сети

Если вы настроите брандмауэр в Azure Synapse, необходимо настроить параметры сети, чтобы разрешить Azure Databricks достичь Azure Synapse. Сначала убедитесь, что рабочая область Azure Databricks развернута в вашей собственной виртуальной сети, следуя инструкции Развертывание Azure Databricks в виртуальной сети Azure (интеграция VNet). Затем можно настроить правила брандмауэра IP-адресов в Azure Synapse, чтобы разрешить подключения из ваших подсетей к вашей учетной записи Synapse. См. правила IP-брандмауэра Azure Synapse Analytics.

Настройка подключения из Azure Databricks к Synapse с помощью OAuth 2.0 с учетной записью службы

Вы можете аутентифицироваться в Azure Synapse Analytics с помощью учетной записи службы с доступом к базовому хранилищу. Дополнительные сведения об использовании учетных данных субъекта-службы для доступа к учетной записи хранения Azure см. в разделе Подключение к Azure Data Lake Storage и хранилищу BLOB-объектов. Чтобы настроить соединитель на проверку подлинности с помощью субъекта-службы, необходимо задать параметр enableServicePrincipalAuth на true в справочнике параметров конфигурации соединения Azure Databricks Synapse.

Вы можете опционально использовать другой служебный принципал для соединения с Azure Synapse Analytics. В следующем примере настраиваются учетные данные служебного субъекта для учетной записи хранения и необязательные учетные данные служебного субъекта для Synapse.

ini

; Defining the Service Principal credentials for the Azure storage account
fs.azure.account.auth.type OAuth
fs.azure.account.oauth.provider.type org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider
fs.azure.account.oauth2.client.id <application-id>
fs.azure.account.oauth2.client.secret <service-credential>
fs.azure.account.oauth2.client.endpoint https://login.microsoftonline.com/<directory-id>/oauth2/token

; Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.databricks.sqldw.jdbc.service.principal.client.id <application-id>
spark.databricks.sqldw.jdbc.service.principal.client.secret <service-credential>

Scala

// Defining the Service Principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<application-id>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<service-credential>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<directory-id>/oauth2/token")

// Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

Питон

# Defining the service principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<application-id>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<service-credential>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<directory-id>/oauth2/token")

# Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

Р

# Load SparkR
library(SparkR)
conf <- sparkR.callJMethod(sparkR.session(), "conf")

# Defining the service principal credentials for the Azure storage account
sparkR.callJMethod(conf, "set", "fs.azure.account.auth.type", "OAuth")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.id", "<application-id>")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.secret", "<service-credential>")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<directory-id>/oauth2/token")

# Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

Поддерживаемые режимы сохранения для пакетной записи

Соединитель Azure Synapse поддерживает режимы сохранения ErrorIfExists, Ignore, Append и Overwrite, по умолчанию используя режим ErrorIfExists. Дополнительные сведения о поддерживаемых режимах сохранения в Apache Spark см. в статье документация Spark SQL по режимам сохранения.

Справочник по параметрам соединителя Azure Databricks Synapse

Предоставленные OPTIONS в Spark SQL поддерживают следующие параметры:

Параметр	Обязательно	По умолчанию	Примечания.
dbTable	Да, если не указан параметр query	Нет по умолчанию	Таблица для создания или чтения данных из Azure Synapse. Этот параметр является обязательным при сохранении (записи) данных обратно в Azure Synapse. Для доступа к таблице в определенной схеме также можно использовать {SCHEMA NAME}.{TABLE NAME}. Если имя схемы не указано, используется схема по умолчанию, связанная с пользователем JDBC. Ранее поддерживавшийся вариант dbtable является нерекомендуемым и в будущих выпусках будет игнорироваться. Используйте вместо этого имя в стиле camelCase.
query	Да, если не указан параметр dbTable	Нет по умолчанию	Запрос для чтения данных из Azure Synapse. Для доступа к таблицам в определенной схеме, упоминаемым в запросе, также можно использовать {SCHEMA NAME}.{TABLE NAME}. Если имя схемы не указано, используется схема по умолчанию, связанная с пользователем JDBC.
user	нет	Нет по умолчанию	Имя пользователя Azure Synapse. Используется в сочетании с параметром password. Можно использовать только в том случае, если имя пользователя и пароль не передаются в URL-адресе. Если оба параметра передаются, произойдет ошибка.
password	нет	Нет по умолчанию	Пароль Azure Synapse. Используется в сочетании с параметром user. Можно использовать только в том случае, если имя пользователя и пароль не передаются в URL-адресе. Если оба параметра передаются, произойдет ошибка.
url	Да	Нет по умолчанию	URL-адрес JDBC, где в качестве подпротокола указан sqlserver. Рекомендуется использовать строку подключения с портала Azure. Параметр encrypt=true настоятельно рекомендуется, так как он включает шифрование SSL подключения JDBC. Если параметры user и password заданы отдельно, их не нужно включать в URL-адрес.
jdbcDriver	нет	Определяется подпротоколом URL-адреса JDBC.	Имя класса используемого драйвера JDBC. Этот класс должен находиться в classpath. В большинстве случаев указывать этот параметр нет необходимости, так как имя класса соответствующего драйвера должно автоматически определяться подпротоколом в URL-адресе JDBC. Ранее поддерживавшийся вариант jdbc_driver является нерекомендуемым и в будущих выпусках будет игнорироваться. Используйте вместо этого имя в стиле camelCase.
tempDir	Да	Нет по умолчанию	URI abfss. Мы рекомендуем использовать выделенный контейнер хранилища BLOB для Azure Synapse. Ранее поддерживавшийся вариант tempdir является нерекомендуемым и в будущих выпусках будет игнорироваться. Используйте вместо этого имя в стиле camelCase. Нельзя использовать внешнее расположение, определенное в каталоге Unity, в качестве tempDir расположения.
tempCompression	нет	SNAPPY	Алгоритм сжатия, используемый для кодирования и декодирования временных файлов как в Spark, так и в Azure Synapse. В настоящее время поддерживаются значения UNCOMPRESSED, SNAPPY и GZIP.
forwardSparkAzureStorageCredentials	нет	неправда	Если true, библиотека автоматически обнаруживает учетные данные ключа доступа учетной записи хранения, которые Spark использует для подключения к контейнеру хранилища BLOB-объектов, и перенаправляет эти учетные данные в Azure Synapse через JDBC. Эти учетные данные отправляются в запросе JDBC. Поэтому при использовании этого параметра настоятельно рекомендуется включить для подключения JDBC шифрование SSL. При настройке проверки подлинности хранилища необходимо задать значение useAzureMSI точно для одного из forwardSparkAzureStorageCredentials или true. Кроме того, можно установить enableServicePrincipalAuth на true и использовать служебный принципал для аутентификации и JDBC, и хранилища. Этот forwardSparkAzureStorageCredentials параметр не поддерживает проверку подлинности для хранилища с помощью управляемого служебного удостоверения или учётной записи службы. Поддерживается только ключ доступа к учетной записи хранения. Ранее поддерживавшийся вариант forward_spark_azure_storage_credentials является нерекомендуемым и в будущих выпусках будет игнорироваться. Используйте вместо этого имя в стиле camelCase.
useAzureMSI	нет	неправда	Если указано значение true, библиотека будет указывать IDENTITY = 'Managed Service Identity' и не будет указывать SECRET для создаваемых ею учетных данных с областью базы данных. При настройке проверки подлинности хранилища необходимо задать значение useAzureMSI точно для одного из forwardSparkAzureStorageCredentials или true. Кроме того, можно задать enableServicePrincipalAuthtrue и использовать субъект-службу для проверки подлинности JDBC и хранилища.
enableServicePrincipalAuth	нет	неправда	Если задано значение true, библиотека будет использовать предоставленные учетные данные служебного принципала для подключения к хранилищу Azure и Azure Synapse Analytics через JDBC. Если либо forward_spark_azure_storage_credentials, либо useAzureMSI установлены в true, этот параметр будет иметь приоритет над учетной записью службы при проверке подлинности хранилища.
tableOptions	нет	CLUSTERED COLUMNSTORE INDEX, DISTRIBUTION = ROUND_ROBIN	Строка, используемая для указания параметров таблицы при создании таблицы Azure Synapse, заданной с помощью dbTable. Эта строка передается в качестве литерала в часть WITH инструкции SQL CREATE TABLE, которая направляется в Azure Synapse. Ранее поддерживавшийся вариант table_options является нерекомендуемым и в будущих выпусках будет игнорироваться. Используйте вместо этого имя в стиле camelCase.
preActions	нет	Без значения по умолчанию (пустая строка)	Разделенный символом ; список команд SQL, которые должны быть выполнены в Azure Synapse перед записью данных в экземпляр Azure Synapse. Эти команды SQL должны быть допустимыми командами, которые принимает Azure Synapse. Если какая-либо из этих команд завершается ошибкой, она обрабатывается как ошибка, а операция записи не выполняется.
postActions	нет	Без значения по умолчанию (пустая строка)	Разделенный символом ; список команд SQL, которые должны быть выполнены в Azure Synapse после того, как соединитель успешно запишет данные в экземпляр Azure Synapse. Эти команды SQL должны быть допустимыми командами, которые принимает Azure Synapse. Если какая-либо из этих команд завершается ошибкой, она обрабатывается как ошибка, и после успешной записи данных в экземпляр Azure Synapse возникает исключение.
maxStrLength	нет	256	StringType в Spark сопоставляется с типом NVARCHAR(maxStrLength) в Azure Synapse. Можно использовать maxStrLength, чтобы задать длину строки для всех столбцов типа NVARCHAR(maxStrLength), которые находятся в таблице с именем dbTable в Azure Synapse. Ранее поддерживавшийся вариант maxstrlength является нерекомендуемым и в будущих выпусках будет игнорироваться. Используйте вместо этого имя в стиле camelCase.
applicationName	нет	Databricks-User-Query	Тег соединения для каждого запроса. Если значение не указано или является пустой строкой, в значение тега по умолчанию добавляется URL-адрес JDBC. Значение по умолчанию предотвращает выдачу средством мониторинга Azure DB ложных предупреждений об атаках путем внедрения SQL-кода.
maxbinlength	нет	Нет по умолчанию	Управляйте длиной столбцов BinaryType. Этот параметр преобразуется в VARBINARY(maxbinlength).
identityInsert	нет	неправда	Если задано значение true, активируется режим IDENTITY_INSERT, в результате чего указанное в DataFrame значение вставляется в столбец IDENTITY таблицы Azure Synapse. См. раздел Явная вставка значений в столбец IDENTITY.
externalDataSource	нет	Нет по умолчанию	Предварительно подготовленный внешний источник данных для чтения данных из Azure Synapse. Внешний источник данных можно использовать только с PolyBase, и это устраняет необходимость в разрешении CONTROL, поскольку соединителю не нужно создавать ни учётные данные с областью действия, ни внешний источник данных для загрузки данных. Пример использования и список разрешений, необходимых при использовании внешнего источника данных, см. в разделе Необходимые разрешения Azure Synapse для PolyBase с внешним источником данных.
maxErrors	нет	0	Максимальное количество строк, которые могут быть отклонены во время операций чтения и записи перед отменой операции загрузки. Отклоненные строки будут игнорироваться. Например, если в двух из десяти записей есть ошибки, обрабатываются только восемь записей. См. документацию REJECT_VALUE в CREATE EXTERNAL TABLE и MAXERRORS в COPY.
inferTimestampNTZType	нет	неправда	Если true значения типа Azure Synapse TIMESTAMP интерпретируются как TimestampNTZType (метка времени без часового пояса) во время чтения. В противном случае, все метки времени интерпретируются как TimestampType, независимо от типа в базовой таблице Azure Synapse.

Примечание.

• Параметры tableOptions, preActions, postActions и maxStrLength нужны только при записи данных из Azure Databricks в новую таблицу в Azure Synapse.
• Хотя все имена параметров источника данных нечувствительны к регистру, для ясности рекомендуется указывать их в формате «camel case», то есть с маленькой первой буквой и заглавными буквами для последующих слов.

Оптимизация выполнения запросов в Azure Synapse

Соединитель Azure Synapse реализует набор правил оптимизации для отправки указанных ниже операторов в Azure Synapse.

• Filter
• Project
• Limit

Операторы Project и Filter поддерживают следующие выражения:

• Большинство булевых логических операторов
• Сравнения
• Простые арифметические операции
• Приведение числовых и строковых типов

Для оператора Limit pushdown поддерживается только в том случае, если порядок не указан. Рассмотрим пример.

SELECT TOP(10) * FROM table, но не SELECT TOP(10) * FROM table ORDER BY col.

Примечание.

Соединитель Azure Synapse не передает выражения, работающие со строками, датами или отметками времени.

Параметр pushdown для передачи запросов, созданных с помощью соединителя Azure Synapse, включен по умолчанию. Ее можно отключить, задав для параметра spark.databricks.sqldw.pushdown значение false.

Управление временными данными

Соединитель Azure Synapse не удаляет временные файлы, создаваемые в контейнере хранилища Azure. Databricks рекомендует периодически удалять временные файлы в месте, указанном пользователем tempDir.

Чтобы упростить очистку данных, соединитель Azure Synapse не сохраняет файлы данных непосредственно в tempDir, а создает подкаталог вида <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. Вы можете настроить периодические задания (с помощью функции заданий Azure Databricks или иным способом) для рекурсивного удаления всех подкаталогов, которые старше заданного порогового значения (например, 2 дней), в предположении, что задания Spark не могут выполняться дольше этого порогового значения.

Более простая альтернатива — периодическое удаление всего контейнера и создание нового с тем же именем. Для этого необходимо использовать выделенный контейнер для временных данных, создаваемых соединителем Azure Synapse, и найти интервал времени, в течение которого запросы с участием соединителя гарантированно не будут выполняться.

Управление временными объектами

Соединитель Azure Synapse автоматизирует обмен данными между кластером Azure Databricks и экземпляром Azure Synapse. Для чтения данных из таблицы или запроса Azure Synapse или записи данных в таблицу Azure Synapse соединитель Azure Synapse в фоновом режиме создает временные объекты, включая DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCE, EXTERNAL FILE FORMAT и EXTERNAL TABLE. Эти объекты живут только в течение соответствующего задания Spark и автоматически удаляются.

Если в кластере выполняется запрос с использованием соединителя Azure Synapse, то в случае, если процесс драйвера Spark завершается сбоем или принудительно перезапускается либо кластер принудительно завершается или перезапускается, временные объекты могут быть не удалены. Чтобы эти объекты было удобно идентифицировать и удалять вручную, соединитель Azure Synapse добавляет в начало имен всех промежуточных временных объектов, создаваемых в экземпляре Azure Synapse, тег в таком формате: tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject>.

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

• SELECT * FROM sys.database_scoped_credentials WHERE name LIKE 'tmp_databricks_%'
• SELECT * FROM sys.external_data_sources WHERE name LIKE 'tmp_databricks_%'
• SELECT * FROM sys.external_file_formats WHERE name LIKE 'tmp_databricks_%'
• SELECT * FROM sys.external_tables WHERE name LIKE 'tmp_databricks_%'