Anslut Azure Databricks och Azure Synapse med PolyBase (äldre)

Viktigt!

Den här dokumentationen har dragits tillbaka och kanske inte uppdateras. De produkter, tjänster eller tekniker som nämns i det här innehållet stöds inte längre. Se Fråga efter data i Azure Synapse Analytics.

Databricks rekommenderar att du använder standardfunktionerna COPY med Azure Data Lake Storage Gen2 för anslutningar till Azure Synapse. Den här artikeln innehåller äldre dokumentation om PolyBase och bloblagring.

Azure Synapse Analytics (tidigare SQL Data Warehouse) är ett molnbaserat informationslager för företag som utnyttjar MPP (massively parallel processing) för att snabbt köra komplexa frågor över petabyte med data. Använd Azure som en nyckelkomponent i en stordatalösning. Importera stordata till Azure med enkla PolyBase T-SQL-frågor eller COPY-instruktion och använd sedan kraften i MPP för att köra analys med höga prestanda. Använd informationslagret en tid för att integrera och analysera och upptäck vilket fantastiskt hjälpmedel det är för att fördjupa insikterna.

Du kan komma åt Azure Synapse från Azure Databricks med hjälp av Azure Synapse-anslutningsappen, en datakällimplementering för Apache Spark som använder Azure Blob Storage och PolyBase eller -instruktionen COPY i Azure Synapse för att överföra stora mängder data effektivt mellan ett Azure Databricks-kluster och en Azure Synapse-instans.

Både Azure Databricks-klustret och Azure Synapse-instansen har åtkomst till en gemensam Blob Storage-container för att utbyta data mellan dessa två system. I Azure Databricks utlöses Apache Spark-jobb av Azure Synapse-anslutningsappen för att läsa data från och skriva data till Blob Storage-containern. På Azure Synapse-sidan utlöses datainläsnings- och avlastningsåtgärder som utförs av PolyBase av Azure Synapse-anslutningsappen via JDBC. I Databricks Runtime 7.0 och senare COPY används som standard för att läsa in data i Azure Synapse av Azure Synapse-anslutningsappen via JDBC.

Kommentar

COPY är endast tillgängligt på Azure Synapse Gen2-instanser, vilket ger bättre prestanda. Om databasen fortfarande använder Gen1-instanser rekommenderar vi att du migrerar databasen till Gen2.

Azure Synapse-anslutningsappen passar bättre för ETL än för interaktiva frågor, eftersom varje frågekörning kan extrahera stora mängder data till Blob Storage. Om du planerar att utföra flera frågor mot samma Azure Synapse-tabell rekommenderar vi att du sparar extraherade data i ett format som Parquet.

Krav

En huvudnyckel för Azure Synapse-databasen.

Autentisering

Anslutningsappen för Azure Synapse använder tre typer av nätverksanslutningar:

  • Spark-drivrutin till Azure Synapse
  • Spark-drivrutin och utförare till Azure Storage-konto
  • Azure Synapse till Azure Storage-konto
                                 ┌─────────┐
      ┌─────────────────────────>│ STORAGE │<────────────────────────┐
      │   Storage acc key /      │ ACCOUNT │  Storage acc key /      │
      │   Managed Service ID /   └─────────┘  OAuth 2.0 /            │
      │                               │                              │
      │                               │                              │
      │                               │ Storage acc key /            │
      │                               │ OAuth 2.0 /                  │
      │                               │                              │
      v                               v                       ┌──────v────┐
┌──────────┐                      ┌──────────┐                │┌──────────┴┐
│ Synapse  │                      │  Spark   │                ││ Spark     │
│ Analytics│<────────────────────>│  Driver  │<───────────────>│ Executors │
└──────────┘  JDBC with           └──────────┘    Configured   └───────────┘
              username & password /                in Spark

I följande avsnitt beskrivs konfigurationsalternativen för varje anslutning.

Spark-drivrutin till Azure Synapse

Spark-drivrutinen kan ansluta till Azure Synapse med JDBC med ett användarnamn och lösenord eller OAuth 2.0 med tjänstens huvudnamn för autentisering.

Användarnamn och lösenord

Vi rekommenderar att du använder anslutningssträng som tillhandahålls av Azure-portalen för båda autentiseringstyperna, som aktiverar SSL-kryptering (Secure Sockets Layer) för alla data som skickas mellan Spark-drivrutinen och Azure Synapse-instansen via JDBC-anslutningen. Om du vill kontrollera att SSL-krypteringen är aktiverad kan du söka efter encrypt=true i anslutningssträng.

