Abfragen von Daten in Azure Synapse Analytics

Sie können über Azure Databricks über den Azure Synapse-Connector auf Azure Synapse zugreifen, der die COPY Anweisung in Azure Synapse verwendet, um große Datenmengen effizient zwischen einem Azure Databricks-Cluster und einer Azure Synapse-Instanz mithilfe eines Azure Data Lake Storage-Speicherkontos für die temporäre Staging zu übertragen.

Von Bedeutung

Die Legacy-Abfrageverbunddokumentation wurde eingestellt und kann nicht aktualisiert werden. Die in diesem Inhalt genannten Konfigurationen werden nicht offiziell von Databricks unterstützt oder getestet. Wenn Lakehouse Federation Ihre Quelldatenbank unterstützt, empfiehlt Databricks stattdessen die Verwendung.

Azure Synapse Analytics ist ein cloudbasiertes Enterprise Data Warehouse, das massive parallele Verarbeitung (MPP) nutzt, um komplexe Abfragen in Petabyte-Daten schnell auszuführen.

Von Bedeutung

Dieser Connector dient nur zur Verwendung mit Synapse Dedicated Pool-Instanzen und ist nicht mit anderen Synapse-Komponenten kompatibel.

Hinweis

COPY ist nur für Azure Data Lake Storage-Instanzen verfügbar. Wenn Sie nach Details zur Arbeit mit Polybase suchen, lesen Sie "Verbinden von Azure Databricks und Azure Synapse mit PolyBase (Legacy)".

Beispielsyntax für Synapse

Sie können Synapse in Scala, Python, SQL und R abfragen. Die folgenden Codebeispiele verwenden Speicherkontoschlüssel und leiten die Speicheranmeldeinformationen von Azure Databricks an Synapse weiter.

Hinweis

Verwenden Sie die vom Azure-Portal bereitgestellte Verbindungszeichenfolge, die die Verschlüsselung per Secure Sockets Layer (SSL) für alle Daten ermöglicht, die zwischen dem Spark-Treiber und der Azure Synapse-Instanz über die JDBC-Verbindung gesendet werden. Ob die SSL-Verschlüsselung aktiviert ist, können Sie überprüfen, indem Sie in der Verbindungszeichenfolge nach encrypt=true suchen.

Von Bedeutung

Externe Speicherorte, die im Unity-Katalog definiert sind, werden nicht als tempDir Speicherorte unterstützt.

Databricks empfiehlt, den sichersten Authentifizierungsflow zu verwenden. Der in diesem Beispiel beschriebene Authentifizierungsfluss trägt Risiken, die in anderen Flüssen nicht vorhanden sind. Sie sollten diesen Flow nur verwenden, wenn andere sicherere Flows, z. B. verwaltete Identitäten, nicht praktikabel sind.

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()

Python

# 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;

R

# 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>")

Wie funktioniert die Authentifizierung zwischen Azure Databricks und Synapse?

Für den Azure Synapse-Connector werden drei Arten von Netzwerkverbindungen verwendet:

• Spark-Treiber mit Azure Synapse
• Spark-Cluster zu Azure-Speicherkonto
• Azure Synapse für das Azure-Speicherkonto

Konfigurieren des Zugriffs auf Azure Storage

Sowohl Azure Databricks als auch Synapse benötigen privilegierten Zugriff auf ein Azure-Speicherkonto, das für die temporäre Datenspeicherung verwendet werden soll.

Azure Synapse unterstützt die Verwendung von SAS für den Zugriff auf Speicherkonten nicht. Sie können den Zugriff für beide Dienste konfigurieren, indem Sie eine der folgenden Aktionen ausführen:

