Aller au contenu principal
Dernière mise à jour le

Connexion de Databricks et Azure Synapse avec PolyBase (hérité)

important

Cette documentation a été retirée et pourrait ne pas être mise à jour. Les produits, services ou technologies mentionnés dans ce contenu ne sont plus pris en charge. Voir query data in Azure Synapse Analytics.

Databricks recommande d'utiliser la fonctionnalité COPY default avec Azure Data Lake Storage pour les connexions à Azure Synapse. Cet article inclut une documentation héritée sur PolyBase et le stockage Blob.

Azure Synapse Analytics (anciennement SQL Data Warehouse) est un data warehouse d’entreprise basé sur le cloud qui exploite le traitement massivement parallèle (MPP) pour exécuter rapidement des requêtes complexes sur des pétaoctets de données. Utilisez Azure comme un composant clé d'une solution Big Data. Importez des Big Data dans Azure avec de simples requêtes T-SQL PolyBase, ou l'instruction COPY, puis utilisez la puissance du MPP pour exécuter de l'analytique haute performance. À mesure que vous intégrez et analysez, le data warehouse deviendra la source unique de vérité sur laquelle votre entreprise pourra compter pour son insight.

Vous pouvez accéder à Azure Synapse depuis Databricks à l'aide du connecteur Azure Synapse, une implémentation de source de données pour Apache Spark qui utilise le stockage Azure Blob, et PolyBase ou l'instruction COPY dans Azure Synapse pour transférer efficacement de grands volumes de données entre un cluster Databricks et une instance Azure Synapse.

Le cluster Databricks et l'instance Azure Synapse accèdent tous deux à un conteneur de stockage Blob commun pour échanger des données entre ces deux systèmes. Dans Databricks, les Jobs Apache Spark sont déclenchés par le connecteur Azure Synapse pour lire les données du conteneur de stockage Blob et y écrire des données. Du côté d'Azure Synapse, les opérations de chargement et de déchargement des données effectuées par PolyBase sont déclenchées par le connecteur Azure Synapse via JDBC. Dans Databricks Runtime 7.0 et versions ultérieures, COPY est utilisé par default pour charger des données dans Azure Synapse par l'intermédiaire du connecteur Azure Synapse via JDBC.

remarque

COPY est disponible uniquement sur les instances Gen2 d’Azure Synapse, qui offrent de meilleures performances. Si votre base de données utilise toujours des instances Gen1, nous vous recommandons de migrer la base de données vers Gen2.

Le connecteur Azure Synapse est plus adapté à l'ETL qu'aux requêtes interactives, car chaque exécution de requête peut extraire de grandes quantités de données vers le stockage Blob. Si vous prévoyez d'exécuter plusieurs queries sur la même table Azure Synapse, nous vous recommandons d'enregistrer les données extraites dans un format tel que Parquet.

Exigences​

Une clé principale de base de données Azure Synapse.

Authentification​

Le connecteur Azure Synapse utilise trois types de connexions réseau :

  • Driver Spark vers Azure Synapse
  • Driver et exécuteurs Spark vers le compte de stockage Azure
  • Compte de stockage Azure Synapse vers Azure
                                 ┌─────────┐
      ┌─────────────────────────>│ STORAGE │<────────────────────────┐
      │   Storage acc key /      │ ACCOUNT │  Storage acc key /      │
      │   Managed Service ID /   └─────────┘  OAuth 2.0 /            │
      │                               │                              │
      │                               │                              │
      │                               │ Storage acc key /            │
      │                               │ OAuth 2.0 /                  │
      │                               │                              │
      v                               v                       ┌──────v────┐
┌──────────┐                      ┌──────────┐                │┌──────────┴┐
│ Synapse  │                      │  Spark   │                ││ Spark     │
│ Analytics│<────────────────────>│  Driver  │<───────────────>│ Executors │
└──────────┘  JDBC with           └──────────┘    Configured   └───────────┘
              username & password /                in Spark

Les sections suivantes décrivent les options de configuration d'authentification de chaque connexion.

Driver Spark vers Azure Synapse​

Le Driver Spark peut se connecter à Azure Synapse en utilisant JDBC avec un nom d'utilisateur et un mot de passe ou OAuth 2,0 avec un Service Principal pour l'authentification.

Nom d'utilisateur et mot de passe​

Nous vous recommandons d'utiliser les chaînes de connexion fournies par le portail Azure pour les deux types d'authentification, qui activent le chiffrement Secure Sockets Layer (SSL) pour toutes les données envoyées entre le Driver Spark et l'instance Azure Synapse via la connexion JDBC. Pour vérifier que le chiffrement SSL est activé, vous pouvez rechercher encrypt=true dans la chaîne de connexion.

Pour permettre au Driver Spark d'atteindre Azure Synapse, nous vous recommandons de définir **Autoriser les services et ressources Azure à accéder à ce workspace** sur **ON** dans le volet Réseau sous Sécurité du workspace Azure Synapse via le portail Azure. Ce paramètre permet les communications de toutes les adresses IP Azure et de tous les sous-réseaux Azure, ce qui permet aux Drivers Spark d'atteindre l'instance Azure Synapse.

OAuth 2.0 avec un Service Principal​

Vous pouvez vous authentifier auprès d'Azure Synapse Analytics à l'aide d'un service principal ayant accès au compte de stockage sous-jacent. Pour plus d'informations sur l'utilisation des identifiants de Service Principal pour accéder à un compte de stockage Azure, consultez Se connecter à Azure Data Lake Storage et Blob Storage. Vous devez définir l'option enableServicePrincipalAuth sur true dans la configuration de connexion Parameters pour permettre au connecteur de s'authentifier avec un Service Principal.

