Connecteur Apache Spark : SQL Server et Azure SQLApache Spark connector: SQL Server & Azure SQL

Le Connecteur Apache Spark pour SQL Server et Azure SQL est un connecteur à hautes performances qui vous permet d’utiliser des données transactionnelles dans l’analytique du Big Data et de conserver les résultats pour des requêtes ad hoc ou des rapports.The Apache Spark connector for SQL Server and Azure SQL is a high-performance connector that enables you to use transactional data in big data analytics and persist results for ad-hoc queries or reporting. Le connecteur vous permet d’utiliser n’importe quelle base de données SQL, locale ou dans le cloud, comme source de données d’entrée ou récepteur de données de sortie pour les travaux Spark.The connector allows you to use any SQL database, on-premises or in the cloud, as an input data source or output data sink for Spark jobs.

Cette bibliothèque contient le code source du connecteur Apache Spark pour SQL Server et Azure SQL.This library contains the source code for the Apache Spark Connector for SQL Server and Azure SQL.

Apache Spark est un moteur d’analytique unifié pour le traitement des données à grande échelle.Apache Spark is a unified analytics engine for large-scale data processing.

Vous pouvez importer le connecteur dans votre projet par le biais des coordonnées Maven : com.microsoft.azure:spark-mssql-connector:1.0.0.You can import the connector into your project through the Maven coordinates: com.microsoft.azure:spark-mssql-connector:1.0.0. Vous pouvez également créer le connecteur à partir de la source ou télécharger le fichier jar à partir de la section Release dans GitHub.You can also build the connector from source or download the jar from the Release section in GitHub. Pour obtenir les informations les plus récentes sur le connecteur, consultez le Référentiel GitHub du connecteur SQL Spark.For the latest information about the connector, see SQL Spark connector GitHub repository.

Fonctionnalités prises en chargeSupported Features

  • Prise en charge de toutes les liaisons Spark (Scala, Python, R)Support for all Spark bindings (Scala, Python, R)
  • Authentification de base et prise en charge des fichiers keytab Active Directory (AD)Basic authentication and Active Directory (AD) Key Tab support
  • Prise en charge de l’écriture de dataframe réorganiséeReordered dataframe write support
  • Prise en charge de l’écriture sur une instance SQL Server unique et un pool de données dans les clusters Big Data SQL ServerSupport for write to SQL Server Single instance and Data Pool in SQL Server Big Data Clusters
  • Prise en charge fiable des connecteurs pour une instance SQL Server uniqueReliable connector support for Sql Server Single Instance
ComposantComponent Versions prises en chargeVersions Supported
Apache SparkApache Spark 2.4.5 (Spark 3.0 non pris en charge)2.4.5 (Spark 3.0 not supported)
ScalaScala 2.112.11
Pilote Microsoft JDBC pour SQL ServerMicrosoft JDBC Driver for SQL Server 8,28.2
Microsoft SQL ServerMicrosoft SQL Server SQL Server 2008 ou version ultérieureSQL Server 2008 or later
Bases de données SQL AzureAzure SQL Databases Pris en chargeSupported

Notes

L’utilisation d’Azure Synapse Analytics (Azure SQL DW) n’est pas testée avec ce connecteur.Azure Synapse Analytics (Azure SQL DW) use is not tested with this connector. Il pourrait fonctionner, mais il peut y avoir des conséquences inattendues.While it may work, there may be unintended consequences.

Options prises en chargeSupported Options

Le connecteur Apache Spark pour SQL Server et Azure SQL prend en charge les options définies ici : SQL DataSource JDBCThe Apache Spark Connector for SQL Server and Azure SQL supports the options defined here: SQL DataSource JDBC

Par ailleurs, les options suivantes sont prises en chargeIn addition following options are supported