• Verwenden Sie den Kontoschlüssel und den geheimen Schlüssel für das Speicherkonto, und legen Sie forwardSparkAzureStorageCredentials auf true fest. Siehe "Spark-Eigenschaften festlegen", um Azure-Anmeldeinformationen für den Zugriff auf Azure Storage zu konfigurieren.
• Verwenden Sie Azure Data Lake Storage mit OAuth 2.0-Authentifizierung, und legen Sie sie enableServicePrincipalAuth auf truefest. Siehe Konfigurieren der Verbindung von Azure Databricks zu Synapse mit OAuth 2.0 mit einem Dienstprinzipal.
• Konfigurieren Sie Ihre Azure Synapse-Instanz so, dass sie über eine verwaltete Dienstidentität verfügt, und setzen Sie useAzureMSI auf true.

Erforderliche Azure Synapse-Berechtigungen

Da COPY im Hintergrund verwendet wird, erfordert der Azure Synapse-Connector, dass der Benutzer der JDBC-Verbindung über die Berechtigung zum Ausführen der folgenden Befehle in der verbundenen Azure Synapse-Instanz verfügt:

• COPY INTO

Wenn die Zieltabelle in der Azure Synapse-Instanz nicht vorhanden ist, ist zusätzlich zum obigen Befehl die Berechtigung zum Ausführen des folgenden Befehls erforderlich:

• CREATE TABLE

In der folgenden Tabelle sind die Berechtigungen zusammengefasst, die für Schreibvorgänge erforderlich sind:COPY

Berechtigungen (in eine vorhandene Tabelle einfügen)	Berechtigungen (in eine neue Tabelle einfügen)
VERWALTEN VON MASSENVORGÄNGEN FÜR DATENBANKEN INSERT	VERWALTEN VON MASSENVORGÄNGEN FÜR DATENBANKEN INSERT CREATE TABLE ALTER ON SCHEMA :: dbo

Netzwerkkonfigurationen

Wenn Sie eine Firewall in Azure Synapse konfigurieren, müssen Sie Netzwerkeinstellungen konfigurieren, damit Azure Databricks Azure Synapse erreichen kann. Stellen Sie zunächst sicher, dass Ihr Azure Databricks-Arbeitsbereich in Ihrem eigenen virtuellen Netzwerk bereitgestellt wird, nachdem Sie Azure Databricks in Ihrem virtuellen Azure-Netzwerk (VNet Injection) bereitstellen. Anschließend können Sie IP-Firewallregeln in Azure Synpase konfigurieren, um Verbindungen von Ihren Subnetzen zu Ihrem Synapse-Konto zuzulassen. Siehe Azure Synapse Analytics IP-Firewallregeln.

Konfigurieren Sie die Verbindung von Azure Databricks zu Synapse mit OAuth 2.0 und einem Dienstprinzipal

Sie können sich bei Azure Synapse Analytics mit einem Dienstprinzipal mit Zugriff auf das zugrunde liegende Speicherkonto authentifizieren. Weitere Informationen zur Verwendung von Anmeldeinformationen für Dienstprinzipale zum Zugriff auf ein Azure-Speicherkonto finden Sie in Herstellen einer Verbindung mit Azure Data Lake Storage und Blob Storage. Sie müssen die enableServicePrincipalAuth Option true in der Verbindungskonfiguration festlegen, um dem Connector die Authentifizierung mit einem Dienstprinzipal zu ermöglichen. Weitere Informationen finden Sie in der Azure Databricks Synapse Connector-Optionsreferenz.

Sie können optional auch einen anderen Dienstprinzipal für die Azure Synapse Analytics verwenden. Im folgenden Beispiel werden Dienstprinzipalanmeldeinformationen für das Speicherkonto und optionale Dienstprinzipalanmeldeinformationen für Synapse konfiguriert:

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>")

Python

# 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>")

R

# 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>")

Unterstützte Speichermodi für Batchschreibvorgänge

Der Azure Synapse-Connector unterstützt die Speichermodi ErrorIfExists, Ignore, Append und Overwrite mit dem Standardmodus ErrorIfExists. Weitere Informationen zu unterstützten Speichermodi in Apache Spark finden Sie in der Spark SQL-Dokumentation zu Speichermodi.

Referenz zu Azure Databricks Synapse-Connectoroptionen