Vous pouvez éventuellement utiliser un autre service principal pour la connexion Azure Synapse Analytics. Un exemple qui configure les informations d'identification de service principal pour le compte de stockage et les informations d'identification de service principal facultatives pour Synapse :

ini
; Defining the Service Principal credentials for the Azure storage account
fs.azure.account.auth.type OAuth
fs.azure.account.oauth.provider.type org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider
fs.azure.account.oauth2.client.id <application-id>
fs.azure.account.oauth2.client.secret <service-credential>
fs.azure.account.oauth2.client.endpoint https://login.microsoftonline.com/<directory-id>/oauth2/token

; Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.databricks.sqldw.jdbc.service.principal.client.id <application-id>
spark.databricks.sqldw.jdbc.service.principal.client.secret <service-credential>

Driver et exécuteurs Spark vers un compte de stockage Azure​

Le conteneur de stockage Azure sert d'intermédiaire pour stocker des données en vrac lors de la lecture ou de l'écriture vers Azure Synapse. Spark se connecte à ADLS ou Stockage Blob à l'aide du Driver abfss.

Les options d'authentification suivantes sont disponibles :

Les exemples ci-dessous illustrent ces deux méthodes utilisant l'approche de la clé d'accès au compte de stockage. Il en va de même pour la configuration OAuth 2.0.

Configuration de session de notebook (préférée)​

En utilisant cette approche, la clé d’accès au compte est définie dans la configuration de session associée au notebook qui exécute la commande. Cette configuration n'affecte pas les autres Notebooks associés au même cluster. spark est l'objet SparkSession fourni dans le Notebook.

Python
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

Configuration globale de Hadoop​

Cette approche met à jour la configuration Hadoop globale associée à l'objet SparkContext partagé par tous les notebooks.

Scala
sc.hadoopConfiguration.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

Azure Synapse vers un compte de stockage Azure​

Azure Synapse se connecte également à un compte de stockage lors du chargement et du déchargement de données temporaires.

Si vous avez configuré une clé de compte et un secret pour le compte de stockage, vous pouvez définir forwardSparkAzureStorageCredentials sur true, auquel cas le connecteur Azure Synapse découvre automatiquement la clé d'accès au compte définie dans la configuration de session du Notebook ou la configuration globale Hadoop et transmet la cl’accès au compte de stockage à l'instance Azure Synapse connectée en créant un identifiant délimité à la base de données Azure temporaire.

Alternativement, si vous utilisez ADLS avec l'authentification OAuth 2.0 ou si votre instance Azure Synapse est configurée pour avoir une identité de service gérée (généralement en conjonction avec une configuration VNet + Service Endpoint), vous devez définir useAzureMSI sur true. Dans ce cas, le connecteur spécifiera IDENTITY = 'Managed Service Identity' pour les informations d'identification étendues à la base de données et aucun SECRET.

Prise en charge du streaming​

Le connecteur Azure Synapse offre une prise en charge efficace et évolutive de l'écriture en Structured Streaming pour Azure Synapse qui fournit une expérience utilisateur cohérente avec les écritures en batch et utilise PolyBase ou COPY pour les transferts de données volumineux entre un cluster Databricks et une instance Azure Synapse. Semblable aux écritures en batch, le streaming est principalement conçu pour l'ETL, offrant ainsi une latence plus élevée qui peut ne pas être adaptée au traitement des données en temps réel dans certains cas.

Sémantique de tolérance aux pannes​

Par default, Azure Synapse streaming offre une garantie de bout en bout d'exécution exactement une seule fois pour l'écriture de données dans une table Azure Synapse en assurant un suivi fiable de l'avancement de la query, grâce à une combinaison d'emplacement de point de contrôle dans DBFS, de table de point de contrôle dans Azure Synapse, et d'un mécanisme de verrouillage, afin de s'assurer que le streaming peut gérer tout type de défaillances, de tentatives et de redémarrages de query. En option, vous pouvez sélectionner des sémantiques « au moins une fois » moins restrictives pour Azure Synapse Streaming en définissant l'option spark.databricks.sqldw.streaming.exactlyOnce.enabled à false, auquel cas une duplication des données pourrait se produire en cas de défaillances de connexion intermittentes à Azure Synapse ou d'interruption inattendue de la query.

Utilisation (Batch)​

Vous pouvez utiliser ce connecteur via l'API de source de données dans les Notebooks Scala, Python, SQL et R.

Scala

// Otherwise, set up the Blob storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

// Get some data from an Azure Synapse table.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .load()

// Load data from an Azure Synapse query.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("query", "select x, count(*) as cnt from table group by x")
  .load()

// Apply some transformations to the data, then use the
// Data Source API to write the data back to another table in Azure Synapse.
df.write
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .save()

Utilisation (streaming)​

Vous pouvez écrire des données à l’aide de Structured Streaming dans des notebooks Scala et Python.

Scala
// Set up the Blob storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

// Prepare streaming source; this could be Kafka or a simple rate stream.
val df: DataFrame = spark.readStream
  .format("rate")
  .option("rowsPerSecond", "100000")
  .option("numPartitions", "16")
  .load()

// Apply some transformations to the data then use
// Structured Streaming API to continuously write the data to a table in Azure Synapse.
df.writeStream
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .option("checkpointLocation", "/tmp_checkpoint_location")
  .start()

Configuration​

