Interroger des données dans Azure Synapse Analytics

Article
03/01/2024

Vous pouvez accéder à Azure Synapse à partir d’Azure Databricks à l’aide du connecteur Azure Synapse, qui utilise l’instruction COPY dans Azure Synapse pour transférer efficacement de gros volumes de données entre un cluster Azure Databricks et une instance Azure Synapse à l’aide d’un compte de stockage Azure Data Lake Storage Gen2 pour une mise en lots temporaire.

Notes

Vous pouvez préférer Lakehouse Federation pour gérer les requêtes sur les données Azure Synapse ou Azure Data Warehouse. Consultez Qu’est-ce que la Fédération Lakehouse.

Azure Synapse Analytics est un entrepôt de données d’entreprise cloud qui tire parti du traitement MPP (Massively Parallel Processing) pour exécuter rapidement des requêtes complexes sur des pétaoctets de données.

Important

Ce connecteur doit être utilisé uniquement avec les instances de pool dédié Synapse. Il n’est pas compatible avec les autres composants Synapse.

Remarque

COPY est disponible uniquement sur les instances Azure Data Lake Storage Gen2. Si vous recherchez des détails sur l’utilisation de PolyBase, consultez Connexion d’Azure Databricks et d’Azure Synapse avec PolyBase (hérité).

Exemple de syntaxe pour Synapse

Vous pouvez interroger Synapse dans Scala, Python, SQL et R. Les exemples de code suivants utilisent des clés de compte de stockage et transfèrent les informations d’identification de stockage d’Azure Databricks à Synapse.

Notes

Utilisez la chaîne de connexion fournie par le portail Azure qui permet d’activer le chiffrement SSL (Secure Sockets Layer) pour l’ensemble des données transmises entre le pilote Spark et l’instance Azure Synapse via la connexion JDBC. Pour vérifier que le chiffrement SSL est activé, recherchez encrypt=true dans la chaîne de connexion.

Important

Les emplacements externes définis dans Unity Catalog ne sont pas pris en charge en tant qu’emplacements tempDir.

Scala


// Set up the 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. The following example applies to Databricks Runtime 11.3 LTS and above.
val df: DataFrame = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") /* Optional - will use default port 1433 if not specified. */
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") /* If schemaName not provided, default to "dbo". */
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

// Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
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()

Python


# Set up the 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. The following example applies to Databricks Runtime 11.3 LTS and above.
df = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") # Optional - will use default port 1433 if not specified.
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") # If schemaName not provided, default to "dbo".
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

# Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
df = 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.
df = 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()

SQL


-- Set up the storage account access key in the notebook session conf.
SET fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net=<your-storage-account-access-key>;

-- Read data using SQL. The following example applies to Databricks Runtime 11.3 LTS and above.
CREATE TABLE example_table_in_spark_read
USING sqldw
OPTIONS (
  host '<hostname>',
  port '<port>' /* Optional - will use default port 1433 if not specified. */
  user '<username>',
  password '<password>',
  database '<database-name>'
  dbtable '<schema-name>.<table-name>', /* If schemaName not provided, default to "dbo". */
  forwardSparkAzureStorageCredentials 'true',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Read data using SQL. The following example applies to Databricks Runtime 10.4 LTS and below.
CREATE TABLE example_table_in_spark_read
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbtable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Write data using SQL.
-- Create a new table, throwing an error if a table with the same name already exists:

CREATE TABLE example_table_in_spark_write
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbTable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
)
AS SELECT * FROM table_to_save_in_spark;

R

# Load SparkR
library(SparkR)