För att spark-drivrutinen ska kunna nå Azure Synapse rekommenderar vi att du anger Tillåt Azure-tjänster och resurser att komma åt den här arbetsytan till i fönstret Nätverk under Säkerhet för Azure Synapse-arbetsytan via Azure-portalen. Den här inställningen tillåter kommunikation från alla Azure IP-adresser och alla Azure-undernät, vilket gör att Spark-drivrutiner kan nå Azure Synapse-instansen.

OAuth 2.0 med ett tjänsthuvudnamn

Du kan autentisera till Azure Synapse Analytics med hjälp av ett huvudnamn för tjänsten med åtkomst till det underliggande lagringskontot. Mer information om att använda uppgifter för tjänstens huvudnamn för att komma åt ett Azure-lagringskonto finns i Ansluta till ett Azure Data Lake Storage Gen2-konto och Blob Storage. Du måste ange enableServicePrincipalAuth alternativet till true i anslutningskonfigurationsparametrarna för att anslutningsappen ska kunna autentisera med tjänstens huvudnamn.

Du kan också använda ett annat huvudnamn för tjänsten för Azure Synapse Analytics-anslutningen. Ett exempel som konfigurerar autentiseringsuppgifter för tjänstens huvudnamn för lagringskontot och valfria autentiseringsuppgifter för tjänstens huvudnamn 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>")

Spark-drivrutin och utförare till Azure Storage-konto

Azure Storage-containern fungerar som mellanhand för att lagra massdata när du läser från eller skriver till Azure Synapse. Spark ansluter till ADLS Gen2 eller Blob Storage med hjälp av abfss drivrutinen.

Följande autentiseringsalternativ är tillgängliga:

Exemplen nedan illustrerar dessa två sätt att använda åtkomstnyckelmetoden för lagringskontot. Samma sak gäller för OAuth 2.0-konfigurationen.

Konfiguration av notebook-sessioner (rekommenderas)

Med den här metoden anges kontoåtkomstnyckeln i sessionskonfigurationen som är associerad med anteckningsboken som kör kommandot. Den här konfigurationen påverkar inte andra notebook-filer som är kopplade till samma kluster. spark är objektet SparkSession som anges i notebook-filen.

spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

Global Hadoop-konfiguration

Den här metoden uppdaterar den globala Hadoop-konfigurationen som är associerad med objektet SparkContext som delas av alla notebook-filer.

Scala
sc.hadoopConfiguration.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")
Python

hadoopConfiguration exponeras inte i alla versioner av PySpark. Även om följande kommando förlitar sig på vissa interna Spark-objekt bör det fungera med alla PySpark-versioner och kommer sannolikt inte att brytas eller ändras i framtiden:

sc._jsc.hadoopConfiguration().set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

Azure Synapse till Azure Storage-konto

Azure Synapse ansluter också till ett lagringskonto vid inläsning och avlastning av tillfälliga data.

Om du har konfigurerat en kontonyckel och hemlighet för lagringskontot kan du ange forwardSparkAzureStorageCredentials till true, i vilket fall Azure Synapse-anslutningsappen automatiskt identifierar kontoåtkomstnyckeln som angetts i konfigurationen av notebook-sessionen eller den globala Hadoop-konfigurationen och vidarebefordrar åtkomstnyckeln för lagringskontot till den anslutna Azure Synapse-instansen genom att skapa en tillfällig Azure-databasomfångad autentiseringsuppgift.

Om du använder ADLS Gen2 med OAuth 2.0-autentisering eller om Azure Synapse-instansen har konfigurerats för att ha en hanterad tjänstidentitet (vanligtvis tillsammans med en konfiguration av VNet + Tjänstslutpunkter) måste du ange useAzureMSI till true. I det här fallet anger IDENTITY = 'Managed Service Identity' anslutningsappen för den databasbaserade begränsade autentiseringsuppgiften och ingen SECRET.

Stöd för direktuppspelning

Azure Synapse-anslutningsappen erbjuder effektivt och skalbart skrivningsstöd för strukturerad direktuppspelning för Azure Synapse som ger konsekvent användarupplevelse med batchskrivningar och använder PolyBase eller COPY för stora dataöverföringar mellan ett Azure Databricks-kluster och Azure Synapse-instans. På samma sätt som batchskrivningar är strömning till stor del utformad för ETL, vilket ger högre svarstid som kanske inte är lämplig för databearbetning i realtid i vissa fall.

Semantik för feltolerans

