Partager via

Connecteur Spark pour les bases de données SQL (préversion)

Important

Cette fonctionnalité est en version préliminaire.

Le connecteur Spark pour les bases de données SQL est une bibliothèque hautes performances qui vous permet de lire et d’écrire dans SQL Server, des bases de données Azure SQL et des bases de données Sql Fabric. Le connecteur offre les fonctionnalités suivantes :

  • Utilisez Spark pour exécuter des opérations d’écriture et de lecture volumineuses sur Azure SQL Database, Azure SQL Managed Instance, SQL Server sur une machine virtuelle Azure et des bases de données SQL Fabric.
  • Lorsque vous utilisez une table ou une vue, le connecteur prend en charge les modèles de sécurité définis au niveau du moteur SQL. Ces modèles incluent la sécurité au niveau objet (OLS), la sécurité au niveau ligne (RLS) et la sécurité au niveau colonne (CLS).

Le connecteur est préinstallé dans le runtime Fabric. Vous n’avez donc pas besoin de l’installer séparément.

Authentication

L’authentification Microsoft Entra est intégrée à Microsoft Fabric.

  • Lorsque vous vous connectez à l’espace de travail Fabric, vos informations d’identification sont automatiquement transmises au moteur SQL pour l’authentification et l’autorisation.
  • Nécessite que l’ID Microsoft Entra soit activé et configuré sur votre moteur de base de données SQL.
  • Aucune configuration supplémentaire n’est nécessaire dans votre code Spark si l’ID Microsoft Entra est configuré. Les informations d’identification sont automatiquement mappées.

Vous pouvez également utiliser la méthode d’authentification SQL (en spécifiant un nom d’utilisateur et un mot de passe SQL) ou un principal de service (en fournissant un jeton d’accès Azure pour l’authentification basée sur l’application).

Permissions

Pour utiliser le connecteur Spark, votre identité, qu’il s’agisse d’un utilisateur ou d’une application, doit disposer des autorisations de base de données nécessaires pour le moteur SQL cible. Ces autorisations sont requises pour lire ou écrire dans des tables et des vues.

Pour Azure SQL Database, Azure SQL Managed Instance et SQL Server sur une machine virtuelle Azure :

  • L’identité exécutant l’opération a généralement besoin db_datawriter et db_datareader autorisations, et éventuellement db_owner pour un contrôle total.

Pour les bases de données SQL Fabric :

  • L'identité a généralement besoin des autorisations db_datawriter et db_datareader, et éventuellement de db_owner.
  • L’identité a également besoin d’au moins une autorisation de lecture sur la base de données SQL Fabric au niveau de l’élément.

Note

Si vous utilisez un principal de service, il peut s’exécuter en tant qu’application (aucun contexte utilisateur) ou en tant qu’utilisateur si l’emprunt d’identité de l’utilisateur est activé. Le principal de service doit disposer des autorisations de base de données requises pour les opérations que vous souhaitez effectuer.

Exemples d’utilisation et de code

Dans cette section, nous fournissons des exemples de code pour montrer comment utiliser efficacement le connecteur Spark pour les bases de données SQL. Ces exemples couvrent différents scénarios, notamment la lecture et l’écriture dans des tables SQL, et la configuration des options de connecteur.

Options prises en charge

L’option minimale requise est url comme "jdbc:sqlserver://<server>:<port>;database=<database>;" ou définie spark.mssql.connector.default.url.

  • Lorsque la valeur url est fournie :

    • url Utilisez toujours comme première préférence.
    • S'il spark.mssql.connector.default.url n'est pas défini, le connecteur le définira et le réutilisera pour de futurs usages.

  • Lorsque le url fichier n’est pas fourni :

    • S’il spark.mssql.connector.default.url est défini, le connecteur utilise la valeur de la configuration Spark.
    • Si spark.mssql.connector.default.url n’est pas défini, une erreur est levée, car les détails requis ne sont pas disponibles.

Ce connecteur prend en charge les options définies ici : Options JDBC SQL DataSource

Le connecteur prend également en charge les options suivantes :

