Abfragen von Daten in Azure Synapse Analytics

Sie können mit dem Azure Synapse-Connector von Azure Databricks aus auf Azure Synapse zugreifen. Der Connector verwendet die COPY-Anweisung in Azure Synapse, um unter Verwendung eines Azure Data Lake Storage Gen2-Speicherkontos für das temporäre Staging große Datenmengen effizient zwischen einem Azure Databricks-Cluster und einer Azure Synapse-Instanz zu übertragen.

Wichtig

Die in diesem Artikel beschriebenen Konfigurationen sind experimentell. Experimentelle Funktionen werden ohne Mängelgewähr („wie besehen“) bereitgestellt und nicht von Databricks über Kanäle des technischen Kundensupports unterstützt. Um vollständige Unterstützung für den Abfrageverbund zu erhalten, sollten Sie stattdessen Lakehouse-Verbund verwenden, wodurch Ihre Azure Databricks-Benutzer die Vorteile der Unity Catalog-Syntax und der Datengovernancetools nutzen können.

Azure Synapse Analytics ist ein cloudbasiertes Data Warehouse für Unternehmen, das MPP (Massive Parallel Processing) zur schnellen Ausführung komplexer Abfragen für mehrere Petabytes an Daten nutzt.

Wichtig

Dieser Connector ist nur für die Verwendung mit Instanzen eines dedizierten Synapse-Pools vorgesehen und nicht mit anderen Synapse-Komponenten kompatibel.

Hinweis

COPY ist nur für Azure Data Lake Storage Gen2-Instanzen verfügbar. Informationen zum Arbeiten mit Polybase finden Sie unter 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 im Azure-Portal bereitgestellten Verbindungszeichenfolgen, sodass alle zwischen dem Spark-Treiber und der Azure Synapse-Instanz über die JDBC-Verbindung gesendeten Daten mittels SSL (Secure Sockets Layer) verschlüsselt werden können. Ob die SSL-Verschlüsselung aktiviert ist, können Sie überprüfen, indem Sie in der Verbindungszeichenfolge nach encrypt=true suchen.

Wichtig

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

Databricks empfiehlt, den sichersten Authentifizierungsfluss zu verwenden. Der in diesem Beispiel beschriebene Authentifizierungsfluss trägt Risiken, die in anderen Flüssen nicht vorhanden sind. Sie sollten diesen Authentifizierungsfluss nur verwenden, wenn andere sicherere Flüsse, wie verwaltete Identitäten, nicht machbar 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 mit Azure-Speicherkonto

Konfigurieren des Zugriffs auf Azure Storage

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

Azure Synapse bietet keine Unterstützung für die Verwendung von SAS zum Zugriff auf Speicherkonten. Sie können den Zugriff für beide Dienste folgendermaßen konfigurieren:

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

Erforderliche Azure Synapse-Berechtigungen

Da der Azure Synapse-Connector im Hintergrund COPY verwendet, muss der Benutzer der JDBC-Verbindung über die Berechtigung verfügen, die folgenden Befehle in der verbundenen Azure Synapse-Instanz auszuführen:

• 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 werden die erforderlichen Berechtigungen für Schreibvorgänge mit COPY zusammengefasst:

Berechtigungen (in eine vorhandene Tabelle einfügen)	Berechtigungen (in eine neue Tabelle einfügen)
ADMINISTER DATABASE BULK OPERATIONS INSERT	ADMINISTER DATABASE BULK OPERATIONS INSERT CREATE TABLE ALTER ON SCHEMA :: dbo

Netzwerkkonfigurationen

Wenn Sie eine Firewall für Azure Synapse konfigurieren, müssen Sie die Netzwerkeinstellungen so konfigurieren, dass Azure Synapse über Azure Databricks erreicht werden kann. Stellen Sie zunächst sicher, dass Ihr Azure Databricks-Arbeitsbereich in Ihrem eigenen virtuellen Netzwerk bereitgestellt wurde. Befolgen Sie dazu die Anleitung unter Bereitstellen von Azure Databricks in Ihrem virtuellen Azure-Netzwerk (VNet-Injektion). Anschließend können Sie IP-Firewallregeln für Azure Synapse konfigurieren, um Verbindungen von Ihren Subnetzen mit Ihrem Synapse-Konto zuzulassen. Siehe Azure Synapse Analytics: IP-Firewallregeln.