OptionOption DefaultDefault DescriptionDescription
reliabilityLevel BEST_EFFORT BEST_EFFORT ou NO_DUPLICATES.BEST_EFFORT or NO_DUPLICATES. NO_DUPLICATES implémente une insertion fiable dans les scénarios de redémarrage d’exécuteurNO_DUPLICATES implements an reliable insert in executor restart scenarios
dataPoolDataSource none none implique que la valeur n’est pas définie et que le connecteur doit écrire sur l’instance unique de SQL Server.none implies the value is not set and the connector should write to SQL Server single instance. Définissez cette valeur sur le nom de la source de données pour écrire dans une table de pool de données dans Clusters Big DataSet this value to data source name to write a data pool table in Big Data Clusters
isolationLevel READ_COMMITTED Spécifier le niveau d’isolationSpecify the isolation level
tableLock false Implémente une insertion avec l’option TABLOCK pour améliorer les performances en écritureImplements an insert with TABLOCK option to improve write performance
schemaCheckEnabled true Désactive la trame de données stricte et la vérification du schéma de table sql lorsque la valeur est falseDisables strict data frame and sql table schema check when set to false

D’autres options de copie en bloc peuvent être définies en tant qu’options sur le dataframe et seront transmises aux API bulkcopy en écritureOther bulk copy options can be set as options on the dataframe and will be passed to bulkcopy APIs on write

Comparaison entre les performancesPerformance comparison

Le connecteur Apache Spark pour SQL Server et Azure SQL est 15x plus rapide que le connecteur JDBC générique pour l’écriture sur SQL Server.Apache Spark Connector for SQL Server and Azure SQL is up to 15x faster than generic JDBC connector for writing to SQL Server. Les caractéristiques de performances varient selon le type, le volume de données et les options utilisées, et peuvent présenter des variations d’exécution.Performance characteristics vary on type, volume of data, options used, and may show run to run variations. Les résultats de performances suivants sont le temps nécessaire pour remplacer une table SQL avec 143,9 M lignes dans un dataframe Spark.The following performance results are the time taken to overwrite a SQL table with 143.9M rows in a spark dataframe. Le dataframe Spark est construit en lisant la table HDFS store_sales générée à l’aide du Benchmark TPCDS Spark.The spark dataframe is constructed by reading store_sales HDFS table generated using spark TPCDS Benchmark. Le temps de lecture de store_sales sur dataframe est exclu.Time to read store_sales to dataframe is excluded. La moyenne des résultats est calculée sur trois exécutions.The results are averaged over three runs.

Type de connecteurConnector Type OptionsOptions DescriptionDescription Durée d’écritureTime to write
JDBCConnector Par défautDefault Connecteur JDBC générique avec les options par défautGeneric JDBC connector with default options 1385 secondes1385 seconds
sql-spark-connector BEST_EFFORT Effort optimal de sql-spark-connector avec les options par défautBest effort sql-spark-connector with default options 580 secondes580 seconds
sql-spark-connector NO_DUPLICATES sql-spark-connector fiableReliable sql-spark-connector 709 secondes709 seconds
sql-spark-connector BEST_EFFORT + tabLock=trueBEST_EFFORT + tabLock=true Effort optimal de sql-spark-connector avec le verrouillage de table activéBest effort sql-spark-connector with table lock enabled 72 secondes72 seconds
sql-spark-connector NO_DUPLICATES + tabLock=trueNO_DUPLICATES + tabLock=true sql-spark-connector fiable avec verrouillage de table activéReliable sql-spark-connector with table lock enabled 198 secondes198 seconds

ConfigConfig

  • Configuration Spark : num_executors = 20, executor_memory = '1664 m', executor_cores = 2Spark config: num_executors = 20, executor_memory = '1664 m', executor_cores = 2
  • Configuration de génération de données : scale_factor=50, partitioned_tables=trueData Gen config: scale_factor=50, partitioned_tables=true
  • Fichier de données store_sales avec le nb de lignes 143 997 590Data file store_sales with nr of rows 143,997,590

EnvironnementEnvironment

Problèmes courantsCommonly Faced Issues

java.lang.NoClassDefFoundError: com/microsoft/aad/adal4j/AuthenticationException