Som standard erbjuder Azure Synapse Streaming en garanti från slutpunkt till slutpunkt exakt en gång för att skriva data till en Azure Synapse-tabell genom att på ett tillförlitligt sätt spåra förloppet för frågan med hjälp av en kombination av kontrollpunktsplats i DBFS, kontrollpunktstabell i Azure Synapse och låsmekanism för att säkerställa att strömning kan hantera alla typer av fel, återförsök och omstarter av frågor. Du kan också välja mindre restriktiva semantik minst en gång för Azure Synapse Streaming genom att ange spark.databricks.sqldw.streaming.exactlyOnce.enabled alternativet till false, i vilket fall dataduplicering kan inträffa i händelse av tillfälliga anslutningsfel till Azure Synapse eller oväntad frågeavslutning.

Användning (Batch)

Du kan använda den här anslutningsappen via datakällans API i Notebook-filer för Scala, Python, SQL och R.

Scala


// Otherwise, set up the Blob 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.
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


# Otherwise, set up the Blob 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.
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


-- Otherwise, set up the Blob 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.
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)

# Otherwise, set up the Blob 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>")

Användning (direktuppspelning)

Du kan skriva data med structured streaming i Scala- och Python-notebook-filer.

Scala

// Set up the Blob 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>")

// Prepare streaming source; this could be Kafka or a simple rate stream.
val df: DataFrame = spark.readStream
  .format("rate")
  .option("rowsPerSecond", "100000")
  .option("numPartitions", "16")
  .load()

// Apply some transformations to the data then use
// Structured Streaming API to continuously write the data to a table in Azure Synapse.
df.writeStream
  .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>")
  .option("checkpointLocation", "/tmp_checkpoint_location")
  .start()

Python

# Set up the Blob 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>")

# Prepare streaming source; this could be Kafka or a simple rate stream.
df = spark.readStream \
  .format("rate") \
  .option("rowsPerSecond", "100000") \
  .option("numPartitions", "16") \
  .load()

# Apply some transformations to the data then use
# Structured Streaming API to continuously write the data to a table in Azure Synapse.
df.writeStream \
  .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>") \
  .option("checkpointLocation", "/tmp_checkpoint_location") \
  .start()

Konfiguration

I det här avsnittet beskrivs hur du konfigurerar skrivsemantik för anslutningsappen, nödvändiga behörigheter och olika konfigurationsparametrar.

I detta avsnitt:

Spara lägen som stöds för batchskrivningar

Azure Synapse-anslutningsappen stöder ErrorIfExists, Ignore, Appendoch Overwrite sparar lägen där standardläget är ErrorIfExists. Mer information om de sparlägen som stöds i Apache Spark finns i Spark SQL-dokumentationen om spara lägen.

Utdatalägen som stöds för direktuppspelningsskrivningar

Azure Synapse-anslutningsappen stöder Append och Complete utdatalägen för posttillägg och aggregeringar. Mer information om utdatalägen och kompatibilitetsmatris finns i guiden Strukturerad direktuppspelning.

Skriva semantik

Kommentar

COPY är tillgängligt i Databricks Runtime 7.0 och senare.

Utöver PolyBase stöder Azure Synapse-anslutningsappen instruktionen COPY . Instruktionen COPY ger ett bekvämare sätt att läsa in data i Azure Synapse utan att behöva skapa en extern tabell, kräver färre behörigheter för att läsa in data och förbättrar prestanda för datainmatning i Azure Synapse.

Som standard identifierar anslutningsappen automatiskt de bästa skrivsemantiken (COPY när du riktar in dig på en Azure Synapse Gen2-instans, annars PolyBase). Du kan också ange skrivsemantiken med följande konfiguration:

Scala

// Configure the write semantics for Azure Synapse connector in the notebook session conf.
spark.conf.set("spark.databricks.sqldw.writeSemantics", "<write-semantics>")

Python

# Configure the write semantics for Azure Synapse connector in the notebook session conf.
spark.conf.set("spark.databricks.sqldw.writeSemantics", "<write-semantics>")

SQL

-- Configure the write semantics for Azure Synapse connector in the notebook session conf.
SET spark.databricks.sqldw.writeSemantics=<write-semantics>;

R

# Load SparkR
library(SparkR)

# Configure the write semantics for Azure Synapse connector in the notebook session conf.
conf <- sparkR.callJMethod(sparkR.session(), "conf")
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.writeSemantics", "<write-semantics>")

där <write-semantics> är antingen polybase att använda PolyBase eller copy att använda -instruktionen COPY .

Nödvändiga Azure Synapse-behörigheter för PolyBase

