Azure Synapse Analytics

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 viktig komponent 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 analyser 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 implementering av datakällan för Apache Spark som använder Azure Blob Storage och PolyBase eller -instruktionen COPY i Azure Synapse för att effektivt överföra stora mängder data mellan ett Azure Databricks-kluster och ett 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.

Anteckning

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

Den 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 kö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 databasen för Azure Synapse.

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 ett huvudnamn för tjänsten för autentisering.

Användarnamn och lösenord

Vi rekommenderar att du använder anslutningssträngarna som tillhandahålls av Azure Portal 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. Du kan kontrollera att SSL-krypteringen är aktiverad genom att söka efter encrypt=true i anslutningssträngen.

För att Spark-drivrutinen ska kunna nå Azure Synapse rekommenderar vi att du ställer in Tillåt åtkomst till Azure-tjänster i brandväggsfönstret på Azure Synapse-servern via Azure Portal. 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 hur du använder autentiseringsuppgifter för tjänstens huvudnamn för att komma åt ett Azure Storage-konto finns i Åtkomst Azure Data Lake Storage Gen2 med OAuth 2.0 med azure-tjänstens huvudnamn. Du måste ange enableServicePrincipalAuth alternativet till true i anslutningskonfigurationen Parametrar för att göra det möjligt för anslutningsappen att autentisera med ett huvudnamn för tjänsten.

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 en mellanhand för att lagra massdata vid läsning från eller skrivning till Azure Synapse. Spark ansluter till lagringscontainern med någon av de inbyggda anslutningsprogrammen: Azure Blob Storage eller Azure Data Lake Storage (ADLS) Gen2. Azure Data Lake Storage Gen1stöds inte och endast SSL-krypterad HTTPS-åtkomst tillåts. Därför är wasbs de enda URI-scheman som stöds och abfss.

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-session (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>.blob.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 som SparkContext delas av alla notebook-filer.

Scala
sc.hadoopConfiguration.set(
  "fs.azure.account.key.<your-storage-account-name>.blob.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-kommandon 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>.blob.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 så fall identifierar Azure Synapse-anslutningsappen automatiskt den kontoåtkomstnyckel som angetts i konfigurationen av notebook-sessionen eller den globala Hadoop-konfigurationen och vidarebefordrar lagringskontots åtkomstnyckel till den anslutna Azure Synapse-instansen genom att skapa en tillfällig Azure-databasbegränsad autentiseringsuppgift .

Om du använder ADLS Gen2 + OAuth 2.0-autentisering eller om din Azure Synapse-instans är konfigurerad 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 databasbegränsade autentiseringsuppgiften och ingen SECRET.

Stöd för direktuppspelning

Azure Synapse-anslutningsappen erbjuder effektivt och skalbart stöd för structured streaming-skrivning 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 lämpar sig för databearbetning i realtid i vissa fall.

Feltoleranssemantik

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 tillförlitligt spåra frågans förlopp 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 för att 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>.blob.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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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>.blob.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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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>.blob.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 'wasbs://<your-container-name>@<your-storage-account-name>.blob.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 'wasbs://<your-container-name>@<your-storage-account-name>.blob.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>.blob.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 = "wasbs://<your-container-name>@<your-storage-account-name>.blob.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 = "wasbs://<your-container-name>@<your-storage-account-name>.blob.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 = "wasbs://<your-container-name>@<your-storage-account-name>.blob.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>.blob.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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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>.blob.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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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 diverse konfigurationsparametrar.

I det här avsnittet:

Lagringslägen som stöds för batchskrivningar

Azure Synapse-anslutningsappen stöder ErrorIfExists, Ignore, Appendoch Overwrite spara lägen där standardläget är ErrorIfExists. Mer information om lagringslägen som stöds i Apache Spark finns i Spark SQL dokumentation om lagringslä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 Structured Streaming (Strukturerad direktuppspelning).

Skriva semantik

Anteckning

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

Förutom PolyBase stöder Azure Synapse-anslutningsappen -instruktionenCOPY. Instruktionen COPY erbjuder ett enklare 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 till Azure Synapse.

Som standard identifierar anslutningsappen automatiskt den 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> antingen ska polybase använda PolyBase eller copy för 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 hjälp av kommandot CREATE MASTER KEY .

Om du vill läsa Azure Synapse tabell som anges via dbTable eller tabeller som anges i querymåste JDBC-användaren dessutom ha behörighet att komma åt de Azure Synapse tabellerna. Om du vill skriva tillbaka data till en Azure Synapse tabell som anges 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 vid användning av extern datakälla
Batchskrivning KONTROLL Se Batch-skrivning
Direktuppspelningsskrivning KONTROLL Se Direktuppspelningsskrivning
Läs KONTROLL Läs mer

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

Anteckning

Tillgänglig i Databricks Runtime 8.4 och senare.

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

Om du vill 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 databasbegränsad 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:

Anteckning

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 för 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 EN EXTERN DATAKÄLLA

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

INSERT

CREATE TABLE

ÄNDRA VALFRITT SCHEMA

ÄNDRA EN EXTERN DATAKÄLLA

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

INSERT

CREATE TABLE

ÄNDRA VALFRITT SCHEMA

ÄNDRA EN EXTERN DATAKÄLLA

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

INSERT

CREATE TABLE

ÄNDRA VALFRITT SCHEMA

ÄNDRA EN EXTERN DATAKÄLLA

ÄNDRA ETT 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äs CREATE TABLE

ÄNDRA VALFRITT SCHEMA

ÄNDRA EN EXTERN DATAKÄLLA

ÄNDRA ETT EXTERNT FILFORMAT

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

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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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", "wasbs://<your-container-name>@<your-storage-account-name>.blob.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 'wasbs://<your-container-name>@<your-storage-account-name>.blob.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 = "wasbs://<your-container-name>@<your-storage-account-name>.blob.core.windows.net/<your-directory-name>"
   externalDataSource = "<your-pre-provisioned-data-source>")

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

Anteckning

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

ALTER ON SCHEMA :: dbo
Direktuppspelningsskrivning ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT
ADMINISTRERA MASSÅTGÄRDER FÖR DATABASER

INSERT

CREATE TABLE

ALTER ON SCHEMA :: dbo

Parametrar

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

Parameter Krävs Standardvärde Kommentarer
dbTable Ja, såvida inte query har angetts Inget standardvärde Tabellen som du vill skapa eller läsa 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.

Varianten som tidigare stöds dbtable är inaktuell och kommer att ignoreras i framtida versioner. Använd "kamelfallets" namn 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 No Inget standardvärde Användarnamnet Azure Synapse. Måste användas tillsammans med password alternativet . Kan endast användas om användaren och lösenordet inte skickas i URL:en. Om båda skickas resulterar det i ett fel.
password No Inget standardvärde Lösenordet för Azure Synapse. Måste användas tillsammans med user alternativet . Kan endast användas om användaren och lösenordet inte skickas i URL:en. Om båda skickas resulterar det i ett fel.
url Yes Inget standardvärde En JDBC-URL med sqlserver angivet som underprotokol. Vi rekommenderar att du använder anslutningssträngen som tillhandahålls av Azure Portal. Inställning
encrypt=true rekommenderas starkt eftersom det aktiverar SSL-kryptering av JDBC-anslutningen. Om user och password anges separat behöver du inte inkludera dem i URL:en.
jdbcDriver No Bestäms av JDBC-URL:ens underprotokol Klassnamnet på den JDBC-drivrutin som ska användas. Den här klassen måste finnas i 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 ska bestämmas av JDBC-URL:ens underprotokol.

Varianten som tidigare stöds jdbc_driver är inaktuell och kommer att ignoreras i framtida versioner. Använd "kamelfallets" namn i stället.
tempDir Yes Inget standardvärde En wasbs URI. Vi rekommenderar att du använder en dedikerad Blob Storage-container för Azure Synapse.

Varianten som tidigare stöds tempdir är inaktuell och kommer att ignoreras i framtida versioner. Använd "kamelfallets" namn i stället.
tempFormat No PARQUET Det format i vilket temporära filer ska sparas i bloblagret när du skriver till Azure Synapse. Standardvärdet är ; inga andra värden tillåts PARQUETjust nu.
tempCompression No SNAPPY Komprimeringsalgoritmen som ska användas för att koda/avkoda tillfälligt av både Spark och Azure Synapse. För närvarande stöds värden: UNCOMPRESSED, SNAPPY och GZIP.
forwardSparkAzureStorageCredentials No 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.

Varianten som tidigare stöds forward_spark_azure_storage_credentials är inaktuell och kommer att ignoreras i framtida versioner. Använd "kamelfallets" namn i stället.
useAzureMSI No falskt Om truekommer biblioteket att ange IDENTITY = 'Managed Service Identity' och nej SECRET för de databasbegränsade autentiseringsuppgifter 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 No 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 No CLUSTERED COLUMNSTORE INDEX, DISTRIBUTION = ROUND_ROBIN En sträng som används för att ange tabellalternativ när du skapar den Azure Synapse tabellen som anges via dbTable. Den här strängen WITH skickas bokstavligen till satsen i SQL-instruktionen CREATE TABLE som utfärdas mot Azure Synapse.

Varianten som tidigare stöds table_options är inaktuell och kommer att ignoreras i framtida versioner. Använd "kamelfallets" namn i stället.
preActions No Inget standardvärde (tom sträng) En ; separat 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 No Inget standardvärde (tom sträng) En ; separat 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 No 256 StringTypei 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
dbTablei Azure Synapse.

Varianten som tidigare stöds maxstrlength är inaktuell och kommer att ignoreras i framtida versioner. Använd "kamelfallets" namn i stället.
checkpointLocation Yes 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 No 0 Anger hur många (senaste) tillfälliga kataloger som ska behållas för regelbunden rensning av mikrobatchar i strömning. När värdet 0är inställt på utlöses katalogborttagningen omedelbart efter att mikrobatch har checkats in, annars behålls antalet senaste mikrobatchar och resten av katalogerna tas bort. Använd -1 för att inaktivera periodisk rensning.
applicationName No 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 JDBC-URL:en till som standardvärde för taggen. Standardvärdet förhindrar att Azure DB-övervakningsverktyget genererar falska SQL inmatningsaviseringar mot frågor.
maxbinlength No Inget standardvärde Kontrollera kolumnlängden BinaryType för kolumner. Den här parametern översätts som VARBINARY(maxbinlength).
identityInsert No falskt Anger till true aktiverar IDENTITY_INSERT läge, vilket infogar ett DataFrame-angivet värde i identitetskolumnen i den Azure Synapse tabellen.

Se Uttryckligen infoga värden i en IDENTITY-kolumn.
externalDataSource No Inget standardvärde En företablerad 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, se Obligatorisk Azure Synapse behörigheter för PolyBase med alternativet extern datakälla.
maxErrors No 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 dokumentationen i SKAPA EXTERN TABELL och MAXERRORS-dokumentation i COPY.

Anteckning

  • 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.
  • checkpointLocationoch 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.

Fråge-pushdown till Azure Synapse

Azure Synapse-anslutningsappen implementerar en uppsättning optimeringsregler för att skicka ned 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 tecken och strängomkastningar

För operatorn Limit stöds pushdown endast när ingen ordning har angetts. Ett exempel:

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

Anteckning

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

Fråge-pushdown som skapats med Azure Synapse-anslutningsappen är aktiverad som standard. Du kan inaktivera det genom att ange spark.databricks.sqldw.pushdown till false.

Tillfällig datahantering

Den 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 datarensningen 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 skapas 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

Anslutningsappen Azure Synapse automatiserar dataöverföringen 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 SOURCE, EXTERNAL FILE FORMAToch EXTERNAL TABLE i bakgrunden. Dessa objekt lever bara under hela varaktigheten för motsvarande Spark-jobb och bör tas bort automatiskt därefter.

När ett kluster kör en fråga med hjälp av Azure Synapse-anslutningsappen, om Spark-drivrutinsprocessen kraschar eller startas om med kraft, 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, Azure Synapse-anslutningsappen prefix 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

Den Azure Synapse-anslutningsappen tar inte bort den kontrollpunktstabell för direktuppspelning som skapas när ny strömmande fråga startas. Det här beteendet är konsekvent med checkpointLocation på DBFS. Därför rekommenderar vi att du regelbundet tar bort kontrollpunktstabeller samtidigt som du tar bort kontrollpunktsplatser i DBFS för frågor som inte kommer att köras i framtiden eller som redan har tagits bort från 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 strömmande frå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 (FAQ)

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?

Som hjälp vid felsökning av 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:

  • SqlDWConnectorExceptionrepresenterar ett fel som utlöses av Azure Synapse-anslutningsappen
  • SqlDWSideExceptionrepresenterar ett fel som utlöses 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 Storage kontoåtkomst korrekt. Om en Spark-tabell skapas med Azure Synapse anslutningsapp måste du fortfarande ange åtkomstautentiseringsuppgifterna 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. Därför stöder inte Azure Synapse-anslutningstjänsten SAS för åtkomst till bloblagringscontainern som anges av tempDir.

Jag skapade en Spark-tabell med Azure Synapse anslutningsprogram med dbTable alternativet, skrev några data till den här Spark-tabellen och släppte 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. Den 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 anropad tableNameDW och en extern tabell i Spark med namnet tableNameSpark som backas upp av tabellen Azure Synapse.

Varning

Akta dig för följande skillnad mellan .save() och .saveAsTable():

  • writeMode För df.write. ... .option("dbTable", tableNameDW).mode(writeMode).save()agerar i tabellen Azure Synapse som förväntat.
  • writeMode För df.write. ... .option("dbTable", tableNameDW).mode(writeMode).saveAsTable(tableNameSpark)agerar på Spark-tabellen, medan tableNameDWskrivs ö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 om Spark DataFrameWriter-API:et.