Spark connector til SQL-databaser (Forhåndsvisning)

Vigtigt

Denne funktion er en prøveversion.

Spark-connectoren til SQL-databaser er et højtydende bibliotek, der lader dig læse fra og skrive til SQL Server, Azure SQL-databaser og Fabric SQL-databaser. Connectoren indeholder følgende funktioner:

Brug Spark til at køre store skrive- og læseoperationer på Azure SQL Database, Azure SQL Managed Instance, SQL Server på Azure VM og Fabric SQL-databaser.
Når du bruger en tabel eller en visning, understøtter connectoren sikkerhedsmodeller sat på SQL-motorniveau. Disse modeller omfatter sikkerhed på objektniveau (OLS), sikkerhed på rækkeniveau (RLS) og sikkerhed på kolonneniveau (CLS).

Connectoren er forudinstalleret i Fabric-runtime, så du behøver ikke installere den separat.

Godkendelse

Microsoft Entra-autentificering er integreret med Microsoft Fabric.

Når du logger ind på Fabric-arbejdsområdet, bliver dine legitimationsoplysninger automatisk sendt til SQL-motoren til autentificering og autorisation.
Det kræver, at Microsoft Entra ID er aktiveret og konfigureret på din SQL-databasemotor.
Der er ikke behov for ekstra konfiguration i din Spark-kode, hvis Microsoft Entra ID er sat op. Oplysningerne bliver automatisk kortlagt.

Du kan også bruge SQL-autentificeringsmetoden (ved at angive et SQL-brugernavn og adgangskode) eller en serviceprincipal (ved at tilbyde en Azure-adgangstoken til app-baseret autentificering).

Tilladelser

For at bruge Spark-connectoren skal din identitet – uanset om det er en bruger eller en app – have de nødvendige databasetilladelser til den målrettede SQL-motor. Disse tilladelser kræves for at læse fra eller skrive til tabeller og visninger.

For Azure SQL Database, Azure SQL Managed Instance og SQL Server på Azure VM:

Identiteten, der kører operationen, kræver db_datawriter typisk tilladelser db_datareader og eventuelt db_owner fuld kontrol.

For Fabric SQL-databaser:

Identiteten kræver db_datawriter typisk og db_datareader tilladelser, og valgfrit db_owner.
Identiteten kræver også mindst læsetilladelse på Fabric SQL-databasen på item-niveau.

Notat

Hvis du bruger en service principal, kan den køre som en app (uden brugerkontekst) eller som en bruger, hvis brugerimitation er aktiveret. Servicechefen skal have de nødvendige databaserettigheder til de operationer, du ønsker at udføre.

Anvendelses- og kodeeksempler

I dette afsnit giver vi kodeeksempler, der demonstrerer, hvordan man effektivt bruger Spark-connectoren til SQL-databaser. Disse eksempler dækker forskellige scenarier, herunder læsning fra og skrivning til SQL-tabeller samt konfiguration af connector-mulighederne.

Understøttede muligheder

Den minimale nødvendige mulighed er url som "jdbc:sqlserver://<server>:<port>;database=<database>;" eller sæt spark.mssql.connector.default.url.

Når den url er angivet:
- Brug altid url det som førsteprioritet.
- Hvis det spark.mssql.connector.default.url ikke er sat, vil stikket sætte det og genbruge det til fremtidig brug.
Når det ikke er givet url :
- Hvis spark.mssql.connector.default.url er sat, bruger connectoren værdien fra spark-konfigurationen.
- Hvis ikke spark.mssql.connector.default.url er sat, kastes en fejl, fordi de nødvendige oplysninger ikke er tilgængelige.

Denne connector understøtter de muligheder, der er defineret her: SQL DataSource JDBC Options

Stikket understøtter også følgende muligheder:

Valgmulighed	Standardværdi	Beskrivelse
`reliabilityLevel`	"BEST_EFFORT"	Kontrollerer pålideligheden af indsættelsesoperationer. Mulige værdier: `BEST_EFFORT` (standard, hurtigst, kan resultere i duplikerede rækker, hvis en eksekver genstarter), (langsommere, `NO_DUPLICATES` sikrer at ingen dubletter indsættes, selv hvis en eksekver genstarter). Vælg ud fra din tolerance for dubletter og dine præstationsbehov.
`isolationLevel`	"READ_COMMITTED"	Sætter transaktionsisolationsniveauet for SQL-operationer. Mulige værdier: `READ_COMMITTED` (standard, forhindrer læsning af ikke-forpligtede data), `READ_UNCOMMITTED`, , `REPEATABLE_READSNAPSHOT`, , `SERIALIZABLE`. Højere isolationsniveauer kan reducere samtidighed, men forbedre datakonsistensen.
`tableLock`	"falsk"	Styrer, om SQL Server TABLOCK-tabelniveau-låsehintet bruges under indsættelsesoperationer. Mulige værdier: `true` (aktiverer TABLOCK, som kan forbedre masseskrivningsydelsen), `false` (standard, bruger ikke TABLOCK). At sætte til `true` kan øge gennemstrømningen for store inserts, men kan reducere samtidighed for andre operationer på bordet.
`schemaCheckEnabled`	"sand"	Kontrollerer, om streng skemavalidering håndhæves mellem din Spark `DataFrame` og SQL-tabellen. Mulige værdier: `true` (standard, håndhæver streng skema-matching), `false` (giver mere fleksibilitet og kan springe nogle skema-tjek over). Setting to `false` kan hjælpe med skema-mismatch, men kan føre til uventede resultater, hvis strukturerne adskiller sig væsentligt.

Andre Bulk API-muligheder kan sættes som muligheder på og DataFrame sendes til bulk-kopier af API'er ved skrivning.