När du använder PolyBase kräver Azure Synapse-anslutningsappen att JDBC-anslutningsanvändaren har behörighet att köra följande kommandon i den anslutna Azure Synapse-instansen:

Som en förutsättning för det första kommandot förväntar sig anslutningsappen att det redan finns en databashuvudnyckel för den angivna Azure Synapse-instansen. Annars kan du skapa en nyckel med kommandot CREATE MASTER KEY .

Dessutom måste JDBC-användaren ha behörighet att komma åt nödvändiga Azure Synapse-tabeller för att kunna läsa azure Synapse-tabellen dbTable eller tabeller som anges i query. Om du vill skriva tillbaka data till en Azure Synapse-tabell som angetts via dbTablemåste JDBC-användaren ha behörighet att skriva till den här Azure Synapse-tabellen.

I följande tabell sammanfattas de behörigheter som krävs för alla åtgärder med PolyBase:

Åtgärd Behörigheter Behörigheter när du använder en extern datakälla
Batchskrivning KONTROLL Se Batch-skrivning
Strömningsskrivning KONTROLL Se Strömningsskrivning
Lästa KONTROLL Läs mer

Nödvändiga Azure Synapse-behörigheter för PolyBase med alternativet extern datakälla

Du kan använda PolyBase med en företablerad extern datakälla. Mer information finns i parametern externalDataSource i Parametrar .

För att kunna använda PolyBase med en företablerad extern datakälla kräver Azure Synapse-anslutningsappen att JDBC-anslutningsanvändaren har behörighet att köra följande kommandon i den anslutna Azure Synapse-instansen:

Om du vill skapa en extern datakälla bör du först skapa en databasomfattande autentiseringsuppgift. Följande länkar beskriver hur du skapar en begränsad autentiseringsuppgift för tjänstens huvudnamn och en extern datakälla för en ABFS-plats:

Kommentar

Platsen för den externa datakällan måste peka på en container. Anslutningsappen fungerar inte om platsen är en katalog i en container.

I följande tabell sammanfattas behörigheterna för PolyBase-skrivåtgärder med alternativet extern datakälla:

Åtgärd Behörigheter (infoga i en befintlig tabell) Behörigheter (infoga i en ny tabell)
Batchskrivning ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT

CREATE TABLE

ÄNDRA VALFRITT SCHEMA

ÄNDRA ALLA EXTERNA DATAKÄLLOR

ÄNDRA VALFRITT EXTERNT FILFORMAT
ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT

CREATE TABLE

ÄNDRA VALFRITT SCHEMA

ÄNDRA ALLA EXTERNA DATAKÄLLOR

ÄNDRA VALFRITT EXTERNT FILFORMAT
Strömningsskrivning ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT

CREATE TABLE

ÄNDRA VALFRITT SCHEMA

ÄNDRA ALLA EXTERNA DATAKÄLLOR

ÄNDRA VALFRITT EXTERNT FILFORMAT
ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT

CREATE TABLE

ÄNDRA VALFRITT SCHEMA

ÄNDRA ALLA EXTERNA DATAKÄLLOR

ÄNDRA VALFRITT EXTERNT FILFORMAT

I följande tabell sammanfattas behörigheterna för PolyBase-läsåtgärder med alternativet extern datakälla:

Åtgärd Behörigheter
Lästa CREATE TABLE

ÄNDRA VALFRITT SCHEMA

ÄNDRA ALLA EXTERNA DATAKÄLLOR

ÄNDRA VALFRITT EXTERNT FILFORMAT

Du kan använda den här anslutningsappen för att läsa via datakällans API i Notebook-filer för Scala, Python, SQL och R.

Scala
// Get some data from an Azure Synapse table.
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("externalDataSource", "<your-pre-provisioned-data-source>")
  .option("dbTable", "<your-table-name>")
  .load()
Python
# Get some data from an Azure Synapse table.
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("externalDataSource", "<your-pre-provisioned-data-source>") \
  .option("dbTable", "<your-table-name>") \
  .load()
SQL
-- Read data using SQL.
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>',
  externalDataSource '<your-pre-provisioned-data-source>'
);
R
# 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>"
   externalDataSource = "<your-pre-provisioned-data-source>")

Nödvändiga Azure Synapse-behörigheter för -instruktionen COPY

Kommentar

Tillgänglig i Databricks Runtime 7.0 och senare.

När du använder -instruktionen COPY kräver Azure Synapse-anslutningsappen att JDBC-anslutningsanvändaren har behörighet att köra följande kommandon i den anslutna Azure Synapse-instansen:

