Zdieľať cez

Spark connector for SQL databases (Preview)

Dôležité

Táto funkcia je vo verzii Preview.

Spark konektor pre SQL databázy je vysokovýkonná knižnica, ktorá vám umožňuje čítať a zapisovať do SQL Serverov, Azure SQL databáz a Fabric SQL databáz. Konektor ponúka nasledujúce možnosti:

  • Použite Spark na spúšťanie veľkých operácií zápisu a čítania na Azure SQL Database, Azure SQL Managed Instance, SQL Server na Azure VM a Fabric SQL databázach.
  • Keď používate tabuľku alebo pohľad, konektor podporuje bezpečnostné modely nastavené na úrovni SQL enginu. Tieto modely zahŕňajú zabezpečenie na úrovni objektu (OLS), zabezpečenie na úrovni riadkov (RLS) a zabezpečenie na úrovni stĺpca (CLS).

Konektor je predinštalovaný v runtime Fabric, takže ho nemusíte inštalovať samostatne.

Overovanie

Autentifikácia Microsoft Entra je integrovaná s Microsoft Fabric.

  • Keď sa prihlásite do pracovného priestoru Fabric, vaše prihlasovacie údaje sa automaticky odovzdajú SQL enginu na autentifikáciu a autorizáciu.
  • Vyžaduje povolenie a konfiguráciu Microsoft Entra ID vo vašom SQL databázovom engine.
  • Nie je potrebná žiadna ďalšia konfigurácia vo vašom Spark kóde, ak je Microsoft Entra ID nastavený. Prihlasovacie údaje sa automaticky mapujú.

Môžete tiež použiť SQL autentifikovaciu metódu (zadáním SQL používateľského mena a hesla) alebo service principal (poskytnutím Azure access tokenu pre autentifikáciu cez aplikáciu).

Povolenia

Na použitie Spark konektora musí vaša identita – či už ide o používateľa alebo aplikáciu – mať potrebné databázové oprávnenia pre cieľový SQL engine. Tieto oprávnenia sú potrebné na čítanie alebo zápis do tabuliek a pohľadov.

For Azure SQL Database, Azure SQL Managed Instance a SQL Server on Azure VM:

  • Identita, ktorá operáciu vykonáva, zvyčajne potrebuje db_datawriter povolenia db_datareader , a voliteľne db_owner aj úplnú kontrolu.

Pre Fabric SQL databázy:

  • Identita zvyčajne vyžaduje db_datawriter a db_datareader oprávnenia, a voliteľne db_owner.
  • Identita tiež vyžaduje aspoň povolenie na čítanie v Fabric SQL databáze na úrovni položiek.

Poznámka

Ak použijete princíp služby, môže bežať ako aplikácia (bez používateľského kontextu) alebo ako používateľ, ak je povolená používateľská imitácia. Servisný princíp musí mať požadované databázové oprávnenia pre operácie, ktoré chcete vykonať.

Použitie a príklady kódu

V tejto sekcii poskytujeme príklady kódu, ktoré demonštrujú, ako efektívne používať konektor Spark pre SQL databázy. Tieto príklady pokrývajú rôzne scenáre, vrátane čítania a zápisu do SQL tabuliek a konfigurácie možností konektora.

Podporované možnosti

Minimálna požadovaná možnosť je url ako alebo "jdbc:sqlserver://<server>:<port>;database=<database>;" množina spark.mssql.connector.default.url.

  • Keď je poskytnuté url :

    • Vždy používajte url ako prvú preferenciu.
    • Ak spark.mssql.connector.default.url to nie je nastavené, konektor to nastaví a použije na budúce použitie.

  • Keď nie je poskytnutá url :

    • Ak spark.mssql.connector.default.url je nastavené, konektor použije hodnotu z konfigurácie iskry.
    • Ak spark.mssql.connector.default.url nie je nastavené, zobrazí sa chyba, pretože požadované údaje nie sú dostupné.

Tento konektor podporuje možnosti definované tu: SQL DataSource JDBC Options

Konektor tiež podporuje nasledujúce možnosti:

Možnosť Predvolená hodnota Popis
reliabilityLevel "BEST_EFFORT" Kontroluje spoľahlivosť operácií s vložením. Možné hodnoty: BEST_EFFORT (predvolené, najrýchlejšie, môže viesť k duplicitným riadkom, ak executor reštartuje), (pomalšie, NO_DUPLICATES zabezpečuje, že sa nevkladajú duplicitné riadky, aj keď executor reštartuje). Vyberte podľa svojej tolerancie voči duplikátom a podľa požiadaviek na výkon.
isolationLevel "READ_COMMITTED" Nastavuje úroveň izolácie transakcií pre SQL operácie. Možné hodnoty: READ_COMMITTED (predvolené, zabraňuje čítaniu nezaviazaných dát), READ_UNCOMMITTED, REPEATABLE_READ, , SNAPSHOT. SERIALIZABLE Vyššie úrovne izolácie môžu znížiť súbežnosť, ale zlepšiť konzistenciu dát.
tableLock "nepravda" Kontroluje, či sa počas vkladacích operácií používa SQL Server TABLOCK TABLOCK na úrovni tabuľkového zámku. Možné hodnoty: true (aktivuje TABLOCK, čo môže zlepšiť výkon hromadného zápisu), false (predvolené, nepoužíva TABLOCK). Nastavenie na true môže zvýšiť priepustnosť pre veľké inserty, ale môže znížiť súbežnosť pri iných operáciách na stole.
schemaCheckEnabled "true" Kontroluje, či je medzi vaším Sparkom DataFrame a SQL tabuľkou vynucovaná prísna validácia schémy. Možné hodnoty: true (predvolené, vyžaduje prísne zladenie schémy), false (umožňuje väčšiu flexibilitu a môže preskočiť niektoré kontroly schémy). Nastavenie môže false pomôcť pri nesúladoch v schémach, ale môže viesť k nečakaným výsledkom, ak sa štruktúry výrazne líšia.

Ostatné možnosti hromadného API môžu byť nastavené ako možnosti na a DataFrame pri zápise sa odovzdávajú do API na hromadné kopírovanie.

Príklad písania a čítania

Nasledujúci kód ukazuje, ako zapisovať a čítať dáta pomocou metódy mssql("<schema>.<table>") s automatickou autentifikáciou Microsoft Entra ID.

Prepitné

Dáta sa vytvárajú priamo na demonštračné účely. V produkčnom scenári by ste zvyčajne čítali dáta z existujúceho zdroja alebo vytvárali zložitejší DataFrame.

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

Môžete tiež vybrať stĺpce, aplikovať filtre a používať ďalšie možnosti pri čítaní dát z SQL databázového enginu.

Príklady autentifikácie

Nasledujúce príklady ukazujú, ako používať autentifikačné metódy iné než Microsoft Entra ID, ako je service principal (access token) a SQL autentifikácia.

Poznámka

Ako už bolo spomenuté, autentifikácia Microsoft Entra ID sa spracováva automaticky pri prihlásení do pracovného priestoru Fabric, takže tieto metódy musíte použiť len vtedy, ak ich váš scenár vyžaduje.

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

Podporované režimy ukladania údajového rámca

Keď zapisujete dáta zo Spark do SQL databáz, môžete si vybrať z viacerých režimov ukladania. Režimy ukladania určujú, ako sa dáta zapisujú, keď cieľová tabuľka už existuje, a môžu ovplyvniť schému, dáta a indexovanie. Pochopenie týchto režimov vám pomôže vyhnúť sa neočakávaným stratám alebo zmenám dát.

Tento konektor podporuje možnosti definované tu: funkcie Spark Save

  • ErrorIfExists (predvolený režim ukladania): Ak cieľová tabuľka existuje, zápis sa preruší a vráti sa výnimka. Inak sa vytvorí nová tabuľka s dátami.

  • Ignorovať: Ak cieľová tabuľka existuje, zápis požiadavku ignoruje a nevráti chybu. Inak sa vytvorí nová tabuľka s dátami.

  • Prepísanie: Ak cieľová tabuľka existuje, tabuľka sa odstráni, znovu vytvorí a pridajú sa nové údaje.

    Poznámka

    Keď použijete overwrite, pôvodná schéma tabuliek (najmä dátové typy exkluzívne pre MSSQL) a indexy tabuliek sa stratia a nahradia schémou odvodenou z vášho Spark DataFrame. Aby sa predišlo strate schémy a indexov, použite .option("truncate", true) namiesto .overwrite

  • Pripojiť: Ak cieľová tabuľka existuje, pridávajú sa k nej nové údaje. Inak sa vytvorí nová tabuľka s dátami.

Riešenie problémov

Keď proces skončí, výstup vašej operácie čítania Spark sa objaví vo výstupnej oblasti bunky. Chyby prichádzajú com.microsoft.sqlserver.jdbc.SQLServerException priamo zo SQL Serveru. Podrobné informácie o chybách nájdete v aplikačných logoch Sparku.

Súvisiaci obsah

  • Last updated on