# Set up the storage account access key in the notebook session conf.
conf <- sparkR.callJMethod(sparkR.session(), "conf")
sparkR.callJMethod(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.
df <- read.df(
   source = "com.databricks.spark.sqldw",
   url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
   forward_spark_azure_storage_credentials = "true",
   dbTable = "<your-table-name>",
   tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

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

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse.

write.df(
  df,
  source = "com.databricks.spark.sqldw",
  url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
  forward_spark_azure_storage_credentials = "true",
  dbTable = "<your-table-name>",
  tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

Comment fonctionne l’authentification entre Azure Databricks et Synapse ?

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

Pilote Spark vers Azure Synapse
Cluster Spark vers un compte de stockage Azure
Azure Synapse vers un compte de stockage Azure

Configuration de l’accès au stockage Azure

Azure Databricks et Synapse ont tous deux besoin d’un accès privilégié à un compte de stockage Azure pour le stockage de données temporaires.

Azure Synapse ne prend pas en charge l’utilisation de la signature d’accès partagé pour l’accès au compte de stockage. Pour configurer l’accès pour les deux services, effectuez l’une des opérations suivantes :

Utilisez la clé de compte et le secret du compte de stockage et définissez forwardSparkAzureStorageCredentials sur true. Consultez Définir des propriétés Spark pour configurer des informations d’identification Azure afin d’accéder au stockage Azure.
Utilisez Azure Data Lake Storage Gen2 avec l’authentification OAuth 2.0 et définissez enableServicePrincipalAuth sur true. Consultez Configurer la connexion d’Azure Databricks à Synapse avec OAuth 2.0 avec un principal de service.
Configurez votre instance Azure Synapse pour disposer d’une identité du service managée et définissez useAzureMSI sur true.

Autorisations Azure Synapse nécessaires

En raison de l’utilisation de COPY en arrière-plan, le connecteur Azure Synapse requiert que l’utilisateur de la connexion JDBC soit autorisé à exécuter les commandes suivantes dans l’instance Azure Synapse connectée :

COPY INTO

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

CREATE TABLE

Le tableau suivant récapitule les autorisations nécessaires pour les écritures avec COPY :

Autorisations (insérer dans une table existante)	Autorisations (insérer dans une nouvelle table)
ADMINISTER DATABASE BULK OPERATIONS INSERT	ADMINISTER DATABASE BULK OPERATIONS INSERT CREATE TABLE ALTER ON SCHEMA :: dbo

Configurations de mise en réseau

Si vous configurez un pare-feu sur Azure Synapse, vous devez configurer les paramètres réseau pour qu’Azure Databricks puisse atteindre Azure Synapse. Assurez-vous tout d’abord que votre espace de travail Azure Databricks est déployé dans votre propre réseau virtuel conformément aux instructions Déployer Azure Databricks dans votre réseau virtuel Azure (injection dans le réseau virtuel). Vous pouvez ensuite configurer des règles de pare-feu IP sur Azure Synapse pour autoriser les connexions de vos sous-réseaux à votre compte Synapse. Consultez Règles de pare-feu IP Azure Synapse Analytics.

Configurer la connexion d’Azure Databricks à Synapse avec OAuth 2.0 avec un principal de service

Vous pouvez vous authentifier auprès d’Azure Synapse Analytics à l’aide d’un principal de service ayant accès au compte de stockage sous-jacent. Si vous souhaitez obtenir plus d’informations sur l’utilisation des informations d’identification du principal de service pour accéder à un compte de stockage Azure, consultez Se connecter à Azure Data Lake Storage Gen2 et au Stockage Blob. Vous devez définir l’option enableServicePrincipalAuth sur true dans la configuration de connexion Informations de référence sur les options du connecteur Azure Databricks Synapse pour permettre au connecteur de s’authentifier avec un principal de service.

Vous pouvez éventuellement utiliser un principal de service différent pour la connexion à Azure Synapse Analytics. Voici un exemple qui configure les informations d’identification du principal de service pour le compte de stockage et les informations d’identification du principal de service facultatif 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>

Scala

// Defining the Service Principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<application-id>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<service-credential>")
spark.conf.set("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.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

Python

# Defining the service principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<application-id>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<service-credential>")
spark.conf.set("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.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

R

# Load SparkR
library(SparkR)
conf <- sparkR.callJMethod(sparkR.session(), "conf")

# Defining the service principal credentials for the Azure storage account
sparkR.callJMethod(conf, "set", "fs.azure.account.auth.type", "OAuth")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.id", "<application-id>")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.secret", "<service-credential>")
sparkR.callJMethod(conf, "set", "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)
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

Modes d’enregistrement pris en charge pour les écritures par lots

Le connecteur Azure Synapse prend en charge les modes d’enregistrement ErrorIfExists, Ignore, Append et Overwrite avec le mode par défaut défini sur ErrorIfExists. Pour plus d’informations sur les modes d’enregistrement pris en charge dans Apache Spark, consultez la documentation Spark SQL sur les modes d’enregistrement.

Informations de référence sur les options du connecteur Azure Databricks Synapse

Le OPTIONS fourni dans Spark SQL prend en charge les paramètres suivants :

Paramètre	Obligatoire	Default	Notes
`dbTable`	Oui, sauf si `query` est spécifié	Pas de valeur par défaut	Table utilisée pour l’écriture ou la lecture dans Azure Synapse. Ce paramètre est obligatoire pour la réécriture des données dans Azure Synapse. Vous pouvez aussi 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 défaut associé à l’utilisateur JDBC est utilisé. La variante `dbtable` auparavant prise en charge est maintenant dépréciée et sera supprimée dans les versions ultérieures. Utilisez le nom en casse mixte à la place.
`query`	Oui, sauf si `dbTable` est spécifié	Pas de valeur par défaut	Requête de lecture 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 défaut associé à l’utilisateur JDBC est utilisé.
`user`	Non	Pas de valeur par défaut	Nom d’utilisateur Azure Synapse. Doit être utilisé en tandem avec l’option `password`. Peut être utilisé uniquement si l’utilisateur et le mot de passe ne sont pas passés dans l’URL. Une erreur se produit si ces deux paramètres sont passés.
`password`	Non	Pas de valeur par défaut	Mot de passe Azure Synapse. Doit être utilisé en tandem avec l’option `user`. Peut être utilisé uniquement si l’utilisateur et le mot de passe ne sont pas passés dans l’URL. Une erreur se produit si ces deux paramètres sont passés.
`url`	Oui	Pas de valeur par défaut	URL JDBC avec `sqlserver` défini comme sous-protocole. Il est recommandé d’utiliser la chaîne de connexion fournie par le portail Azure. 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	Nom de la classe du pilote JDBC à utiliser. Cette classe doit être sur le classpath. Dans la plupart des cas, il n’est pas nécessaire de spécifier cette option, car le nom de la classe du pilote approprié est en principe défini automatiquement par le sous-protocole de l’URL JDBC. La variante `jdbc_driver` auparavant prise en charge est maintenant dépréciée et sera supprimée dans les versions ultérieures. Utilisez le nom en casse mixte à la place.
`tempDir`	Oui	Pas de valeur par défaut	URI `abfss`. Nous vous recommandons d’utiliser un conteneur de stockage Blob dédié pour Azure Synapse. La variante `tempdir` auparavant prise en charge est maintenant dépréciée et sera supprimée dans les versions ultérieures. Utilisez le nom en casse mixte à la place. Vous ne pouvez pas utiliser un emplacement externe défini dans Unity Catalog comme emplacement `tempDir`.
`tempCompression`	Non	`SNAPPY`	Algorithme de compression à utiliser pour encoder/décoder les données temporaires par Spark et Azure Synapse. Valeurs actuellement prises en charge : `UNCOMPRESSED`, `SNAPPY` et `GZIP`
`forwardSparkAzureStorageCredentials`	Non	false	Si le paramètre est défini sur `true`, la bibliothèque découvre automatiquement les informations d’identification de clé d’accès au compte de stockage que Spark utilise pour se connecter au conteneur de stockage blob, puis elle les transmet à Azure Synapse via JDBC. Ces informations d’identification sont envoyées dans la requête JDBC. Il est donc fortement recommandé d’activer le chiffrement SSL de la connexion JDBC si vous utilisez cette option. Lors de la configuration de l’authentification du stockage, vous devez définir exactement l’un de `useAzureMSI` et `forwardSparkAzureStorageCredentials` sur `true`. Vous pouvez également définir `enableServicePrincipalAuth` sur `true` et utiliser le principal de service pour l’authentification de stockage et JDBC. L’option `forwardSparkAzureStorageCredentials` ne prend pas en charge l’authentification au stockage en utilisant une identité du service managée ou un principal de service. Seule la clé d’accès au compte de stockage est prise en charge. La variante `forward_spark_azure_storage_credentials` auparavant prise en charge est maintenant dépréciée et sera supprimée dans les versions ultérieures. Utilisez le nom en casse mixte à la place.
`useAzureMSI`	Non	false	Si le paramètre est défini sur `true`, la bibliothèque spécifie `IDENTITY = 'Managed Service Identity'` et pas de `SECRET` pour les informations d’identification délimitées à la base de données qu’elle crée. Lors de la configuration de l’authentification du stockage, vous devez définir exactement l’un de `useAzureMSI` et `forwardSparkAzureStorageCredentials` sur `true`. Vous pouvez également définir `enableServicePrincipalAuth` sur `true` et utiliser le principal de service pour l’authentification de stockage et JDBC.
`enableServicePrincipalAuth`	Non	false	Si le paramètre est défini sur `true`, la bibliothèque utilise les informations d’identification du principal de service fournies pour se connecter au compte de stockage Azure et à Azure Synapse Analytics via JDBC. Si `forward_spark_azure_storage_credentials` ou `useAzureMSI` est défini sur `true`, cette option est prioritaire sur le principal de service dans l’authentification du stockage.
`tableOptions`	Non	`CLUSTERED COLUMNSTORE INDEX`, `DISTRIBUTION = ROUND_ROBIN`	Chaîne utilisée pour spécifier des options de table quand vous créez la table Azure Synapse définie avec `dbTable`. Cette chaîne est passée littéralement à la clause `WITH` de l’instruction SQL `CREATE TABLE` qui est émise sur Azure Synapse. La variante `table_options` auparavant prise en charge est maintenant dépréciée et sera supprimée dans les versions ultérieures. Utilisez le nom en casse mixte à la place.
`preActions`	Non	Pas de valeur par défaut (chaîne vide)	Liste séparée par le signe `;` des commandes SQL à exécuter dans Azure Synapse avant d’écrire des données dans l’instance Azure Synapse. Ces commandes SQL doivent être des commandes valides prises en charge 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	Pas de valeur par défaut (chaîne vide)	Liste séparée par le signe `;` des commandes SQL à exécuter dans Azure Synapse après que le connecteur a terminé d’écrire les données dans l’instance Azure Synapse. Ces commandes SQL doivent être des commandes valides prises en charge par Azure Synapse. Si l’une de ces commandes échoue, elle est traitée comme une erreur, et une exception est levée après l’écriture des données 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` auparavant prise en charge est maintenant dépréciée et sera supprimée dans les versions ultérieures. Utilisez le nom en casse mixte à la place.
`applicationName`	Non	`Databricks-User-Query`	Étiquette de la connexion pour chaque requête. Si l’étiquette n’est pas spécifiée ou si sa valeur est une chaîne vide, la valeur par défaut de l’étiquette est ajoutée à l’URL JDBC. Avec la valeur par défaut, l’outil Azure DB Monitoring ne peut pas déclencher d’alertes d’injection SQL parasites sur des requêtes.
`maxbinlength`	Non	Pas de valeur par défaut	Contrôle la longueur de colonne des colonnes de type `BinaryType`. Ce paramètre est converti en `VARBINARY(maxbinlength)`.
`identityInsert`	Non	false	Le paramètre défini sur `true` active le mode `IDENTITY_INSERT`, qui insère une valeur fournie par le DataFrame dans la colonne IDENTITY de la table Azure Synapse. Consultez Insérer explicitement des valeurs dans une colonne IDENTITY.
`externalDataSource`	Non	Pas de valeur par défaut	Source de données externe préprovisionnée qui est utilisée pour lire les données dans Azure Synapse. Une source de données externe peut être utilisée uniquement avec PolyBase. Elle supprime l’obligation d’autorisation CONTROL, car le connecteur n’a pas besoin de créer des informations d’identification délimitées ni une source de données externe pour charger des données. Pour obtenir un exemple d’utilisation et la liste des autorisations requises avec une source de données externe, consultez Autorisations Azure Synapse requises pour utiliser PolyBase avec l’option de source de données externe.
`maxErrors`	Non	0	Nombre maximal de lignes pouvant être rejetées pendant des lectures et écritures avant l’annulation de l’opération de chargement. Les lignes rejetées sont ignorées. Par exemple, si deux enregistrements sur dix comportent des erreurs, seuls huit enregistrements sont traités. Consultez la documentation de REJECT_VALUE dans CREATE EXTERNAL TABLE et la documentation de MAXERRORS dans COPY.
`inferTimestampNTZType`	Non	false	Si `true`, les valeurs de type Azure Synapse `TIMESTAMP` sont interprétées comme `TimestampNTZType` (horodatage sans fuseau horaire) pendant les lectures. Dans le cas contraire, tous les horodatages sont interprétés comme étant `TimestampType`, quel que soit le type dans la table Azure Synapse sous-jacente.

Notes

tableOptions, preActions, postActions et maxStrLength sont pertinents uniquement pour écrire des données issues d’Azure Databricks dans une nouvelle table dans Azure Synapse.
Les noms des options de source de données n’imposent pas le respect de la casse, mais nous vous recommandons toutefois de les spécifier en casse mixte pour plus de clarté.

Pushdown des requêtes dans Azure Synapse

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

Filter
Project
Limit

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

Majeure partie des opérateurs logiques booléens
Comparaisons
Opérations arithmétiques de base
Casts numériques et de chaînes

Pour l’opérateur Limit, le pushdown est pris en charge uniquement quand aucun ordre n’est spécifié. Par exemple :

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

Notes

Le connecteur Azure Synapse ne pousse pas les expressions utilisées sur des chaînes, des dates ou des horodateurs.

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

Gestion des données temporaires

Le connecteur Azure Synapse ne supprime pas les fichiers temporaires qu’il crée dans le conteneur de stockage Azure. Databricks recommande de supprimer régulièrement les fichiers temporaires sous l’emplacement tempDir spécifié 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 ; il crée à la place un sous-répertoire au format <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. Vous pouvez créer des travaux périodiques (à l’aide de la fonctionnalité travaux d’Azure Databricks, par exemple) pour supprimer de manière récursive tous les sous-répertoires antérieurs à une période spécifiée (par exemple, deux jours), en partant du principe qu’il ne peut pas y avoir de travaux Spark d’une durée plus longue que cette période.

Une autre solution, plus simple, consiste à supprimer régulièrement le conteneur entier et à en recréer un autre du même nom. Cela est possible si sous utilisez un conteneur dédié pour les données temporaires produites par le connecteur Azure Synapse et si vous pouvez identifier une fenêtre de temps durant laquelle vous êtes certain qu’aucune requête impliquant le connecteur n’est en cours d’exécution.

Gestion des objets temporaires

Le connecteur Azure Synapse automatise le transfert des données entre un cluster Azure Databricks et une instance Azure Synapse. Pour lire les données d’une table ou d’une requête Azure Synapse ou pour écrire des données dans une table Azure Synapse, le connecteur Azure Synapse crée en arrière-plan des objets temporaires, dont DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCE, EXTERNAL FILE FORMAT et EXTERNAL TABLE. Ces objets existent uniquement pendant la durée du travail Spark correspondant et sont automatiquement supprimés.

Lorsqu’un cluster exécute une requête avec le connecteur Azure Synapse, si le processus du pilote Spark plante ou est redémarré de force, ou si le cluster est arrêté ou redémarré, il arrive que des objets temporaires ne soient pas 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 étiquette de la forme suivante : tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject>.

Nous vous recommandons de rechercher régulièrement les objets fuités à l’aide de requêtes similaires à celles-ci :

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_%'

Interroger des données dans Azure Synapse Analytics

Exemple de syntaxe pour Synapse

Scala

Python

SQL

R

Comment fonctionne l’authentification entre Azure Databricks et Synapse ?

Configuration de l’accès au stockage Azure

Autorisations Azure Synapse nécessaires

Configurations de mise en réseau

Configurer la connexion d’Azure Databricks à Synapse avec OAuth 2.0 avec un principal de service

ini

Scala

Python

R

Modes d’enregistrement pris en charge pour les écritures par lots

Informations de référence sur les options du connecteur Azure Databricks Synapse

Pushdown des requêtes dans Azure Synapse

Gestion des données temporaires

Gestion des objets temporaires

Ressources supplémentaires