Om måltabellen inte finns i Azure Synapse krävs behörighet att köra följande kommando utöver kommandot ovan:

I följande tabell sammanfattas behörigheterna för batch- och direktuppspelningsskrivningar med COPY:

Åtgärd Behörigheter (infoga i en befintlig tabell) Behörigheter (infoga i en ny tabell)
Batchskrivning ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT
ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT

CREATE TABLE

ÄNDRA I SCHEMA :: dbo
Strömningsskrivning ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT
ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT

CREATE TABLE

ÄNDRA I SCHEMA :: dbo

Parametrar

Parameterkartan eller OPTIONS som anges i Spark SQL stöder följande inställningar:

Parameter Obligatoriskt Standardvärde Kommentar
dbTable Ja, såvida inte query har angetts Inget standardvärde Tabellen som ska skapas eller läsas från i Azure Synapse. Den här parametern krävs när du sparar data tillbaka till Azure Synapse.

Du kan också använda {SCHEMA NAME}.{TABLE NAME} för att komma åt en tabell i ett visst schema. Om schemanamnet inte anges används standardschemat som är associerat med JDBC-användaren.

Den tidigare variant som stöds dbtable är inaktuell och ignoreras i framtida versioner. Använd namnet "kamelfall" i stället.
query Ja, såvida inte dbTable har angetts Inget standardvärde Frågan som ska läsas från i Azure Synapse.

För tabeller som refereras i frågan kan du också använda {SCHEMA NAME}.{TABLE NAME} för att komma åt en tabell i ett visst schema. Om schemanamnet inte anges används standardschemat som är associerat med JDBC-användaren.
user Nej Inget standardvärde Användarnamnet för Azure Synapse. Måste användas tillsammans med password alternativet . Kan bara användas om användaren och lösenordet inte skickas i URL:en. Om du skickar båda resulterar det i ett fel.
password Nej Inget standardvärde Azure Synapse-lösenordet. Måste användas tillsammans med user alternativet . Kan bara användas om användaren och lösenordet inte skickas i URL:en. Om du skickar båda resulterar det i ett fel.
url Ja Inget standardvärde En JDBC-URL med sqlserver inställd som underprotokol. Vi rekommenderar att du använder anslutningssträng som tillhandahålls av Azure-portalen. Inställning
encrypt=true rekommenderas starkt eftersom det möjliggör SSL-kryptering av JDBC-anslutningen. Om user och password anges separat behöver du inte inkludera dem i URL:en.
jdbcDriver Nej Bestäms av JDBC-URL:ens underprotokol Klassnamnet på den JDBC-drivrutin som ska användas. Den här klassen måste finnas på klassökvägen. I de flesta fall bör det inte vara nödvändigt att ange det här alternativet, eftersom lämpligt drivrutinsklassnamn automatiskt bör fastställas av JDBC-URL:ens underprotokol.

Den tidigare variant som stöds jdbc_driver är inaktuell och ignoreras i framtida versioner. Använd namnet "kamelfall" i stället.
tempDir Ja Inget standardvärde En abfss URI. Vi rekommenderar att du använder en dedikerad Blob Storage-container för Azure Synapse.

Den tidigare variant som stöds tempdir är inaktuell och ignoreras i framtida versioner. Använd namnet "kamelfall" i stället.
tempFormat Nej PARQUET Formatet där du kan spara temporära filer i bloblagret när du skriver till Azure Synapse. Standardvärdet PARQUETär ; inga andra värden tillåts just nu.
tempCompression Nej SNAPPY Komprimeringsalgoritmen som ska användas för att koda/avkoda temporärt av både Spark och Azure Synapse. För närvarande stöds värden: UNCOMPRESSED, SNAPPY och GZIP.
forwardSparkAzureStorageCredentials Nej falskt Om trueidentifierar biblioteket automatiskt de autentiseringsuppgifter som Spark använder för att ansluta till Blob Storage-containern och vidarebefordrar dessa autentiseringsuppgifter till Azure Synapse via JDBC. Dessa autentiseringsuppgifter skickas som en del av JDBC-frågan. Därför rekommenderar vi starkt att du aktiverar SSL-kryptering för JDBC-anslutningen när du använder det här alternativet.

Den aktuella versionen av Azure Synapse-anslutningsappen kräver (exakt) en av forwardSparkAzureStorageCredentials, enableServicePrincipalAutheller useAzureMSI för att uttryckligen anges till true.

