Spark connector for SQL databases (Preview)

Tärkeää

SQL-tietokantojen Spark-liitin on suorituskykyinen kirjasto, jonka avulla voit lukea ja kirjoittaa SQL Serveristä, Azure SQL -tietokannoista ja Fabric SQL -tietokannoista. Liitin tarjoaa seuraavat ominaisuudet:

Käytä Spintia suorittaaksesi suuria kirjoitus- ja lukutoimintoja Azure SQL Databasessa, Azure SQL Managed Instancessa, SQL Serverissä Azure VM:ssä ja Fabric SQL -tietokannoissa.
Kun käytät taulukkoa tai näkymää, liitin tukee turvallisuusmalleja, jotka on asetettu SQL-moottorin tasolle. Näitä malleja ovat objektitason suojaus (OLS), rivitason suojaus (RLS) ja saraketason suojaus (CLS).

Liitin on valmiiksi asennettu Fabric-ajonaikaan, joten sitä ei tarvitse asentaa erikseen.

Todennus

Microsoft Entra -todennus on integroitu Microsoft Fabriciin.

Kun kirjaudut Fabric-työtilaan, tunnuksesi siirretään automaattisesti SQL-moottorille todennukseen ja valtuutukseen.
Vaatii, että Microsoft Entra ID on käytössä ja konfiguroituna SQL-tietokantamoottorissasi.
Lisäasetuksia ei tarvita Spark-koodissasi, jos Microsoft Entra ID on asetettu. Tunnukset yhdistetään automaattisesti.

Voit myös käyttää SQL-todennusmenetelmää (määrittämällä SQL-käyttäjätunnus ja salasana) tai palveluperiaatetta (tarjoamalla Azure-käyttötunniste sovelluspohjaiseen tunnistautumiseen).

Käyttöoikeudet

Spark-liittimen käyttämiseksi identiteettisi – olipa kyseessä käyttäjä tai sovellus – täytyy sisältää tarvittavat tietokantaoikeudet kohde-SQL-moottorille. Nämä oikeudet vaaditaan taulujen ja näkymien lukemiseen tai niihin kirjoittamiseen.

Azure SQL Database, Azure SQL Managed Instance ja SQL Server on Azure VM:

Operaatiota ajava identiteetti tarvitsee db_datawriter tyypillisesti oikeudet ja db_datareader oikeudet, ja tarvittaessa db_owner täyden hallinnan.

Fabric SQL -tietokannoille:

Identiteetti yleensä tarvitsee db_datawriter ja db_datareader oikeudet, ja tarvittaessa db_owner.
Identiteetti vaatii myös vähintään lukuoikeuden Fabric SQL -tietokannassa kohdetasolla.

Note

Jos käytät palveluperiaatetta, se voi toimia sovelluksena (ilman käyttäjäkontekstia) tai käyttäjänä, jos käyttäjäjäljittely on käytössä. Palvelupäämiehellä on oltava tarvittavat tietokantaoikeudet niille operaatioille, joita haluat suorittaa.

Käyttö- ja koodiesimerkit

Tässä osiossa annamme koodiesimerkkejä, jotka osoittavat, miten Spark-liitintä käytetään tehokkaasti SQL-tietokannoissa. Nämä esimerkit kattavat erilaisia tilanteita, kuten SQL-taulukoista lukemisen ja niiden kirjoittamisen sekä liitinasetusten konfiguroinnin.

Tuetut vaihtoehdot

Vähimmäisvaatimus on url as "jdbc:sqlserver://<server>:<port>;database=<database>;" tai asetettu spark.mssql.connector.default.url.

Kun se url on annettu:
- Käytä url aina ensisijaisena vaihtoehtona.
- Jos spark.mssql.connector.default.url sitä ei ole asetettu, liitin asettaa sen ja käyttää sitä uudelleen tulevaa käyttöä varten.
Kun sitä url ei ole tarjolla:
- Jos spark.mssql.connector.default.url liitin on asetettu, liitin käyttää spark-konfiguraatiosta saatua arvoa.
- Jos spark.mssql.connector.default.url sitä ei ole asetettu, virhe syntyy, koska vaaditut tiedot eivät ole saatavilla.

Tämä liitin tukee tässä määriteltyjä vaihtoehtoja: SQL DataSource JDBC Options

Liitin tukee myös seuraavia vaihtoehtoja:

Vaihtoehto	Oletusarvo	Kuvaus
`reliabilityLevel`	"BEST_EFFORT"	Kontrolloi insert-toimintojen luotettavuutta. Mahdolliset arvot: `BEST_EFFORT` (oletusarvo, nopein, voi johtaa päällekkäisiin riveihin, jos toimeenpanija käynnistyy uudelleen), `NO_DUPLICATES` (hitaampi, varmistaa, ettei päällekkäisiä rivejä lisätä, vaikka suorittaja käynnistyisi uudelleen). Valitse sen mukaan, miten sietoudut päällekkäisyyksiin ja suorituskykytarpeitasi.
`isolationLevel`	"READ_COMMITTED"	Asettaa transaktioiden eristystason SQL-operaatioille. Mahdolliset arvot: `READ_COMMITTED` (oletusarvo, estää sitoutumattoman datan lukemisen), `READ_UNCOMMITTED`, `REPEATABLE_READ`, `SNAPSHOT`, `SERIALIZABLE`. Korkeammat eristystasot voivat vähentää samanaikaisuutta, mutta parantaa datan johdonmukaisuutta.
`tableLock`	"Väärin"	Hallitsee, käytetäänkö SQL Server TABLOCK-taulutason lukitusvihjettä insert-operaatioissa. Mahdolliset arvot: `true` (mahdollistaa TABLOCKin, joka voi parantaa massakirjoituskykyä), `false` (oletuksena, ei käytä TABLOCKia). Asetus voi `true` lisätä läpimenoa suurille inserteille, mutta vähentää samanaikaisuutta muille taulukon operaatioille.
`schemaCheckEnabled`	"true"	Se hallitsee, valvotaanko tiukka skeeman validointi Sparkin `DataFrame` ja SQL-taulun välillä. Mahdolliset arvot: `true` (oletusarvo, vaatii tiukan skeeman sovittamisen), `false` (mahdollistaa enemmän joustavuutta ja saattaa jättää joitakin skeematarkistuksia väliin). Asetuksen asettaminen `false` voi auttaa skeema-epäsuhtauksissa, mutta voi johtaa odottamattomiin tuloksiin, jos rakenteet eroavat merkittävästi.

Muita Bulk API -vaihtoehtoja voi asettaa vaihtoehdoiksi DataFrame ja ne välitetään bulk copy API:lle kirjoituksen yhteydessä.

Kirjoita ja lue esimerkki

Seuraava koodi näyttää, miten dataa kirjoitetaan ja luetaan käyttämällä mssql("<schema>.<table>") menetelmää, jossa käytetään automaattista Microsoft Entra ID -tunnistautumista.

Vihje

Data luodaan inline-muodossa demonstrointia varten. Tuotantotilanteessa luetaan tyypillisesti dataa olemassa olevasta lähteestä tai luodaan monimutkaisempi DataFrame.

PySpark
Skalaa 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

Voit myös valita sarakkeita, soveltaa suodattimia ja käyttää muita vaihtoehtoja, kun luet dataa SQL-tietokantamoottorista.

Todennusesimerkit

Seuraavat esimerkit osoittavat, miten käytetään muita todennusmenetelmiä kuin Microsoft Entra ID:tä, kuten Service Principal (access token) ja SQL-todennus.

Note

Kuten aiemmin mainittiin, Microsoft Entra ID -tunnistautuminen hoidetaan automaattisesti, kun kirjaudut Fabric-työtilaan, joten näitä menetelmiä tarvitsee käyttää vain, jos tilanteesi niitä vaatii.

Palvelupäähenkilö tai pääsytunnus
Käyttäjä/Salasana

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

Tuetut DataFrame-tallennustilat

Kun kirjoitat dataa Sparkista SQL-tietokantoihin, voit valita useista tallennustavoista. Tallennustilat ohjaavat, miten dataa kirjoitetaan, kun kohdetaulu on jo olemassa, ja voivat vaikuttaa skeemaan, dataan ja indeksointiin. Näiden tilojen ymmärtäminen auttaa välttämään odottamattoman datan menetyksen tai muutoksen.

Tämä liitin tukee tässä määriteltyjä asetuksia: Spark Save -toiminnot

ErrorIfExists (oletustallennustila): Jos kohdetaulu on olemassa, kirjoitus keskeytetään ja poikkeus palautetaan. Muussa tapauksessa luodaan uusi taulukko tiedoista.
Sivuuta: Jos kohdetaulu on olemassa, kirjoitus jättää pyynnön huomiotta eikä palauta virhettä. Muussa tapauksessa luodaan uusi taulukko tiedoista.
Ylikirjoitus: Jos kohdetaulu on olemassa, taulu poistetaan, luodaan uudelleen ja lisätään uutta dataa.

Note

Kun käytät overwrite, alkuperäinen taulukkoskeema (erityisesti MSSQL:n eksklusiiviset tietotyypit) ja taulukkoindeksit katoavat ja korvautuvat Spark DataFramestasi päätellellä skeemalla. Välttääksesi skeeman ja indeksien menetyksen, käytä .option("truncate", true) sen sijaan overwrite.
Liitä: Jos kohdetaulu on olemassa, siihen lisätään uutta dataa. Muussa tapauksessa luodaan uusi taulukko tiedoista.

Vianmääritys

Kun prosessi päättyy, Spark-lukuoperaation tulos ilmestyy solun lähtöalueelle. Virheet com.microsoft.sqlserver.jdbc.SQLServerException tulevat suoraan SQL Serveristä. Yksityiskohtaiset virhetiedot löytyvät Spark-sovelluslokista.

Azuren SQLtietokannan
Fabric SQL -tietokannat
Azure SQL Database - Todennus ja valtuutus

Palaute

Onko tästä sivusta apua?

Last updated on 2025-11-25