Cette section décrit comment configurer la sémantique d'écriture pour le connecteur, les autorisations requises et les divers paramètres de configuration.

Dans cette section :

Modes de sauvegarde pris en charge pour les écritures par batch​

Le connecteur Azure Synapse prend en charge les modes de sauvegarde ErrorIfExists, Ignore, Append et Overwrite, le mode default étant ErrorIfExists. Pour plus d'informations sur les modes de sauvegarde pris en charge dans Apache Spark, consultez la documentation Spark SQL sur les modes de sauvegarde.

Modes de sortie pris en charge pour les écritures de streaming​

Le connecteur Azure Synapse prend en charge les modes de sortie Append et Complete pour les ajouts et les agrégations d'enregistrements. Pour plus de détails sur les modes de sortie et la matrice de compatibilité, consultez le guide Structured Streaming.

Écrire la sémantique​

remarque

COPY est disponible dans Databricks Runtime 7,0 et versions ultérieures.

En plus de PolyBase, le connecteur Azure Synapse prend en charge l'instruction COPY. L'instruction COPY offre un moyen plus pratique de charger des données dans Azure Synapse sans avoir besoin de créer une table externe, requiert moins d'autorisations pour charger les données et améliore les performances de l'ingestion des données dans Azure Synapse.

By default, le connecteur découvre automatiquement la meilleure sémantique d'écriture (COPY lors du ciblage d'une instance Azure Synapse Gen2, PolyBase sinon). Vous pouvez également spécifier la sémantique d'écriture avec la configuration suivante :

Scala
// Configure the write semantics for Azure Synapse connector in the notebook session conf.
spark.conf.set("spark.databricks.sqldw.writeSemantics", "<write-semantics>")

où <write-semantics> est soit polybase pour utiliser PolyBase, soit copy pour utiliser l'instruction COPY.

Autorisations Azure Synapse requises pour PolyBase​

Lorsque vous utilisez PolyBase, le connecteur Azure Synapse exige que l’utilisateur de la connexion JDBC ait l’autorisation d’exécuter les commandes suivantes dans l’instance Azure Synapse connectée :

Comme prérequis pour la première commande, le connecteur s'attend à ce qu'une clé principale de base de données existe déjà pour l'instance Azure Synapse spécifiée. Sinon, vous pouvez créer une clé à l'aide de la commande CREATE MASTER KEY.

De plus, pour lire l'ensemble de tables Azure Synapse via dbTable ou les tables mentionnées dans query, l'utilisateur JDBC doit avoir l'autorisation d'accéder aux tables Azure Synapse nécessaires. Pour écrire des données dans une table Azure Synapse définie via dbTable, l'utilisateur JDBC doit avoir la permission d'écrire dans cette table Azure Synapse.

Le tableau suivant résume les autorisations requises pour toutes les opérations avec PolyBase :

Opérations

Autorisations

Autorisations lors de l'utilisation d'une source de données externe

Écriture par lot

CONTRÔLE

Voir l'écriture par batch

Écriture en streaming

CONTRÔLE

Consultez Écriture en streaming

Lire l'article

CONTRÔLE

Voir Lire l'article

Opérations

Autorisations

Autorisations lors de l'utilisation d'une source de données externe

Écriture par lot

CONTRÔLE

Voir l'écriture par batch

Écriture en streaming

CONTRÔLE

Consultez Écriture en streaming

Lire l'article

CONTRÔLE

Voir Lire l'article

Autorisations Azure Synapse requises pour PolyBase avec l'option de source de données externe​

Vous pouvez utiliser PolyBase avec une source de données externe pré-provisionnée. Consultez le parameter externalDataSource dans Parameters pour plus d'informations.

Pour utiliser PolyBase avec une source de données externe pré-provisionnée, le connecteur Azure Synapse requiert que l'utilisateur de la connexion JDBC dispose de l'autorisation d'exécuter les commandes suivantes dans l'instance Azure Synapse connectée :

Pour créer une source de données externe, vous devez d'abord créer des informations d'identification étendues à la base de données. Les links suivants décrivent comment créer un identifiant délimité pour les Service Principal et une source de données externe pour un emplacement ABFS :

remarque

L'emplacement de la source de données externe doit pointer vers un conteneur. Le connecteur ne fonctionnera pas si l'emplacement est un répertoire dans un conteneur.

Le tableau suivant résume les autorisations pour les opérations d'écriture PolyBase avec l'option de source de données externe :

Opérations

Permissions (insérer dans une table existante)

Autorisations (insérer dans une nouvelle table)

Écriture par lot

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Écriture en streaming

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Opérations

Permissions (insérer dans une table existante)

Autorisations (insérer dans une nouvelle table)

Écriture par lot

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Écriture en streaming

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Le tableau suivant résume les autorisations pour les opérations de lecture PolyBase avec l'option source de données externe :

Opérations

Autorisations

Lire l'article

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Opérations

Autorisations

Lire l'article

Créer une table

ALTER ANY SCHEMA

ALTER ANY EXTERNAL SOURCE DE DONNÉES

ALTER ANY EXTERNAL FILE FORMAT

Vous pouvez utiliser ce connecteur pour lire via l’API de la source de données dans les notebooks Scala, Python, SQL et R.

Scala
// Get some data from an Azure Synapse table.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("externalDataSource", "<your-pre-provisioned-data-source>")
  .option("dbTable", "<your-table-name>")
  .load()

Autorisations Azure Synapse requises pour l'instruction COPY​

remarque

Disponible dans Databricks Runtime 7.0 et versions ultérieures.