Die in Spark SQL bereitgestellten OPTIONS unterstützen die folgenden Einstellungen:

Parameter	Erforderlich	Standard	Hinweise
dbTable	Ja, es sei denn query ist angegeben	Keine Standardeinstellung	Die Tabelle, aus der in Azure Synapse erstellt oder gelesen werden soll. Dieser Parameter ist erforderlich, wenn Daten wieder in Azure Synapse gespeichert werden. Sie können auch {SCHEMA NAME}.{TABLE NAME} verwenden, um auf eine Tabelle in einem bestimmten Schema zuzugreifen. Wenn kein Schemaname angegeben wird, wird das Standardschema verwendet, das dem JDBC-Benutzer zugeordnet ist. Die bislang unterstützte dbtable-Variante ist veraltet und wird in zukünftigen Releases ignoriert. Verwenden Sie stattdessen den Namen mit gemischter Groß-/Kleinschreibung.
query	Ja, es sei denn dbTable ist angegeben	Keine Standardeinstellung	Die Abfrage, aus der in Azure Synapse gelesen werden soll. Für Tabellen, auf die in der Abfrage verwiesen wird, können Sie auch {SCHEMA NAME}.{TABLE NAME} verwenden, um auf eine Tabelle in einem bestimmten Schema zuzugreifen. Wenn kein Schemaname angegeben wird, wird das Standardschema verwendet, das dem JDBC-Benutzer zugeordnet ist.
user	Nein	Keine Standardeinstellung	Der Azure Synapse-Benutzername. Muss zusammen mit der Option password verwendet werden. Kann nur verwendet werden, wenn der Benutzername und das Kennwort nicht in der URL übergeben werden. Andernfalls tritt ein Fehler auf.
password	Nein	Keine Standardeinstellung	Das Azure Synapse-Kennwort. Muss zusammen mit der Option user verwendet werden. Kann nur verwendet werden, wenn der Benutzername und das Kennwort nicht in der URL übergeben werden. Andernfalls tritt ein Fehler auf.
url	Ja	Keine Standardeinstellung	Eine JDBC-URL, wobei sqlserver als Unterprotokoll festgelegt ist. Es wird empfohlen, die im Azure-Portal bereitgestellte Verbindungszeichenfolge zu verwenden. Die Einstellung encrypt=true wird dringend empfohlen, da sie die SSL-Verschlüsselung der JDBC-Verbindung ermöglicht. Wenn user und password separat festgelegt werden, müssen Sie sie nicht in die URL einbinden.
jdbcDriver	Nein	Bestimmt durch das Unterprotokoll der JDBC-URL	Der Klassenname des zu verwendenden JDBC-Treibers. Diese Klasse muss im Klassenpfad vorhanden sein. In den meisten Fällen sollte es nicht erforderlich sein, diese Option anzugeben, da der entsprechende Treiberklassenname automatisch vom Subprotokoll der JDBC-URL bestimmt werden sollte. Die bislang unterstützte jdbc_driver-Variante ist veraltet und wird in zukünftigen Releases ignoriert. Verwenden Sie stattdessen den Namen mit gemischter Groß-/Kleinschreibung.
tempDir	Ja	Keine Standardeinstellung	Ein abfss-URI. Es wird empfohlen, einen dedizierten Blobspeichercontainer für die Azure Synapse-Instanz zu verwenden. Die bislang unterstützte tempdir-Variante ist veraltet und wird in zukünftigen Releases ignoriert. Verwenden Sie stattdessen den Namen mit gemischter Groß-/Kleinschreibung. Sie können keinen externen Speicherort verwenden, der in Unity Catalog als tempDir-Speicherort definiert ist.
tempCompression	Nein	SNAPPY	Der Komprimierungsalgorithmus, der zum Codieren/Decodieren von temporären Daten sowohl von Spark als auch von Azure Synapse verwendet werden soll. Derzeit werden die Werte UNCOMPRESSED, SNAPPY und GZIP unterstützt.
forwardSparkAzureStorageCredentials	Nein	Falsch	Wenn true, ermittelt die Bibliothek automatisch die Anmeldeinformationen für den Speicherkontozugriff, die Spark zum Herstellen einer Verbindung mit dem Blob-Speichercontainer verwendet, und leitet diese Anmeldeinformationen über JDBC an Azure Synapse weiter. Diese Anmeldeinformationen werden als Teil der JDBC-Abfrage gesendet. Daher wird dringend empfohlen, die SSL-Verschlüsselung der JDBC-Verbindung zu aktivieren, wenn Sie diese Option verwenden. Beim Konfigurieren der Speicherauthentifizierung müssen Sie genau eine von useAzureMSI und forwardSparkAzureStorageCredentials auf true setzen. Alternativ können Sie enableServicePrincipalAuth auf true setzen und einen Dienstprinzipal sowohl für die JDBC- als auch für die Speicherauthentifizierung verwenden. Die forwardSparkAzureStorageCredentials Option unterstützt die Authentifizierung für den Speicher nicht mithilfe einer verwalteten Dienstidentität oder eines Dienstprinzipals. Es wird nur der Zugriffsschlüssel für das Speicherkonto unterstützt. Die bislang unterstützte forward_spark_azure_storage_credentials-Variante ist veraltet und wird in zukünftigen Releases ignoriert. Verwenden Sie stattdessen den Namen mit gemischter Groß-/Kleinschreibung.
useAzureMSI	Nein	Falsch	Wenn der Wert true ist, gibt die Bibliothek IDENTITY = 'Managed Service Identity' und kein SECRET für die datenbankweit gültigen Anmeldeinformationen an, die sie erstellt. Beim Konfigurieren der Speicherauthentifizierung müssen Sie genau eine von useAzureMSI und forwardSparkAzureStorageCredentials auf true setzen. Alternativ können Sie enableServicePrincipalAuth auf true setzen und einen Dienstprinzipal sowohl für die JDBC- als auch für die Speicherauthentifizierung verwenden.
enableServicePrincipalAuth	Nein	Falsch	Wenn der Wert true ist, verwendet die Bibliothek die bereitgestellten Anmeldeinformationen des Dienstprinzipals, um eine Verbindung mit dem Azure-Speicherkonto und Azure Synapse Analytics über JDBC herzustellen. Wenn entweder forward_spark_azure_storage_credentials oder useAzureMSI auf true festgelegt wird, hat diese Option Vorrang vor dem Diensthaupt bei der Speicherauthentifizierung.
tableOptions	Nein	CLUSTERED COLUMNSTORE INDEX, DISTRIBUTION = ROUND_ROBIN	Eine Zeichenfolge, die zum Angeben von Tabellenoptionen verwendet wird, wenn die Azure Synapse-Tabellen über dbTable erstellt werden. Diese Zeichenfolge wird wortwörtlich an die WITH-Klausel der CREATE TABLE-Anweisung übergeben, die für Azure Synapse ausgegeben wird. Die bislang unterstützte table_options-Variante ist veraltet und wird in zukünftigen Releases ignoriert. Verwenden Sie stattdessen den Namen mit gemischter Groß-/Kleinschreibung.
preActions	Nein	Kein Standardwert (leere Zeichenfolge)	Eine durch ; getrennte Liste mit SQL-Befehlen, die in Azure Synapse ausgeführt werden müssen, bevor Daten in die Azure Synapse-Instanz geschrieben werden können. Diese SQL-Befehle müssen gültige Befehle sein, die von Azure Synapse akzeptiert werden. Wenn einer dieser Befehle fehlschlägt, wird er als Fehler behandelt, und der Schreibvorgang wird nicht ausgeführt.
postActions	Nein	Kein Standardwert (leere Zeichenfolge)	Eine durch ; getrennte Liste mit SQL-Befehlen, die in Azure Synapse ausgeführt werden müssen, nachdem der Connector erfolgreich Daten in die Azure Synapse-Instanz geschrieben hat. Diese SQL-Befehle müssen gültige Befehle sein, die von Azure Synapse akzeptiert werden. Wenn eines dieser Befehle fehlschlägt, wird sie als Fehler behandelt, und Sie erhalten eine Ausnahme, nachdem die Daten erfolgreich in die Azure Synapse-Instanz geschrieben wurden.
maxStrLength	Nein	256	StringType in Spark wird dem Typ NVARCHAR(maxStrLength) in Azure Synapse zugeordnet. Sie können maxStrLength verwenden, um die Zeichenfolgenlänge für alle spalten vom Typ NVARCHAR(maxStrLength) festzulegen, die sich in der Tabelle mit dem Namen dbTable in Azure Synapse befinden. Die bislang unterstützte maxstrlength-Variante ist veraltet und wird in zukünftigen Releases ignoriert. Verwenden Sie stattdessen den Namen mit gemischter Groß-/Kleinschreibung.
applicationName	Nein	Databricks-User-Query	Das Tag der Verbindung für die einzelnen Abfragen. Wenn kein Wert angegeben wird oder der Wert eine leere Zeichenfolge ist, wird dem Standardwert des Tags die JDBC-URL hinzugefügt. Mit dem Standardwert wird verhindert, dass das Azure DB-Überwachungstool fälschlicherweise Warnungen bei der SQL-Einschleusung für Abfragen ausgibt.
maxbinlength	Nein	Keine Standardeinstellung	Steuert die Spaltenlänge von BinaryType-Spalten. Dieser Parameter wird als VARBINARY(maxbinlength) übersetzt.
identityInsert	Nein	Falsch	Durch Festlegen auf true wird der IDENTITY_INSERT-Modus aktiviert, durch den ein vom Datenrahmen bereitgestellter Wert in die Identitätsspalte der Azure Synapse-Tabelle eingefügt wird. Weitere Informationen finden Sie unter Explizites Einfügen von Werten in eine IDENTITY-Spalte.
externalDataSource	Nein	Keine Standardeinstellung	Eine vorab bereitgestellte externe Datenquelle zum Lesen von Daten aus Azure Synapse. Eine externe Datenquelle kann nur mit PolyBase verwendet werden und entfernt die CONTROL-Berechtigungsanforderung, da der Connector keine bereichsbezogenen Anmeldeinformationen und eine externe Datenquelle zum Laden von Daten erstellen muss. Beispiele für die Verwendung und die Liste der Berechtigungen, die bei Verwendung einer externen Datenquelle erforderlich sind, finden Sie unter Erforderliche Azure Synapse-Berechtigungen für PolyBase mit der Option einer externen Datenquelle.
maxErrors	Nein	0	Die maximale Anzahl von Zeilen, die während Lese- und Schreibvorgängen abgelehnt werden können, bevor der Ladevorgang abgebrochen wird. Die abgelehnten Zeilen werden ignoriert. Wenn z. B. zwei von zehn Datensätzen Fehler aufweisen, werden nur acht Datensätze verarbeitet. Siehe REJECT_VALUE-Dokumentation in CREATE EXTERNAL TABLE und MAXERRORS-Dokumentation in COPY.
inferTimestampNTZType	Nein	Falsch	Wenn truewerte vom Typ Azure Synapse TIMESTAMP während der Lesevorgänge als TimestampNTZType (Zeitstempel ohne Zeitzone) interpretiert werden. Andernfalls werden alle Zeitstempel unabhängig vom Typ in der zugrunde liegenden Azure Synapse-Tabelle als TimestampType interpretiert.