Den tidigare variant som stöds forward_spark_azure_storage_credentials är inaktuell och ignoreras i framtida versioner. Använd namnet "kamelfall" i stället.
useAzureMSI Nej falskt Om trueanger IDENTITY = 'Managed Service Identity' biblioteket och nej SECRET för de databasomfattningsautentiseringsuppgifter som skapas.

Den aktuella versionen av Azure Synapse-anslutningsappen kräver (exakt) en av forwardSparkAzureStorageCredentials, enableServicePrincipalAutheller useAzureMSI för att uttryckligen anges till true.
enableServicePrincipalAuth Nej falskt Om trueanvänder biblioteket de angivna autentiseringsuppgifterna för tjänstens huvudnamn för att ansluta till Azure Storage-kontot och Azure Synapse Analytics via JDBC.

Den aktuella versionen av Azure Synapse-anslutningsappen kräver (exakt) en av forwardSparkAzureStorageCredentials, enableServicePrincipalAutheller useAzureMSI för att uttryckligen anges till true.
tableOptions Nej CLUSTERED COLUMNSTORE INDEX, DISTRIBUTION = ROUND_ROBIN En sträng som används för att ange tabellalternativ när du skapar Azure Synapse-tabellen som anges via dbTable. Den här strängen skickas bokstavligen WITH till satsen i SQL-instruktionen CREATE TABLE som utfärdas mot Azure Synapse.

Den tidigare variant som stöds table_options är inaktuell och ignoreras i framtida versioner. Använd namnet "kamelfall" i stället.
preActions Nej Inget standardvärde (tom sträng) En ; avgränsad lista över SQL-kommandon som ska köras i Azure Synapse innan data skrivs till Azure Synapse-instansen. Dessa SQL-kommandon måste vara giltiga kommandon som accepteras av Azure Synapse.

Om något av dessa kommandon misslyckas behandlas det som ett fel och skrivåtgärden körs inte.
postActions Nej Inget standardvärde (tom sträng) En ; avgränsad lista över SQL-kommandon som ska köras i Azure Synapse efter att anslutningsappen har skrivit data till Azure Synapse-instansen. Dessa SQL-kommandon måste vara giltiga kommandon som accepteras av Azure Synapse.

Om något av dessa kommandon misslyckas behandlas det som ett fel och du får ett undantag när data har skrivits till Azure Synapse-instansen.
maxStrLength Nej 256 StringType i Spark mappas till NVARCHAR(maxStrLength) typen i Azure Synapse. Du kan använda maxStrLength för att ange stränglängden för alla NVARCHAR(maxStrLength) typkolumner som finns i tabellen med namnet
dbTable i Azure Synapse.

Den tidigare variant som stöds maxstrlength är inaktuell och ignoreras i framtida versioner. Använd namnet "kamelfall" i stället.
checkpointLocation Ja Inget standardvärde Plats på DBFS som ska användas av Structured Streaming för att skriva metadata och kontrollpunktsinformation. Se Återställa från fel med kontrollpunkter i programmeringsguiden för strukturerad direktuppspelning.
numStreamingTempDirsToKeep Nej 0 Anger hur många (senaste) tillfälliga kataloger som ska behållas för regelbunden rensning av mikrobatch i strömning. När värdet 0är inställt på utlöses katalogborttagning omedelbart efter att mikrobatch har checkats in, annars anges antalet senaste mikrobatcherna och resten av katalogerna tas bort. Använd -1 för att inaktivera periodisk rensning.
applicationName Nej Databricks-User-Query Taggen för anslutningen för varje fråga. Om det inte anges eller om värdet är en tom sträng läggs standardvärdet för taggen till JDBC-URL:en. Standardvärdet hindrar Azure DB-övervakningsverktyget från att skapa falska SQL-inmatningsaviseringar mot frågor.
maxbinlength Nej Inget standardvärde Kontrollera kolumnlängden BinaryType för kolumner. Den här parametern översätts som VARBINARY(maxbinlength).
identityInsert Nej falskt Inställning för att true aktivera IDENTITY_INSERT läge, vilket infogar ett DataFrame-angivet värde i identitetskolumnen i Azure Synapse-tabellen.

Se Explicit infoga värden i en identitetskolumn.
externalDataSource Nej Inget standardvärde En fördefinierad extern datakälla för att läsa data från Azure Synapse. En extern datakälla kan bara användas med PolyBase och tar bort behörighetskravet CONTROL eftersom anslutningsappen inte behöver skapa en begränsad autentiseringsuppgift och en extern datakälla för att läsa in data.