Lorsque vous utilisez l'instruction COPY, le connecteur Azure Synapse requiert que l'utilisateur de la connexion JDBC dispose de l'autorisation d'exécuter les commandes suivantes dans l'instance Azure Synapse connectée :

Si la table de destination n'existe pas dans Azure Synapse, une autorisation d'exécution de la commande suivante est requise en plus de la commande ci-dessus :

Le tableau suivant résume les autorisations pour les écritures en batch et en streaming avec COPY:

Opérations

Permissions (insérer dans une table existante)

Autorisations (insérer dans une nouvelle table)

Écriture par lot

Administrer les opérations en bloc de la base de données

INSÉRER

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ON SCHEMA :: dbo

Écriture en streaming

Administrer les opérations en bloc de la base de données

INSÉRER

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ON SCHEMA :: dbo

Opérations

Permissions (insérer dans une table existante)

Autorisations (insérer dans une nouvelle table)

Écriture par lot

Administrer les opérations en bloc de la base de données

INSÉRER

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ON SCHEMA :: dbo

Écriture en streaming

Administrer les opérations en bloc de la base de données

INSÉRER

Administrer les opérations en bloc de la base de données

INSÉRER

Créer une table

ALTER ON SCHEMA :: dbo

parameter​

La carte des paramètres ou le OPTIONS fourni dans Spark SQL prend en charge les paramètres suivants :

parameter

Obligatoire

Par défaut

Notes

dbTable

Oui, sauf si query est spécifié

No default

La table à créer ou à lire dans Azure Synapse. Ce paramètre est requis lors de la sauvegarde des données vers Azure Synapse.

Vous pouvez également utiliser {SCHEMA NAME}.{TABLE NAME} pour accéder à une table dans un schéma donné. Si le nom du schéma n'est pas fourni, le schéma par default associé à l'utilisateur JDBC est utilisé.

La variante dbtable précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

query

Oui, sauf si dbTable est spécifié

No default

La query à lire dans Azure Synapse.

Pour les tables référencées dans la requête, vous pouvez également utiliser {SCHEMA NAME}.{TABLE NAME} pour accéder à une table dans un schéma donné. Si le nom du schéma n'est pas fourni, le schéma par default associé à l'utilisateur JDBC est utilisé.

user

Non

No default

Le nom d'utilisateur Azure Synapse. Doit être utilisé conjointement avec l'option password. Peut être utilisé uniquement si l'utilisateur et le mot de passe ne sont pas transmis dans l'URL. Le fait de passer les deux entraînera une erreur.

password

Non

No default

Le mot de passe Azure Synapse. Doit être utilisé conjointement avec l'option user. Peut être utilisé uniquement si l'utilisateur et le mot de passe ne sont pas transmis dans l'URL. Le fait de passer les deux entraînera une erreur.

url

Oui

No default

Une URL JDBC avec sqlserver défini comme sous-protocole. Il est recommandé d'utiliser la chaîne de connexion fournie par le portail Azure. Le paramètre encrypt=true est fortement recommandé, car il active le chiffrement SSL de la connexion JDBC. Si user et password sont définis séparément, vous n'avez pas besoin de les inclure dans l'URL.

jdbcDriver

Non

Déterminé par le sous-protocole de l'URL JDBC.

Le nom de classe du Driver JDBC à utiliser. Cette classe doit se trouver dans le classpath. Dans la plupart des cas, il ne devrait pas être nécessaire de spécifier cette option, car le nom de classe du Driver approprié devrait être automatiquement déterminé par le sous-protocole de l'URL JDBC.

La variante jdbc_driver précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

tempDir

Oui

No default

Un URI abfss. Nous vous recommandons d'utiliser un conteneur de stockage Blob dédié pour Azure Synapse.

La variante tempdir précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

tempFormat

Non

PARQUET

Le format dans lequel enregistrer les fichiers temporaires dans le stockage blob lors de l’écriture dans Azure Synapse. default is PARQUET; aucune autre valeur n’est autorisée actuellement.

tempCompression

Non

SNAPPY

L'algorithme de compression à utiliser pour encoder/décoder temporairement par Spark et Azure Synapse. Les valeurs actuellement prises en charge sont : UNCOMPRESSED, SNAPPY et GZIP.

forwardSparkAzureStorageCredentials

Non

false

Si true, la bibliothèque détecte automatiquement les identifiants que Spark utilise pour se connecter au conteneur de stockage Blob et transmet ces identifiants à Azure Synapse via JDBC. Ces identifiants sont envoyés dans le cadre de la query JDBC. Il est donc vivement recommandé d'activer le chiffrement SSL de la connexion JDBC lorsque vous utilisez cette option.

La version actuelle du connecteur Azure Synapse requiert (exactement) l'un des éléments forwardSparkAzureStorageCredentials, enableServicePrincipalAuth ou useAzureMSI pour être explicitement défini sur true.

La variante forward_spark_azure_storage_credentials précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

useAzureMSI

Non

false

Si true, la bibliothèque spécifiera IDENTITY = 'Managed Service Identity' et aucun SECRET pour les identifiants à l'échelle de la base de données qu'elle crée.

La version actuelle du connecteur Azure Synapse requiert (exactement) l'un des éléments forwardSparkAzureStorageCredentials, enableServicePrincipalAuth ou useAzureMSI pour être explicitement défini sur true.

enableServicePrincipalAuth

Non

false

Si true, la bibliothèque utilisera les informations d'identification du Service Principal fournies pour se connecter au compte de stockage Azure et à Azure Synapse Analytics via JDBC.