Choix Valeur par défaut Descriptif
reliabilityLevel « BEST_EFFORT » Contrôle la fiabilité des opérations d’insertion. Valeurs possibles : BEST_EFFORT (par défaut, le plus rapide, peut entraîner des lignes en double si un exécuteur redémarre), NO_DUPLICATES (plus lent, garantit qu’aucune ligne en double n’est insérée même si un exécuteur redémarre). Choisissez en fonction de votre tolérance pour les doublons et les besoins en matière de performances.
isolationLevel « READ_COMMITTED » Définit le niveau d’isolation des transactions pour les opérations SQL. Valeurs possibles : READ_COMMITTED (par défaut, empêche la lecture des données non validées), READ_UNCOMMITTED, REPEATABLE_READ, SNAPSHOT, SERIALIZABLE. Des niveaux d’isolation plus élevés peuvent réduire la concurrence, mais améliorer la cohérence des données.
tableLock « faux » Contrôle si l’indicateur de verrou au niveau de la table SQL Server TABLOCK est utilisé pendant les opérations d’insertion. Valeurs possibles : true (active TABLOCK, qui peut améliorer les performances d’écriture en bloc), false (par défaut, n’utilise pas TABLOCK). Définir sur true peut augmenter le débit pour les insertions volumineuses, mais peut réduire la concurrence lors d’autres opérations sur la table.
schemaCheckEnabled « true » Contrôle si la validation stricte du schéma est appliquée entre votre DataFrame spark et la table SQL. Valeurs possibles : true (par défaut, applique une correspondance stricte de schéma), false (permet une plus grande flexibilité et peut ignorer certaines vérifications de schéma). Définir le paramètre false peut aider à gérer les mauvaises correspondances de schéma mais peut entraîner des résultats inattendus si les structures diffèrent considérablement.

D'autres options Bulk API peuvent être définies en tant qu'options sur le DataFrame et transmises aux API de copie en bloc en écriture.

Exemple de rédaction et de lecture

Le code suivant montre comment écrire et lire des données à l’aide de la méthode mssql("<schema>.<table>") avec l’authentification automatique Microsoft Entra ID.

Conseil / Astuce

Les données sont créées en ligne à des fins de démonstration. Dans un scénario de production, vous devez généralement lire des données à partir d’une source existante ou créer un élément plus complexe 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

Vous pouvez également sélectionner des colonnes, appliquer des filtres et utiliser d’autres options lorsque vous lisez des données à partir du moteur de base de données SQL.

Exemples d’authentification

Les exemples suivants montrent comment utiliser des méthodes d’authentification autres que l’ID Microsoft Entra, comme le principal de service (jeton d’accès) et l’authentification SQL.

Note

Comme mentionné précédemment, l’authentification microsoft Entra ID est gérée automatiquement lorsque vous vous connectez à l’espace de travail Fabric. Vous devez donc utiliser ces méthodes uniquement si votre scénario les requiert.

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

Modes d’enregistrement de DataFrame pris en charge

Lorsque vous écrivez des données de Spark dans des bases de données SQL, vous pouvez choisir parmi plusieurs modes d’enregistrement. Les modes d’enregistrement contrôlent la façon dont les données sont écrites lorsque la table de destination existe déjà et peuvent affecter le schéma, les données et l’indexation. La compréhension de ces modes vous permet d’éviter une perte ou des modifications inattendues des données.

Ce connecteur prend en charge les options définies ici : Fonctions d’enregistrement Spark

  • ErrorIfExists (mode d’enregistrement par défaut) : si la table de destination existe, l’écriture est abandonnée et une exception est retournée. Sinon, une nouvelle table est créée avec des données.

  • Ignorer : si la table de destination existe, l’écriture ignore la requête et ne retourne pas d’erreur. Sinon, une nouvelle table est créée avec des données.

  • Remplacer : si la table de destination existe, la table est supprimée, recréée et les nouvelles données sont ajoutées.

    Note

    Lorsque vous utilisez overwrite, le schéma de table d’origine (en particulier les types de données exclusifs MSSQL) et les index de table sont perdus et remplacés par le schéma déduit de votre DataFrame Spark. Pour éviter de perdre le schéma et les index, utilisez .option("truncate", true) plutôt overwriteque .

  • Ajout : si la table de destination existe, de nouvelles données y sont ajoutées. Sinon, une nouvelle table est créée avec des données.

Troubleshoot

Lorsque le processus est terminé, le résultat de votre opération de lecture Spark apparaît dans la zone de sortie de la cellule. com.microsoft.sqlserver.jdbc.SQLServerException Les erreurs proviennent directement de SQL Server. Vous trouverez des informations détaillées sur les erreurs dans les journaux d’activité de l’application Spark.

Contenu connexe

  • Last updated on