Till exempel användning och listan över behörigheter som krävs när du använder en extern datakälla finns i Nödvändiga Azure Synapse-behörigheter för PolyBase med alternativet extern datakälla.
maxErrors Nej 0 Det maximala antalet rader som kan avvisas under läsningar och skrivningar innan inläsningsåtgärden (antingen PolyBase eller COPY) avbryts. De avvisade raderna ignoreras. Om två av tio poster till exempel har fel bearbetas endast åtta poster.

Se REJECT_VALUE dokumentation i SKAPA EXTERN TABELL och MAXERRORS-dokumentation i COPY.

Kommentar

  • tableOptions, preActions, postActionsoch maxStrLength är endast relevanta när du skriver data från Azure Databricks till en ny tabell i Azure Synapse.
  • externalDataSource är endast relevant när du läser data från Azure Synapse och skriver data från Azure Databricks till en ny tabell i Azure Synapse med PolyBase-semantik. Du bör inte ange andra typer av lagringsautentisering när du använder externalDataSource till exempel forwardSparkAzureStorageCredentials eller useAzureMSI.
  • checkpointLocation och numStreamingTempDirsToKeep är endast relevanta för strömmande skrivningar från Azure Databricks till en ny tabell i Azure Synapse.
  • Även om alla alternativnamn för datakällor är skiftlägesokänsliga rekommenderar vi att du anger dem i "kamelfall" för tydlighetens skull.

Skicka frågor till Azure Synapse

Azure Synapse-anslutningsappen implementerar en uppsättning optimeringsregler för att push-överföra följande operatorer till Azure Synapse:

  • Filter
  • Project
  • Limit

Operatorerna Project och Filter stöder följande uttryck:

  • De flesta booleska logikoperatorer
  • Jämförelser
  • Grundläggande aritmetiska åtgärder
  • Numeriska och stränggjutningar

För operatorn Limit stöds pushdown endast när ingen beställning har angetts. Till exempel:

SELECT TOP(10) * FROM table, men inte SELECT TOP(10) * FROM table ORDER BY col.

Kommentar

Azure Synapse-anslutningsappen push-överför inte uttryck som körs på strängar, datum eller tidsstämplar.

Pushdown-frågor som skapats med Azure Synapse-anslutningsappen är aktiverat som standard. Du kan inaktivera det genom att ange spark.databricks.sqldw.pushdown till false.

Tillfällig datahantering

Azure Synapse-anslutningsappen tar inte bort de temporära filer som skapas i Blob Storage-containern. Därför rekommenderar vi att du regelbundet tar bort temporära filer under den plats som användaren anger tempDir .

För att underlätta datarensning lagrar Azure Synapse-anslutningsappen inte datafiler direkt under tempDir, utan skapar i stället en underkatalog för formuläret: <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. Du kan konfigurera periodiska jobb (med hjälp av funktionen Azure Databricks-jobb eller på annat sätt) för att rekursivt ta bort alla underkataloger som är äldre än ett visst tröskelvärde (till exempel 2 dagar), med antagandet att Det inte kan finnas Spark-jobb som körs längre än det tröskelvärdet.

Ett enklare alternativ är att regelbundet släppa hela containern och skapa en ny med samma namn. Detta kräver att du använder en dedikerad container för tillfälliga data som produceras av Azure Synapse-anslutningsappen och att du kan hitta ett tidsfönster där du kan garantera att inga frågor som rör anslutningsappen körs.

Tillfällig objekthantering

Azure Synapse-anslutningsappen automatiserar dataöverföring mellan ett Azure Databricks-kluster och en Azure Synapse-instans. För att läsa data från en Azure Synapse-tabell eller fråga eller skriva data till en Azure Synapse-tabell skapar Azure Synapse-anslutningsappen tillfälliga objekt, inklusive DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCEEXTERNAL FILE FORMAToch EXTERNAL TABLE bakom kulisserna. Dessa objekt lever endast under hela varaktigheten för motsvarande Spark-jobb och bör sedan tas bort automatiskt.

När ett kluster kör en fråga med hjälp av Azure Synapse-anslutningsappen, om Spark-drivrutinsprocessen kraschar eller startas om kraftfullt, eller om klustret avslutas eller startas om, kanske inte temporära objekt tas bort. För att underlätta identifiering och manuell borttagning av dessa objekt prefixar Azure Synapse-anslutningsappen namnen på alla mellanliggande temporära objekt som skapats i Azure Synapse-instansen med en tagg i formuläret: tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject>.

Vi rekommenderar att du regelbundet letar efter läckta objekt med hjälp av frågor som följande:

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

Hantering av kontrollpunktstabeller för direktuppspelning