La version actuelle du connecteur Azure Synapse requiert (exactement) l'un des éléments forwardSparkAzureStorageCredentials, enableServicePrincipalAuth ou useAzureMSI pour être explicitement défini sur true.

tableOptions

Non

CLUSTERED COLUMNSTORE INDEX, DISTRIBUTION = ROUND_ROBIN

Une chaîne utilisée pour spécifier les options de table lors de la création de l'ensemble de tables Azure Synapse via dbTable. Cette chaîne est transmise littéralement à la clause WITH de l'instruction SQL CREATE TABLE qui est émise sur Azure Synapse.

La variante table_options précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

preActions

Non

Aucune valeur par default (chaîne vide)

Une liste de commandes SQL séparées par ; à exécuter dans Azure Synapse avant d'écrire des données dans l'instance Azure Synapse. Ces commandes SQL doivent être des commandes valides acceptées par Azure Synapse.

Si l'une de ces commandes échoue, elle est traitée comme une erreur et l'opération d'écriture n'est pas exécutée.

postActions

Non

Aucune valeur par default (chaîne vide)

Liste séparée par ; de commandes SQL à exécuter dans Azure Synapse une fois que le connecteur a écrit les données avec succès dans l'instance Azure Synapse. Ces commandes SQL doivent être des commandes valides acceptées par Azure Synapse.

Si l'une de ces commandes échoue, elle est traitée comme une erreur et vous obtiendrez une exception après que les données aient été écrites avec succès dans l'instance Azure Synapse.

maxStrLength

Non

256

StringType dans Spark est mappé au type NVARCHAR(maxStrLength) dans Azure Synapse. Vous pouvez utiliser maxStrLength pour définir la longueur de chaîne de toutes les colonnes de type NVARCHAR(maxStrLength) qui se trouvent dans la table nommée dbTable dans Azure Synapse.

La variante maxstrlength précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

checkpointLocation

Oui

No default

Emplacement sur DBFS qui sera utilisé par Structured Streaming pour écrire les métadonnées et les informations de point de contrôle. Consultez le guide de programmation de Structured Streaming sur la récupération après des pannes avec des points de contrôle.

numStreamingTempDirsToKeep

Non

0

Indique combien de répertoires temporaires (les plus récents) conserver pour le nettoyage périodique des micro-batch en streaming. Lorsqu'il est défini sur 0, la suppression du répertoire est Trigger immédiatement après la validation du micro batch, sinon le nombre fourni des derniers micro batches est conservé et le reste des répertoires est supprimé. Utilisez -1 pour désactiver le nettoyage périodique.

applicationName

Non

Databricks-User-Query

L'étiquette de la connexion pour chaque query. Si elle n'est pas spécifiée ou si la valeur est une chaîne vide, la valeur default du tag est ajoutée à l'URL JDBC. La valeur default empêche l'outil de monitoring Azure DB de déclencher des alertes d'injection SQL erronées contre les query.

maxbinlength

Non

No default

Contrôlez la longueur des BinaryType colonnes. Ce parameter est traduit en VARBINARY(maxbinlength).

identityInsert

Non

false

Le réglage sur true active le mode IDENTITY_INSERT, qui insère une valeur fournie par le DataFrame dans la colonne d'identité de la table Azure Synapse.

Consultez Insertion explicite de valeurs dans une colonne d'identité.

externalDataSource

Non

No default

Une source de données externe pré-provisionnée pour lire les données d'Azure Synapse. Une source de données externe ne peut être utilisée qu'avec PolyBase et supprime l'exigence de la permission CONTROL, car le connecteur n'a pas besoin de créer une accréditation limitée et une source de données externe pour charger les données.

Pour un exemple d'utilisation et la liste des autorisations requises lors de l'utilisation d'une source de données externe, consultez Autorisations Azure Synapse requises pour PolyBase avec l'option de source de données externe.

maxErrors

Non

0

Le nombre maximal de lignes qui peuvent être rejetées pendant les lectures et les écritures avant que l'Opération de chargement (PolyBase ou COPY) ne soit annulée. Les lignes rejetées seront ignorées. Par exemple, si deux enregistrements sur dix comportent des erreurs, seuls huit enregistrements seront traités.

Consultez la documentation REJECT_VALUE dans CREATE EXTERNAL TABLE et la documentation MAXERRORS dans COPY.

parameter

Obligatoire

Par défaut

Notes

dbTable

Oui, sauf si query est spécifié

No default

La table à créer ou à lire dans Azure Synapse. Ce paramètre est requis lors de la sauvegarde des données vers Azure Synapse.

Vous pouvez également utiliser {SCHEMA NAME}.{TABLE NAME} pour accéder à une table dans un schéma donné. Si le nom du schéma n'est pas fourni, le schéma par default associé à l'utilisateur JDBC est utilisé.

La variante dbtable précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

query

Oui, sauf si dbTable est spécifié

No default

La query à lire dans Azure Synapse.

Pour les tables référencées dans la requête, vous pouvez également utiliser {SCHEMA NAME}.{TABLE NAME} pour accéder à une table dans un schéma donné. Si le nom du schéma n'est pas fourni, le schéma par default associé à l'utilisateur JDBC est utilisé.

user

Non

No default

Le nom d'utilisateur Azure Synapse. Doit être utilisé conjointement avec l'option password. Peut être utilisé uniquement si l'utilisateur et le mot de passe ne sont pas transmis dans l'URL. Le fait de passer les deux entraînera une erreur.

password

Non

No default

