Delen via

Spark-connector voor SQL-databases (Preview)

Belangrijk

Deze functie is beschikbaar als preview-versie.

De Spark-connector voor SQL-databases is een bibliotheek met hoge prestaties waarmee u SQL Server-, Azure SQL-databases en Fabric SQL-databases kunt lezen en schrijven. De connector biedt de volgende mogelijkheden:

  • Gebruik Spark om grote schrijf- en leesbewerkingen uit te voeren op Azure SQL Database, Azure SQL Managed Instance, SQL Server op Azure VM en Fabric SQL-databases.
  • Wanneer u een tabel of weergave gebruikt, ondersteunt de connector beveiligingsmodellen die zijn ingesteld op sql-engineniveau. Deze modellen omvatten beveiliging op objectniveau (OLS), beveiliging op rijniveau (RLS) en beveiliging op kolomniveau (CLS).

De connector is vooraf geïnstalleerd in de Fabric-runtime, dus u hoeft deze niet afzonderlijk te installeren.

Authenticatie

Microsoft Entra-verificatie is geïntegreerd met Microsoft Fabric.

  • Wanneer u zich aanmeldt bij de Fabric-werkruimte, worden uw referenties automatisch doorgegeven aan de SQL-engine voor verificatie en autorisatie.
  • Vereist dat Microsoft Entra-id is ingeschakeld en geconfigureerd op uw SQL-database-engine.
  • Er is geen extra configuratie nodig in uw Spark-code als Microsoft Entra-id is ingesteld. De inloggegevens worden automatisch gekoppeld.

U kunt ook de SQL-verificatiemethode gebruiken (door een SQL-gebruikersnaam en -wachtwoord op te geven) of een service-principal (door een Azure-toegangstoken op te geven voor verificatie op basis van apps).

Permissions

Als u de Spark-connector wilt gebruiken, moet uw identiteit, ongeacht of het een gebruiker of een app is, beschikken over de benodigde databasemachtigingen voor de doel-SQL-engine. Deze machtigingen zijn vereist voor het lezen van of schrijven naar tabellen en weergaven.

Voor Azure SQL Database, Azure SQL Managed Instance en SQL Server op Azure VM:

  • De identiteit die de operatie uitvoert, heeft doorgaans db_datawriter- en db_datareader-machtigingen nodig, en optioneel db_owner voor volledige controle.

Voor Fabric SQL-databases:

  • De identiteit heeft doorgaans db_datawriter- en db_datareader-machtigingen nodig, en optioneel ook db_owner-machtigingen.
  • De identiteit heeft ook ten minste leesmachtigingen nodig voor de Fabric SQL-database op itemniveau.

Opmerking

Als u een service-principal gebruikt, kan deze worden uitgevoerd als een app (geen gebruikerscontext) of als een gebruiker wanneer gebruikersimitatie is ingeschakeld. De service-principal moet over de vereiste databasemachtigingen beschikken voor de bewerkingen die u wilt uitvoeren.

Voorbeelden van gebruik en code

In deze sectie bieden we codevoorbeelden om te laten zien hoe u de Spark-connector effectief kunt gebruiken voor SQL-databases. Deze voorbeelden hebben betrekking op verschillende scenario's, waaronder het lezen van en schrijven naar SQL-tabellen en het configureren van de connectoropties.

Ondersteunde opties

De minimaal vereiste optie is url als "jdbc:sqlserver://<server>:<port>;database=<database>;" of als spark.mssql.connector.default.url ingesteld.

  • Wanneer de url gegevens zijn opgegeven:

    • url Gebruik altijd als eerste voorkeur.
    • Als spark.mssql.connector.default.url niet is ingesteld, zal de connector het instellen en dit hergebruiken voor toekomstig gebruik.

  • Wanneer het url niet is opgegeven:

    • Als spark.mssql.connector.default.url is ingesteld, gebruikt de connector de waarde van de spark-config.
    • Als spark.mssql.connector.default.url niet is ingesteld, wordt er een fout weergegeven omdat de vereiste details niet beschikbaar zijn.

Deze connector ondersteunt de opties die hier zijn gedefinieerd: SQL DataSource JDBC-opties

De connector ondersteunt ook de volgende opties:

Optie Standaardwaarde Description
reliabilityLevel BEST_EFFORT (beste inspanning) Hiermee bepaalt u de betrouwbaarheid van invoegbewerkingen. Mogelijke waarden: BEST_EFFORT (standaard, snelste, kan leiden tot dubbele rijen als een uitvoerder opnieuw wordt opgestart), NO_DUPLICATES (langzamer, zorgt ervoor dat er geen dubbele rijen worden ingevoegd, zelfs als een uitvoerder opnieuw wordt opgestart). Kies op basis van uw tolerantie voor duplicaten en prestatiebehoeften.
isolationLevel "READ_COMMITTED" Hiermee stelt u het niveau van transactieisolatie in voor SQL-bewerkingen. Mogelijke waarden: READ_COMMITTED (standaard, voorkomt het lezen van niet-doorgevoerde gegevens), READ_UNCOMMITTED, , REPEATABLE_READSNAPSHOT, SERIALIZABLE. Hogere isolatieniveaus kunnen gelijktijdigheid verminderen, maar de gegevensconsistentie verbeteren.
tableLock "onwaar" Hiermee bepaalt u of de hint voor het vergrendelen op tabelniveau van SQL Server TABLOCK wordt gebruikt tijdens het invoegen van bewerkingen. Mogelijke waarden: true (maakt TABLOCK mogelijk, waardoor de prestaties van bulksgewijs schrijven kunnen worden verbeterd), false (standaard wordt tablock niet gebruikt). Instellen op true kan de doorvoersnelheid voor grote invoegacties verhogen, maar kan de gelijktijdigheid van andere bewerkingen op de tabel verminderen.
schemaCheckEnabled waar Hiermee bepaalt u of strikte schemavalidatie wordt afgedwongen tussen uw Spark DataFrame en de SQL-tabel. Mogelijke waarden: true (standaard, dwingt strikte schemakoppeling af), false (biedt meer flexibiliteit en kan enkele schemacontroles overslaan). Instellen op false kan helpen bij schema mismatches, maar kan leiden tot onverwachte resultaten als de structuren aanzienlijk verschillen.

Andere bulk-API-opties kunnen worden ingesteld als opties op de DataFrame api en worden doorgegeven aan api's voor bulksgewijs kopiëren bij schrijven.

Voorbeeld van schrijven en lezen

De volgende code laat zien hoe u gegevens schrijft en leest met behulp van de mssql("<schema>.<table>") methode met automatische Microsoft Entra ID-verificatie.

Aanbeveling

Gegevens worden inline gemaakt voor demonstratiedoeleinden. In een productiescenario zou u doorgaans gegevens lezen uit een bestaande bron of een complexere DataFramebron maken.

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

U kunt ook kolommen selecteren, filters toepassen en andere opties gebruiken wanneer u gegevens uit de SQL-database-engine leest.

Voorbeelden van verificatie

In de volgende voorbeelden ziet u hoe u andere verificatiemethoden gebruikt dan Microsoft Entra ID, zoals service-principal (toegangstoken) en SQL-verificatie.

Opmerking

Zoals eerder vermeld, wordt verificatie van Microsoft Entra-id automatisch verwerkt wanneer u zich aanmeldt bij de Fabric-werkruimte. U hoeft deze methoden dus alleen te gebruiken als voor uw scenario dit vereist is.

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

Ondersteunde dataframe-opslagmodi

Wanneer u gegevens van Spark naar SQL-databases schrijft, kunt u kiezen uit verschillende opslagmodi. Met de modus Opslaan kunt u bepalen hoe gegevens worden geschreven wanneer de doeltabel al bestaat en kan dit van invloed zijn op schema, gegevens en indexering. Als u deze modi begrijpt, voorkomt u onverwacht gegevensverlies of wijzigingen.

Deze connector ondersteunt de opties die hier zijn gedefinieerd: Spark Save-functies

  • ErrorIfExists (standaardopslagmodus): Als de doeltabel bestaat, wordt de schrijfbewerking afgebroken en wordt er een uitzondering geretourneerd. Anders wordt er een nieuwe tabel gemaakt met gegevens.

  • Negeren: Als de doeltabel bestaat, negeert de schrijfbewerking de aanvraag en wordt er geen fout geretourneerd. Anders wordt er een nieuwe tabel gemaakt met gegevens.

  • Overschrijven: Als de doeltabel bestaat, wordt de tabel verwijderd, opnieuw gemaakt en worden nieuwe gegevens toegevoegd.

    Opmerking

    Wanneer u gebruikt overwrite, gaan het oorspronkelijke tabelschema (met name MSSQL-exclusieve gegevenstypen) en tabelindexen verloren en vervangen door het schema dat is afgeleid van uw Spark DataFrame. Als u wilt voorkomen dat schema en indexen verloren gaan, gebruikt .option("truncate", true) u in plaats van overwrite.

  • Toevoegen: Als de doeltabel bestaat, worden er nieuwe gegevens aan toegevoegd. Anders wordt er een nieuwe tabel gemaakt met gegevens.

Troubleshoot

Wanneer het proces is voltooid, verschijnt de uitvoer van uw Spark-leesactie in het uitvoergebied van de cel. Fouten van com.microsoft.sqlserver.jdbc.SQLServerException komen rechtstreeks van SQL Server. Gedetailleerde foutinformatie vindt u in de Spark-toepassingslogboeken.

Verwante inhoud

  • Last updated on