Hinweis

• tableOptions, preActions, postActions und maxStrLength sind nur relevant, wenn Daten aus Azure Databricks in eine neue Tabelle in Azure Synapse geschrieben werden.
• Obwohl die Groß-/Kleinschreibung bei Datenquellenoptionsnamen nicht beachtet wird, sollten Sie die Namen aus Gründen der Übersichtlichkeit mit Groß- und Kleinbuchstaben angeben.

Abfrage-Pushdown in Azure Synapse

Der Azure Synapse-Connector implementiert eine Reihe von Optimierungsregeln, um für die folgenden Operatoren in die Azure Synapse einen Pushdown durchzuführen:

• Filter
• Project
• Limit

Die Operatoren Project und Filter unterstützen die folgenden Ausdrücke:

• Die meisten booleschen Logikoperatoren
• Vergleiche
• Grundlegende arithmetische Operationen
• Numerische und Zeichenfolgenumwandlungen

Für den Operator Limit wird Pushdown nur unterstützt, wenn keine Reihenfolge angegeben ist. Beispiel:

SELECT TOP(10) * FROM table, aber nicht SELECT TOP(10) * FROM table ORDER BY col.

Hinweis

Der Azure Synapse-Connector führt für Ausdrücke, die für Zeichenfolgen, Datumsangaben oder Zeitstempel verwendet werden, keinen Pushdown aus.