Le mot de passe Azure Synapse. Doit être utilisé conjointement avec l'option user. Peut être utilisé uniquement si l'utilisateur et le mot de passe ne sont pas transmis dans l'URL. Le fait de passer les deux entraînera une erreur.

url

Oui

No default

Une URL JDBC avec sqlserver défini comme sous-protocole. Il est recommandé d'utiliser la chaîne de connexion fournie par le portail Azure. Le paramètre encrypt=true est fortement recommandé, car il active le chiffrement SSL de la connexion JDBC. Si user et password sont définis séparément, vous n'avez pas besoin de les inclure dans l'URL.

jdbcDriver

Non

Déterminé par le sous-protocole de l'URL JDBC.

Le nom de classe du Driver JDBC à utiliser. Cette classe doit se trouver dans le classpath. Dans la plupart des cas, il ne devrait pas être nécessaire de spécifier cette option, car le nom de classe du Driver approprié devrait être automatiquement déterminé par le sous-protocole de l'URL JDBC.

La variante jdbc_driver précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

tempDir

Oui

No default

Un URI abfss. Nous vous recommandons d'utiliser un conteneur de stockage Blob dédié pour Azure Synapse.

La variante tempdir précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

tempFormat

Non

PARQUET

Le format dans lequel enregistrer les fichiers temporaires dans le stockage blob lors de l’écriture dans Azure Synapse. default is PARQUET; aucune autre valeur n’est autorisée actuellement.

tempCompression

Non

SNAPPY

L'algorithme de compression à utiliser pour encoder/décoder temporairement par Spark et Azure Synapse. Les valeurs actuellement prises en charge sont : UNCOMPRESSED, SNAPPY et GZIP.

forwardSparkAzureStorageCredentials

Non

false

Si true, la bibliothèque détecte automatiquement les identifiants que Spark utilise pour se connecter au conteneur de stockage Blob et transmet ces identifiants à Azure Synapse via JDBC. Ces identifiants sont envoyés dans le cadre de la query JDBC. Il est donc vivement recommandé d'activer le chiffrement SSL de la connexion JDBC lorsque vous utilisez cette option.

La version actuelle du connecteur Azure Synapse requiert (exactement) l'un des éléments forwardSparkAzureStorageCredentials, enableServicePrincipalAuth ou useAzureMSI pour être explicitement défini sur true.

La variante forward_spark_azure_storage_credentials précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

useAzureMSI

Non

false

Si true, la bibliothèque spécifiera IDENTITY = 'Managed Service Identity' et aucun SECRET pour les identifiants à l'échelle de la base de données qu'elle crée.

La version actuelle du connecteur Azure Synapse requiert (exactement) l'un des éléments forwardSparkAzureStorageCredentials, enableServicePrincipalAuth ou useAzureMSI pour être explicitement défini sur true.

enableServicePrincipalAuth

Non

false

Si true, la bibliothèque utilisera les informations d'identification du Service Principal fournies pour se connecter au compte de stockage Azure et à Azure Synapse Analytics via JDBC.

La version actuelle du connecteur Azure Synapse requiert (exactement) l'un des éléments forwardSparkAzureStorageCredentials, enableServicePrincipalAuth ou useAzureMSI pour être explicitement défini sur true.

tableOptions

Non

CLUSTERED COLUMNSTORE INDEX, DISTRIBUTION = ROUND_ROBIN

Une chaîne utilisée pour spécifier les options de table lors de la création de l'ensemble de tables Azure Synapse via dbTable. Cette chaîne est transmise littéralement à la clause WITH de l'instruction SQL CREATE TABLE qui est émise sur Azure Synapse.

La variante table_options précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

preActions

Non

Aucune valeur par default (chaîne vide)

Une liste de commandes SQL séparées par ; à exécuter dans Azure Synapse avant d'écrire des données dans l'instance Azure Synapse. Ces commandes SQL doivent être des commandes valides acceptées par Azure Synapse.

Si l'une de ces commandes échoue, elle est traitée comme une erreur et l'opération d'écriture n'est pas exécutée.

postActions

Non

Aucune valeur par default (chaîne vide)

Liste séparée par ; de commandes SQL à exécuter dans Azure Synapse une fois que le connecteur a écrit les données avec succès dans l'instance Azure Synapse. Ces commandes SQL doivent être des commandes valides acceptées par Azure Synapse.

Si l'une de ces commandes échoue, elle est traitée comme une erreur et vous obtiendrez une exception après que les données aient été écrites avec succès dans l'instance Azure Synapse.

maxStrLength

Non

256

StringType dans Spark est mappé au type NVARCHAR(maxStrLength) dans Azure Synapse. Vous pouvez utiliser maxStrLength pour définir la longueur de chaîne de toutes les colonnes de type NVARCHAR(maxStrLength) qui se trouvent dans la table nommée dbTable dans Azure Synapse.

La variante maxstrlength précédemment prise en charge est obsolète et sera ignorée dans les futures versions. Utiliser le nom « camel case » à la place.

checkpointLocation

Oui

No default

Emplacement sur DBFS qui sera utilisé par Structured Streaming pour écrire les métadonnées et les informations de point de contrôle. Consultez le guide de programmation de Structured Streaming sur la récupération après des pannes avec des points de contrôle.

numStreamingTempDirsToKeep

Non

0

Indique combien de répertoires temporaires (les plus récents) conserver pour le nettoyage périodique des micro-batch en streaming. Lorsqu'il est défini sur 0, la suppression du répertoire est Trigger immédiatement après la validation du micro batch, sinon le nombre fourni des derniers micro batches est conservé et le reste des répertoires est supprimé. Utilisez -1 pour désactiver le nettoyage périodique.