Azure Synapse-anslutningsappen tar inte bort den kontrollpunktstabell för direktuppspelning som skapas när ny direktuppspelningsfråga startas. Det här beteendet överensstämmer med checkpointLocation dbfs. Därför rekommenderar vi att du regelbundet tar bort kontrollpunktstabeller samtidigt som du tar bort kontrollpunktsplatser på DBFS för frågor som inte kommer att köras i framtiden eller som redan har tagit bort kontrollpunktsplatsen.

Som standard har alla kontrollpunktstabeller namnet <prefix>_<query-id>, där <prefix> är ett konfigurerbart prefix med standardvärde databricks_streaming_checkpoint och query_id är ett direktuppspelningsfråge-ID med _ borttagna tecken. Kör frågan för att hitta alla kontrollpunktstabeller för inaktuella eller borttagna direktuppspelningsfrågor:

SELECT * FROM sys.tables WHERE name LIKE 'databricks_streaming_checkpoint%'

Du kan konfigurera prefixet med konfigurationsalternativet spark.databricks.sqldw.streaming.exactlyOnce.checkpointTableNamePrefixSpark SQL .

Vanliga frågor och svar

Jag fick ett fel när jag använde Azure Synapse-anslutningsappen. Hur vet jag om det här felet kommer från Azure Synapse eller Azure Databricks?

För att hjälpa dig att felsöka fel omsluts alla undantag som genereras av kod som är specifik för Azure Synapse-anslutningsappen SqlDWException i ett undantag som utökar egenskapen. Undantag gör också följande skillnad:

  • SqlDWConnectorException representerar ett fel som utlöses av Azure Synapse-anslutningsappen
  • SqlDWSideException representerar ett fel som genereras av den anslutna Azure Synapse-instansen

Vad ska jag göra om min fråga misslyckades med felet "Ingen åtkomstnyckel hittades i sessionskonfigurationen eller den globala Hadoop-konfigurationen"?

Det här felet innebär att Azure Synapse-anslutningsappen inte kunde hitta åtkomstnyckeln till lagringskontot i konfigurationen av notebook-sessionen eller den globala Hadoop-konfigurationen för lagringskontot som anges i tempDir. Se Användning (Batch) för exempel på hur du konfigurerar åtkomsten till lagringskontot korrekt. Om en Spark-tabell skapas med Azure Synapse-anslutningsappen måste du fortfarande ange autentiseringsuppgifterna för lagringskontot för att kunna läsa eller skriva till Spark-tabellen.

Kan jag använda en signatur för delad åtkomst (SAS) för att komma åt Blob-lagringscontainern som anges av tempDir?

Azure Synapse stöder inte användning av SAS för åtkomst till Blob Storage. Azure Synapse-anslutningsappen stöder därför inte SAS för åtkomst till bloblagringscontainern som anges av tempDir.

Jag skapade en Spark-tabell med hjälp av Azure Synapse-anslutningsprogrammet med dbTable alternativet, skrev lite data till den här Spark-tabellen och tappade sedan den här Spark-tabellen. Kommer tabellen som skapas på Azure Synapse-sidan att tas bort?

Nej. Azure Synapse anses vara en extern datakälla. Azure Synapse-tabellen med det angivna dbTable namnet tas inte bort när Spark-tabellen tas bort.

Varför måste jag skriva .option("dbTable", tableName).save() i stället för bara .saveAsTable(tableName) när jag skriver en DataFrame till Azure Synapse?

Det beror på att vi vill göra följande distinktion tydlig: .option("dbTable", tableName) refererar till tabellen databas (dvs. Azure Synapse), medan .saveAsTable(tableName) refererar till Spark-tabellen. Du kan till och med kombinera de två: df.write. ... .option("dbTable", tableNameDW).saveAsTable(tableNameSpark) som skapar en tabell i Azure Synapse med namnet tableNameDW och en extern tabell i Spark med namnet tableNameSpark som backas upp av Azure Synapse-tabellen.

Varning

Se upp för följande skillnad mellan .save() och .saveAsTable():

  • För df.write. ... .option("dbTable", tableNameDW).mode(writeMode).save()fungerar writeMode som förväntat i Azure Synapse-tabellen.
  • För df.write. ... .option("dbTable", tableNameDW).mode(writeMode).saveAsTable(tableNameSpark)fungerar writeMode i Spark-tabellen, medan skrivs tableNameDW över tyst om den redan finns i Azure Synapse.

Det här beteendet skiljer sig inte från att skriva till någon annan datakälla. Det är bara en varning för Spark DataFrameWriter-API:et.