Konfigurieren der Verbindung zwischen Azure Databricks und Synapse über OAuth 2.0 mit 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 Dienstprinzipal-Anmeldeinformationen für den Zugriff auf ein Azure-Speicherkonto finden Sie unter Herstellen einer Verbindung mit Azure Data Lake Storage Gen2 und Blob Storage. Sie müssen die Option enableServicePrincipalAuth in der Verbindungskonfiguration (siehe true) auf festlegen, damit der Connector sich mit einem Dienstprinzipal authentifizieren kann.

Sie können optional auch einen anderen Dienstprinzipal für die Azure Synapse Analytics verwenden. Das folgende Beispiel konfiguriert die Anmeldeinformationen des Dienstprinzipals für das Speicherkonto und optionale Anmeldeinformationen des Dienstprinzipals für 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>")

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 der Azure Databricks Synapse-Connectoroptionen

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

Parameter	Erforderlich	Standard	Notizen
dbTable	Ja, es sei denn query ist angegeben	Kein Standardwert	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	Kein Standardwert	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	Kein Standardwert	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	Kein Standardwert	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	Kein Standardwert	Eine JDBC-URL, wobei sqlserver als Unterprotokoll festgelegt ist. Es wird empfohlen, die im Azure-Portal bereitgestellte Verbindungszeichenfolge zu verwenden. Einstellung Die Einstellung encrypt=true wird dringend empfohlen, weil damit die SSL-Verschlüsselung der JDBC-Verbindung aktiviert wird. Wenn user und password separat festgelegt werden, müssen Sie sie nicht in die URL einbinden.
jdbcDriver	Nein	Wird durch das Unterprotokoll der JDBC-URL bestimmt.	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 angeben zu müssen, da der entsprechende Treiberklassenname automatisch durch das Unterprotokoll 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	Kein Standardwert	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 im Unity-Katalog 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	false	Wenn der Wert true ist, ermittelt die Bibliothek die Anmeldeinformationen für den Speicherkonto-Zugriffsschlüssel automatisch, die Spark zum Herstellen einer Verbindung mit dem Blob Storage-Container 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 der Optionen useAzureMSI und forwardSparkAzureStorageCredentials auf true festlegen. Alternativ können Sie enableServicePrincipalAuth auf true festlegen und den Dienstprinzipal sowohl für die JDBC- als auch die Speicherauthentifizierung verwenden. Die Option forwardSparkAzureStorageCredentials unterstützt die Authentifizierung für den Speicher mithilfe einer verwalteten Dienstidentität oder eines Dienstprinzipals nicht. Nur der Speicherkonto-Zugriffsschlüssel wird 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	false	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 der Optionen useAzureMSI und forwardSparkAzureStorageCredentials auf true festlegen. Alternativ können Sie enableServicePrincipalAuth auf true festlegen und den Dienstprinzipal sowohl für die JDBC- als auch die Speicherauthentifizierung verwenden.
enableServicePrincipalAuth	Nein	false	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 ist, hat diese Option bei der Speicherauthentifizierung Vorrang vor dem Dienstprinzipal.
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 einer dieser Befehle fehlschlägt, wird dies als Fehler behandelt, und es wird eine Ausnahme ausgelöst, 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	Kein Standardwert	Steuert die Spaltenlänge von BinaryType-Spalten. Dieser Parameter wird als VARBINARY(maxbinlength) übersetzt.
identityInsert	Nein	false	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	Kein Standardwert	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, weil 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 bei 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. Weitere Informationen finden Sie in REJECT_VALUE der DOKUMENTATION CREATE EXTERNAL TABLEund MAXERRORS in COPY.
inferTimestampNTZType	Nein	false	Bei einer Festlegung auf true werden Werte mit dem Azure Synapse-Typ TIMESTAMP bei Lesevorgängen als TimestampNTZType (Zeitstempel ohne Zeitzone) interpretiert. Andernfalls werden alle Zeitstempel als TimestampType interpretiert, unabhängig vom Typ in der zugrunde liegenden Azure Synapse-Tabelle.

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. Beispiele:

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

Die im Azure Storage-Container erstellten temporären Dateien werden nicht durch den Azure Synapse-Connector gelöscht. Databricks empfiehlt, dass Sie temporäre Dateien in dem vom Benutzer angegebenen tempDir-Speicherort regelmäßig 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 (mithilfe der Azure Databricks-Funktion Aufträge oder auf andere Weise) regelmäßige Aufträge einrichten, mit denen alle Unterverzeichnisse rekursiv gelöscht werden, die älter sind als ein angegebener Schwellenwert (z. B. 2 Tage), wobei davon ausgegangen wird, dass Spark-Aufträge nicht über diesen Schwellenwert hinaus ausgeführt werden dürfen.

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 werden nur für die Dauer des entsprechenden Spark-Auftrags beibehalten und anschließend 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_%'