applicationName

Non

Databricks-User-Query

L'étiquette de la connexion pour chaque query. Si elle n'est pas spécifiée ou si la valeur est une chaîne vide, la valeur default du tag est ajoutée à l'URL JDBC. La valeur default empêche l'outil de monitoring Azure DB de déclencher des alertes d'injection SQL erronées contre les query.

maxbinlength

Non

No default

Contrôlez la longueur des BinaryType colonnes. Ce parameter est traduit en VARBINARY(maxbinlength).

identityInsert

Non

false

Le réglage sur true active le mode IDENTITY_INSERT, qui insère une valeur fournie par le DataFrame dans la colonne d'identité de la table Azure Synapse.

Consultez Insertion explicite de valeurs dans une colonne d'identité.

externalDataSource

Non

No default

Une source de données externe pré-provisionnée pour lire les données d'Azure Synapse. Une source de données externe ne peut être utilisée qu'avec PolyBase et supprime l'exigence de la permission CONTROL, car le connecteur n'a pas besoin de créer une accréditation limitée et une source de données externe pour charger les données.

Pour un exemple d'utilisation et la liste des autorisations requises lors de l'utilisation d'une source de données externe, consultez Autorisations Azure Synapse requises pour PolyBase avec l'option de source de données externe.

maxErrors

Non

0

Le nombre maximal de lignes qui peuvent être rejetées pendant les lectures et les écritures avant que l'Opération de chargement (PolyBase ou COPY) ne soit annulée. Les lignes rejetées seront ignorées. Par exemple, si deux enregistrements sur dix comportent des erreurs, seuls huit enregistrements seront traités.

Consultez la documentation REJECT_VALUE dans CREATE EXTERNAL TABLE et la documentation MAXERRORS dans COPY.

remarque
  • tableOptions, preActions, postActions et maxStrLength sont pertinents uniquement lors de l'écriture de données de Databricks vers une nouvelle table dans Azure Synapse.
  • externalDataSource n'est pertinent que lors de la lecture de données depuis Azure Synapse et de l'écriture de données depuis Databricks vers une nouvelle table dans Azure Synapse avec la sémantique PolyBase. Vous ne devez pas spécifier d'autres types d'authentification de stockage lors de l'utilisation de externalDataSource, tels que forwardSparkAzureStorageCredentials ou useAzureMSI.
  • checkpointLocation et numStreamingTempDirsToKeep ne sont pertinentes que pour les écritures en streaming de Databricks vers une nouvelle table dans Azure Synapse.
  • Même si tous les noms d'options de source de données ne sont pas sensibles à la casse, nous vous recommandons de les spécifier en « camel case » pour plus de clarté.

Pushdown de la query vers Azure Synapse​

Le connecteur Azure Synapse implémente un ensemble de règles d’optimisation pour pousser les opérateurs suivants vers Azure Synapse :

  • Filter
  • Project
  • Limit

Les opérateurs Project et Filter prennent en charge les expressions suivantes :

  • La plupart des opérateurs logiques booléens
  • Comparaisons
  • Opérations arithmétiques de base
  • Conversions numériques et de chaînes

Pour l'opérateur Limit, le pushdown n'est pris en charge que lorsqu'aucun ordre n'est spécifié. Par exemple :

SELECT TOP(10) * FROM table, mais pas SELECT TOP(10) * FROM table ORDER BY col.

remarque

Le connecteur Azure Synapse ne transmet pas les expressions fonctionnant sur des chaînes, des dates ou des horodatages.

Le pushdown de query intégré au connecteur Azure Synapse est activé par default. Vous pouvez le désactiver en définissant spark.databricks.sqldw.pushdown sur false.

Gestion temporaire des données​

Le connecteur Azure Synapse ne supprime *pas* les fichiers temporaires qu'il crée dans le conteneur de stockage Blob. Nous vous recommandons donc de supprimer régulièrement les fichiers temporaires sous l'emplacement tempDir fourni par l'utilisateur.

Pour faciliter le nettoyage des données, le connecteur Azure Synapse ne stocke pas les fichiers de données directement sous tempDir, mais crée un sous-répertoire de la forme : <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. Vous pouvez configurer des Jobs périodiques (en utilisant la fonctionnalité des LakeFlow jobs ou autrement) pour supprimer récursivement tous les sous-répertoires plus anciens qu'un threshold donné (par exemple, 2 jours), en supposant qu'il ne peut y avoir de Jobs Spark fonctionnant plus longtemps que ce threshold.

Une alternative plus simple consiste à supprimer périodiquement l'intégralité du conteneur et à en créer un nouveau avec le même nom. Cela nécessite que vous utilisiez un conteneur dédié pour les données temporaires produites par le connecteur Azure Synapse et que vous puissiez trouver une fenêtre de temps dans laquelle vous pouvez garantir qu'aucune query impliquant le connecteur n'est en cours d'exécution.

Gestion des objets temporaires​

Le connecteur Azure Synapse automatise le transfert de données entre un cluster Databricks et une instance Azure Synapse. Pour lire des données à partir d'une table ou d'une query Azure Synapse, ou écrire des données dans une table Azure Synapse, le connecteur Azure Synapse crée des objets temporaires, y compris DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCE, EXTERNAL FILE FORMAT, et EXTERNAL TABLE en arrière-plan. Ces objets existent uniquement pendant la durée du Job Spark correspondant et devraient être automatiquement supprimés par la suite.