Der im Azure Synapse-Connector integrierte Abfragepushdown ist standardmäßig aktiviert. Sie können diese Einstellung deaktivieren, indem Sie spark.databricks.sqldw.pushdown auf false festlegen.

Verwaltung temporärer Daten

Der Azure Synapse-Connector löscht nicht die temporären Dateien, die er im Azure-Speichercontainer erstellt. Databricks empfiehlt, temporäre Dateien regelmäßig unter dem vom Benutzer angegebenen tempDir Speicherort zu löschen.

Zur Vereinfachung der Datenbereinigung speichert der Azure Synapse-Connector Datendateien nicht direkt im Verzeichnis tempDir, sondern erstellt stattdessen ein Unterverzeichnis im Format <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. Sie können periodische Aufträge (mit dem Feature "Lakeflow Jobs" oder anderweitig) einrichten, um alle Unterverzeichnisse, die älter als ein bestimmter Schwellenwert sind (z. B. 2 Tage), rekursiv zu löschen, wobei davon ausgegangen wird, dass Spark-Aufträge nicht länger als dieser Schwellenwert ausgeführt werden können.

Eine einfachere Alternative besteht darin, in regelmäßigen Abständen den gesamten Container zu löschen und einen neuen Container mit demselben Namen zu erstellen. Dies setzt voraus, dass Sie für die vom Azure Synapse-Connector erstellten temporären Daten einen dedizierten Container verwenden und ein Zeitfenster finden, für das Sie garantieren können, dass keine den Connector betreffenden Abfragen ausgeführt werden.