Ce problème provient de l’utilisation d’une version antérieure du pilote MSSQL (qui est maintenant inclus dans ce connecteur) dans votre environnement Hadoop.This issue arises from using an older version of the mssql driver (which is now included in this connector) in your hadoop environment. Si vous utilisez le connecteur Azure SQL précédent et que vous avez installé manuellement des pilotes sur ce cluster pour la compatibilité Azure Active Directory, vous devrez supprimer ces pilotes.If you are coming from using the previous Azure SQL Connector and have manually installed drivers onto that cluster for Azure Active Directory compatibility, you will need to remove those drivers.

Étapes pour résoudre le problème :Steps to fix the issue:

  1. Si vous utilisez un environnement Hadoop générique, vérifiez et supprimez le fichier jar mssql : rm $HADOOP_HOME/share/hadoop/yarn/lib/mssql-jdbc-6.2.1.jre7.jar.If you are using a generic Hadoop environment, check and remove the mssql jar: rm $HADOOP_HOME/share/hadoop/yarn/lib/mssql-jdbc-6.2.1.jre7.jar. Si vous utilisez Databricks, ajoutez un script global ou un script d’initialisation de cluster pour supprimer les anciennes versions du pilote mssql du dossier /databricks/jars, ou ajoutez cette ligne à un script existant : rm /databricks/jars/*mssql*If you are using Databricks, add a global or cluster init script to remove old versions of the mssql driver from the /databricks/jars folder, or add this line to an existing script: rm /databricks/jars/*mssql*

  2. Ajoutez les packages adal4j et mssql.Add the adal4j and mssql packages. Par exemple, vous pouvez utiliser Maven, mais toute méthode devrait fonctionner.For example, you can use Maven but any way should work.

    Attention

    N’installez pas le connecteur SQL Spark de cette manière.Do not install the SQL spark connector this way.

  3. Ajoutez la classe du pilote à votre configuration de connexion.Add the driver class to your connection configuration. Exemple :For example:

    connectionProperties = {
      `Driver`: `com.microsoft.sqlserver.jdbc.SQLServerDriver`
    }`
    

Pour plus d’informations et d’explications, consultez la résolution pour https://github.com/microsoft/sql-spark-connector/issues/26.For more information and explanation, see the resolution to https://github.com/microsoft/sql-spark-connector/issues/26.

DécouvrirGet Started

Le connecteur Apache Spark pour SQL Server et Azure SQL est basé sur l’API Spark DataSourceV1 et l’API de bloc SQL Server et utilise la même interface que le connecteur JDBC Spark-SQL intégré.The Apache Spark Connector for SQL Server and Azure SQL is based on the Spark DataSourceV1 API and SQL Server Bulk API and uses the same interface as the built-in JDBC Spark-SQL connector. Cette intégration vous permet d’intégrer facilement le connecteur et de migrer vos travaux Spark existants en mettant simplement à jour le paramètre de format avec com.microsoft.sqlserver.jdbc.spark.This integration allows you to easily integrate the connector and migrate your existing Spark jobs by simply updating the format parameter with com.microsoft.sqlserver.jdbc.spark.

Pour inclure le connecteur dans vos projets, téléchargez ce référentiel et générez le fichier jar à l’aide de SBT.To include the connector in your projects, download this repository and build the jar using SBT.

Écrire dans une nouvelle table SQLWrite to a new SQL Table

Avertissement

Le mode overwrite supprime d’abord la table si elle existe déjà dans la base de données par défaut.The overwrite mode first drops the table if it already exists in the database by default. Utilisez cette option avec soin pour éviter les pertes de données inattendues.Please use this option with due care to avoid unexpected data loss.

Lorsque vous utilisez le mode overwrite et que vous n’utilisez pas l’option truncate, les index sont perdus lors de la recréation de la table.When using mode overwrite if you do not use the option truncate on recreation of the table, indexes will be lost. , une table ColumnStore serait maintenant un segment de mémoire., a columnstore table would now be a heap. Si vous souhaitez conserver l’indexation existante, spécifiez également l’option truncate avec la valeur true.If you want to maintain existing indexing please also specify option truncate with value true. Par exemple : .option("truncate","true").For example, .option("truncate","true").

server_name = "jdbc:sqlserver://{SERVER_ADDR}"
database_name = "database_name"
url = server_name + ";" + "databaseName=" + database_name + ";"

table_name = "table_name"
username = "username"
password = "password123!#" # Please specify password here

try:
  df.write \
    .format("com.microsoft.sqlserver.jdbc.spark") \
    .mode("overwrite") \
    .option("url", url) \
    .option("dbtable", table_name) \
    .option("user", username) \
    .option("password", password) \
    .save()
except ValueError as error :
    print("Connector write failed", error)

Ajouter à une table SQLAppend to SQL Table

try:
  df.write \
    .format("com.microsoft.sqlserver.jdbc.spark") \
    .mode("append") \
    .option("url", url) \
    .option("dbtable", table_name) \
    .option("user", username) \
    .option("password", password) \
    .save()
except ValueError as error :
    print("Connector write failed", error)

Spécifier le niveau d’isolationSpecify the isolation level

Par défaut, ce connecteur utilise le niveau d’isolation READ_COMMITTED lors de l’insertion en bloc dans la base de données.This connector by default uses READ_COMMITTED isolation level when performing the bulk insert into the database. Si vous souhaitez remplacer le niveau d’isolation, utilisez l’option mssqlIsolationLevel comme indiqué ci-dessous.If you wish to override the isolation level, use the mssqlIsolationLevel option as shown below.

    .option("mssqlIsolationLevel", "READ_UNCOMMITTED") \

Lire à partir d’une table SQLRead from SQL Table

jdbcDF = spark.read \
        .format("com.microsoft.sqlserver.jdbc.spark") \
        .option("url", url) \
        .option("dbtable", table_name) \
        .option("user", username) \
        .option("password", password).load()

Authentification Azure Active DirectoryAzure Active Directory Authentication

Exemple Python avec un principal de servicePython Example with Service Principal

context = adal.AuthenticationContext(authority)
token = context.acquire_token_with_client_credentials(resource_app_id_url, service_principal_id, service_principal_secret)
access_token = token["accessToken"]

jdbc_db = spark.read \
        .format("com.microsoft.sqlserver.jdbc.spark") \
        .option("url", url) \
        .option("dbtable", table_name) \
        .option("accessToken", access_token) \
        .option("encrypt", "true") \
        .option("hostNameInCertificate", "*.database.windows.net") \
        .load()

Exemple Python avec mot de passe Active DirectoryPython Example with Active Directory Password

jdbc_df = spark.read \
        .format("com.microsoft.sqlserver.jdbc.spark") \
        .option("url", url) \
        .option("dbtable", table_name) \
        .option("authentication", "ActiveDirectoryPassword") \
        .option("user", user_name) \
        .option("password", password) \
        .option("encrypt", "true") \
        .option("hostNameInCertificate", "*.database.windows.net") \
        .load()

Une dépendance requise doit être installée pour pouvoir s’authentifier à l’aide d’Active Directory.A required dependency must be installed in order to authenticate using Active Directory.

Pour Scala, l’artefact _com.microsoft.aad.adal4j_ doit être installé.For Scala, the _com.microsoft.aad.adal4j_ artifact will need to be installed.

Pour Python, la bibliothèque _adal_ doit être installée.For Python, the _adal_ library will need to be installed. Cela est possible via pip.This is available via pip.

Pour obtenir des exemples, consultez les Exemples de notebooks.Check the sample notebooks for examples.

SupportSupport

Le connecteur Apache Spark pour Azure SQL et SQL Server est un projet open source.The Apache Spark Connector for Azure SQL and SQL Server is an open-source project. Ce connecteur n’est fourni avec aucun support technique de Microsoft.This connector does not come with any Microsoft support. Pour les problèmes liés au connecteur, créez un problème dans le référentiel de ce projet.For issues with or questions about the connector, create an Issue in this project repository. La communauté du connecteur est active et surveille les envois.The connector community is active and monitoring submissions.

Étapes suivantesNext steps

Visitez le référentiel GitHub de SQL Spark.Visit the SQL Spark connector GitHub repository.

Pour plus d’informations sur les niveaux d’isolement, consultez SET TRANSACTION ISOLATION LEVEL (Transact-SQL).For information about isolation levels, see SET TRANSACTION ISOLATION LEVEL (Transact-SQL).