Skrive- og læseeksempel

Følgende kode viser, hvordan man skriver og læser data ved hjælp mssql("<schema>.<table>") af metoden med automatisk Microsoft Entra ID-autentificering.

Tips

Data oprettes inline til demonstrationsformål. I et produktionsscenarie vil du typisk læse data fra en eksisterende kilde eller skabe en mere kompleks DataFrame.

PySpark
Scala Spark

import com.microsoft.sqlserver.jdbc.spark
url = "jdbc:sqlserver://<server>:<port>;database=<database>;"
row_data = [("Alice", 1),("Bob", 2),("Charlie", 3)]
column_header = ["Name", "Age"]
df = spark.createDataFrame(row_data, column_header)
df.write.mode("overwrite").option("url", url).mssql("dbo.publicExample")
spark.read.option("url", url).mssql("dbo.publicExample").show()

url = "jdbc:sqlserver://<server>:<port>;database=<database2>;" # different database
df.write.mode("overwrite").option("url", url).mssql("dbo.tableInDatabase2") # default url is updated
spark.read.mssql("dbo.tableInDatabase2").show() # no url option specified and will use database2

import com.microsoft.sqlserver.jdbc.spark.SparkSqlImplicits._
import org.apache.spark.sql.Row
import org.apache.spark.sql.types._
val url = "jdbc:sqlserver://<server>:<port>;database=<database>;"
val row_data = Seq(
  Row("Alice", 2),
  Row("Bob", 2),
  Row("Charlie", 3)
)
val schema = List(
  StructField("Name", StringType, nullable = true),
  StructField("Age", IntegerType, nullable = true)
)
val df = spark.createDataFrame(spark.sparkContext.parallelize(row_data), StructType(schema))
df.write.mode("overwrite").option("url", url).mssql("dbo.publicExample")
spark.read.option("url", url).mssql("dbo.publicExample").show

val url = "jdbc:sqlserver://<server>:<port>;database=<database2>;" // different database
df.write.mode("overwrite").option("url", url).mssql("dbo.tableInDatabase2") // default url is updated
spark.read.mssql("dbo.tableInDatabase2").show // no url option specified and will use database2

Du kan også vælge kolonner, anvende filtre og bruge andre muligheder, når du læser data fra SQL-databasemotoren.

Autentificeringseksempler

Følgende eksempler viser, hvordan man bruger autentificeringsmetoder andre end Microsoft Entra ID, såsom service principal (adgangstok) og SQL-autentificering.

Notat

Som nævnt tidligere håndteres Microsoft Entra ID-autentificering automatisk, når du logger ind på Fabric-arbejdsområdet, så du behøver kun bruge disse metoder, hvis dit scenarie kræver det.

Service Principal eller Access Token
Bruger/Adgangskode

import com.microsoft.sqlserver.jdbc.spark
url = "jdbc:sqlserver://<server>:<port>;database=<database>;"
row_data = [("Alice", 1),("Bob", 2),("Charlie", 3)]
column_header = ["Name", "Age"]
df = spark.createDataFrame(row_data, column_header)

from azure.identity import ClientSecretCredential
credential = ClientSecretCredential(tenant_id="", client_id="", client_secret="") # service principal app
scope = "https://database.windows.net/.default"
token = credential.get_token(scope).token

df.write.mode("overwrite").option("url", url).option("accesstoken", token).mssql("dbo.publicExample")
spark.read.option("accesstoken", token).mssql("dbo.publicExample").show()

import com.microsoft.sqlserver.jdbc.spark
url = "jdbc:sqlserver://<server>:<port>;database=<database>;"
row_data = [("Alice", 1),("Bob", 2),("Charlie", 3)]
column_header = ["Name", "Age"]
df = spark.createDataFrame(row_data, column_header)
df.write.mode("overwrite").option("url", url).option("user", "").option("password", "").mssql("dbo.publicExample")
spark.read.option("user", "").option("password", "").mssql("dbo.publicExample").show()

Understøttede lagringstilstande for DataFrame

Når du skriver data fra Spark til SQL-databaser, kan du vælge mellem flere gemmetilstande. Gemmetilstande styrer, hvordan data skrives, når destinationstabellen allerede eksisterer, og kan påvirke skema, data og indeksering. At forstå disse tilstande hjælper dig med at undgå uventet datatab eller ændringer.

Denne connector understøtter de muligheder, der er defineret her: Spark Save-funktioner

ErrorIfExists (standard gemmetilstand): Hvis destinationstabellen eksisterer, afbrydes skrivningen, og en undtagelse returneres. Ellers oprettes en ny tabel med data.
Ignorer: Hvis destinationstabellen eksisterer, ignorerer skrivningen forespørgslen og returnerer ikke en fejl. Ellers oprettes en ny tabel med data.
Overskriv: Hvis destinationstabellen eksisterer, droppes tabellen, genskabes, og nye data tilføjes.

Notat

Når du bruger overwrite, mister du det oprindelige tabelskema (især MSSQL-eksklusive datatyper) og tabelindekser og erstattes af det skema, der udledes fra din Spark DataFrame. For at undgå at miste skema og indekser, brug .option("truncate", true) i stedet for overwrite.
Bilag: Hvis destinationstabellen eksisterer, tilføjes nye data til den. Ellers oprettes en ny tabel med data.

Fejlfinding

Når processen er færdig, vises outputtet fra din Spark-læseoperation i cellens outputområde. Fejl fra com.microsoft.sqlserver.jdbc.SQLServerException kommer direkte fra SQL Server. Du kan finde detaljeret fejlinformation i Spark-applikationsloggene.

Feedback

Var denne side nyttig?

Last updated on 2025-11-25