Lorsqu'un cluster exécute une query à l'aide du connecteur Azure Synapse, si le processus Spark Driver se bloque ou est redémarré de force, ou si le cluster est arrêté ou redémarré de force, les objets temporaires risquent de ne pas être supprimés. Pour faciliter l'identification et la suppression manuelle de ces objets, le connecteur Azure Synapse préfixe les noms de tous les objets temporaires intermédiaires créés dans l'instance Azure Synapse avec une balise de la forme : tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject>.

Nous vous recommandons de rechercher périodiquement les objets divulgués à l’aide de queries telles que les suivantes :

  • SELECT * FROM sys.database_scoped_credentials WHERE name LIKE 'tmp_databricks_%'
  • SELECT * FROM sys.external_data_sources WHERE name LIKE 'tmp_databricks_%'
  • SELECT * FROM sys.external_file_formats WHERE name LIKE 'tmp_databricks_%'
  • SELECT * FROM sys.external_tables WHERE name LIKE 'tmp_databricks_%'

Gestion des tables de points de contrôle de streaming​

Le connecteur Azure Synapse *ne supprime pas* la table de point de contrôle de streaming qui est créée lorsqu'une nouvelle query de streaming est démarrée. Ce comportement est cohérent avec le checkpointLocation sur DBFS. Par conséquent, nous vous recommandons de supprimer périodiquement les tables de point de contrôle en même temps que de supprimer les emplacements de point de contrôle sur DBFS pour les requêtes qui ne seront pas exécutées à l'avenir ou dont l'emplacement de point de contrôle a déjà été supprimé.

Par default, toutes les tables de checkpoint portent le nom <prefix>_<query-id>, où <prefix> est un préfixe configurable avec la valeur par default databricks_streaming_checkpoint et query_id est un ID de query streaming avec _ caractères supprimés. Pour trouver toutes les tables de checkpoint pour les queries streaming obsolètes ou supprimées, exécutez la query :

SQL
SELECT * FROM sys.tables WHERE name LIKE 'databricks_streaming_checkpoint%'

Vous pouvez configurer le préfixe avec l'option de configuration Spark SQL spark.databricks.sqldw.streaming.exactlyOnce.checkpointTableNamePrefix.

Questions fréquemment posées (FAQ)​

J'ai reçu une erreur en utilisant le connecteur Azure Synapse. Comment savoir si cette erreur provient d'Azure Synapse ou de Databricks ?

Pour vous aider à déboguer les erreurs, toute exception levée par le code spécifique au connecteur Azure Synapse est encapsulée dans une exception qui étend le trait SqlDWException. Les exceptions font également la distinction suivante :

  • SqlDWConnectorException représente une erreur générée par le connecteur Azure Synapse
  • SqlDWSideException représente une erreur générée par l'instance Azure Synapse connectée

Que dois-je faire si ma query a échoué avec le message d'erreur « No access key found in the session conf or the global Hadoop conf » ?

Cette erreur signifie que le connecteur Azure Synapse n'a pas pu trouver la clé d'accès au compte de stockage dans la configuration de session du Notebook ou la configuration globale Hadoop pour le compte de stockage spécifié dans tempDir. Voir Utilisation (Batch) pour des exemples de la façon de configurer correctement l'accès au compte de stockage. Si une table Spark est créée à l'aide du connecteur Azure Synapse, vous devez toujours fournir les informations d'identification d'accès au compte de stockage afin de lire ou d'écrire dans la table Spark.

Puis-je utiliser une signature d’accès partagé (SAS) pour accéder au conteneur de stockage Blob spécifié par tempDir?

Azure Synapse ne prend pas en charge l'utilisation de SAS pour accéder au stockage Blob. Par conséquent, le connecteur Azure Synapse ne prend pas en charge SAS pour accéder au conteneur de stockage Blob spécifié par tempDir.

J'ai créé une table Spark à l'aide du connecteur Azure Synapse avec l'option dbTable, j'ai écrit des données dans cette table Spark, puis j'ai supprimé cette table Spark. La table créée côté Azure Synapse sera-t-elle supprimée ?

Non. Azure Synapse est considéré comme une source de données externe. La table Azure Synapse dont le nom est défini via dbTable n'est pas supprimée lorsque la table Spark est supprimée.

Lorsque j'écris un DataFrame vers Azure Synapse, pourquoi dois-je dire .option("dbTable", tableName).save() au lieu de simplement .saveAsTable(tableName)?

En effet, nous voulons établir clairement la distinction suivante : .option("dbTable", tableName) fait référence à la table de la base de données (c'est-à-dire Azure Synapse), tandis que .saveAsTable(tableName) fait référence à la table Spark. En fait, vous pourriez même combiner les deux : df.write. ... .option("dbTable", tableNameDW).saveAsTable(tableNameSpark), qui crée une table dans Azure Synapse appelée tableNameDW et une table externe dans Spark appelée tableNameSpark qui est adossée à la table Azure Synapse.

attention

Attention à la différence suivante entre .save() et .saveAsTable():

  • Pour df.write. ... .option("dbTable", tableNameDW).mode(writeMode).save(), writeMode agit sur la table Azure Synapse, comme prévu.
  • Pour df.write. ... .option("dbTable", tableNameDW).mode(writeMode).saveAsTable(tableNameSpark), writeMode agit sur la table Spark, tandis que tableNameDW est écrasé silencieusement s'il existe déjà dans Azure Synapse.

Ce comportement n'est pas différent de l'écriture dans n'importe quelle autre source de données. Il s'agit juste d'une mise en garde concernant l'API DataFrameWriter de Spark.

Sur cette page