Verwaltung temporärer Objekte

Mit dem Azure Synapse-Connector wird die Datenübertragung zwischen einem Azure Databricks-Cluster und einer Azure Synapse-Instanz automatisiert. Zum Lesen von Daten aus einer Azure Synapse-Tabelle oder -Abfrage oder zum Schreiben von Daten in eine Azure Synapse-Tabelle erstellt der Azure Synapse-Connector im Hintergrund temporäre Objekte, wie DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCE, EXTERNAL FILE FORMAT und EXTERNAL TABLE. Diese Objekte leben nur während der gesamten Dauer des entsprechenden Spark-Auftrags und werden automatisch gelöscht.

Wenn ein Cluster eine Abfrage mit dem Azure Synapse-Connector ausführt und der Spark-Treiberprozess abstürzt oder zwangsweise neu gestartet wird, oder wenn der Cluster zwangsweise beendet oder neu gestartet wird, werden temporäre Objekte möglicherweise nicht gelöscht. Azure Synapse-Connector stellt den Namen aller temporären Zwischenobjekte, die in der Azure Synapse-Instanz erstellt werden, ein Tag der Form tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject> voran, um die Identifizierung und das manuelle Löschen dieser Objekte zu erleichtern.

Es wird empfohlen, in regelmäßigen Abständen mithilfe von Abfragen wie den folgenden nach verloren gegangenen Objekten zu suchen:

• 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_%'