Informations de référence sur les options d’API Spark

Cette page répertorie les options d’entrée et de sortie disponibles pour les API Spark qui lisent et écrivent des données.

Options DataFrameReader

Utilisez ces options avec DataFrameReader.option(), DataFrameReader.options(), read_files, COPY INTO et Auto Loader pour contrôler la façon dont Azure Databricks lit les fichiers de données.

Example

L’exemple suivant définit multiLine la valeur pour True lire des fichiers JSON :

Python

df = spark.read.format("json").option("multiLine", True).load("/path/to/data")

Scala

val df = spark.read.format("json").option("multiLine", "true").load("/path/to/data")

SQL

SELECT * FROM read_files("/path/to/data", format => "json", multiLine => true)

Commun

Les options suivantes s’appliquent à tous les formats de fichier.

Clé	Par défaut	Valeurs valides	Description
ignoreCorruptFiles	false	true, false	Indique s’il faut ignorer les fichiers endommagés. Si la valeur est true, les travaux Spark continueront à s’exécuter lorsqu’ils rencontrent des fichiers manquants et le contenu qui a été lu sera toujours renvoyé. Pour COPY INTO, vous pouvez observer les fichiers endommagés ignorés comme numSkippedCorruptFiles dans la operationMetrics colonne de l’historique Delta Lake. Disponible dans Databricks Runtime 11.3 LTS et versions ultérieures.
ignoreMissingFiles	false pour le chargeur automatique, true pour COPY INTO (hérité)	true, false	Indique s’il faut ignorer les fichiers manquants. Si la valeur est true, les travaux Spark continuent à s’exécuter lors de la rencontre de fichiers manquants et le contenu est toujours retourné. Disponible dans Databricks Runtime 11.3 LTS et versions ultérieures.
modifiedAfter	None	Chaîne d’horodatage	Horodatage facultatif en tant que filtre pour ingérer uniquement les fichiers qui ont un horodatage de modification après l’horodatage spécifié.
modifiedBefore	None	Chaîne d’horodatage	Horodatage facultatif en tant que filtre pour ingérer uniquement les fichiers qui ont un horodatage de modification avant l’horodatage spécifié.
pathGlobFilter ou fileNamePattern	None	Chaîne de modèle glob	Modèle glob potentiel pour choisir des fichiers. Équivalent à PATTERN in COPY INTO (hérité). fileNamePattern peut être utilisé dans read_files.
recursiveFileLookup	false	true, false	Quand true, cette option effectue une recherche dans des répertoires imbriqués même si leurs noms ne suivent pas un schéma de nommage de partition comme date=2019-07-01.

Avro

Les options suivantes s’appliquent lors de la lecture des fichiers Avro.

Clé	Par défaut	Valeurs valides	Description
avroSchema	None	Chaîne de schéma Avro	Schéma facultatif spécifié par un utilisateur au format Avro. Lors de la lecture d’Avro, cette option peut être définie sur un schéma évolué compatible mais différent du schéma Avro réel. Le schéma de désérialisation est cohérent avec le schéma évolué. Par exemple, si vous définissez un schéma évolué contenant une colonne supplémentaire avec une valeur par défaut, le résultat de lecture contient également la nouvelle colonne.
avroSchemaEvolutionMode	none	none, restart	Comment gérer l’évolution du schéma lors de l’utilisation d’un registre de schémas. none ignore les modifications de schéma et poursuit le travail. restart déclenche une UnknownFieldException détection des modifications de schéma et nécessite un redémarrage du travail.
datetimeRebaseMode	LEGACY	EXCEPTION, , LEGACYCORRECTED	Contrôle le rebasage des valeurs DATE et TIMESTAMP entre les calendriers julien et grégorien proleptique.
enableStableIdentifiersForUnionType	false	true, false	Indique s’il faut utiliser des noms de champs stables pour les types Avro Union. Lorsqu’ils sont activés, les noms de champs de type union sont dérivés de leurs noms de types en minuscules (par exemple, , member_intmember_string). Lève une exception si deux noms de type sont identiques après la casse.
mergeSchema	false	true, false	Indique s’il faut déduire le schéma entre plusieurs fichiers et fusionner le schéma de chaque fichier. mergeSchema pour Avro n’assouplit pas les types de données.
mode	FAILFAST	FAILFAST, , PERMISSIVEDROPMALFORMED	Mode d’analyse pour la gestion des enregistrements endommagés. FAILFAST lève une exception. PERMISSIVE définit les champs mal formés sur Null. DROPMALFORMED supprime silencieusement les enregistrements incorrects.
readerCaseSensitive	true	true, false	Spécifie le comportement de respect de la casse lorsque rescuedDataColumn est activé. Si la valeur est true, sauvez les colonnes de données dont les noms diffèrent par cas du schéma. Lorsque la valeur est false, lisez les données de manière non sensible à la casse.
recursiveFieldMaxDepth	None	De 0 à 15.	Profondeur maximale de récursivité pour les champs Avro récursifs. Défini pour 1 tronquer tous les champs récursifs, 2 pour autoriser un niveau de récursivité, et ainsi de suite jusqu’à 15. Lorsque des champs non défini ou 0récursifs ne sont pas autorisés.
rescuedDataColumn	None	Chaîne de nom de colonne	Indique s’il faut collecter, dans une colonne distincte, toutes les données qui ne peuvent pas être analysées en raison d’une incompatibilité de type de données et d’une incompatibilité de schéma (y compris la casse de colonne). Cette colonne est incluse par défaut lors de l’utilisation d’Auto Loader. COPY INTO (hérité) ne prend pas en charge la colonne de données sauvée, car vous ne pouvez pas définir manuellement le schéma à l’aide de COPY INTO. Databricks recommande d’utiliser le chargeur automatique pour la plupart des scénarios d’ingestion. Pour plus de détails, reportez-vous à Qu’est-ce que la colonne des données récupérées ?.
stableIdentifierPrefixForUnionType	member_	Toute chaîne de caractères	Préfixe à utiliser pour les noms de champs de type union stable quand enableStableIdentifiersForUnionType=true.

CSV

Les options suivantes s’appliquent lors de la lecture de fichiers CSV.

Clé	Par défaut	Valeurs valides	Description
badRecordsPath	None	Chaîne de chemin d’accès	Chemin d’accès pour stocker les fichiers contenant des informations sur les enregistrements CSV incorrects.
charToEscapeQuoteEscaping	\0	Un caractère unique	Caractère utilisé pour placer dans une séquence d’échappement le caractère utilisé pour les guillemets d’échappement. Par exemple, pour l'enregistrement suivant : [ " a\\", b ] : Si le caractère d'échappement pour '\' n’est pas défini, l’enregistrement ne sera pas parsé. L’analyseur lira les caractères : [a],[\],["],[,],[ ],[b] et générera une erreur car il ne trouve pas de guillemet fermant. Si le caractère d’échappement de '\' est défini comme '\', l’enregistrement est lu avec 2 valeurs : [a\] et [b].
columnNameOfCorruptRecord	_corrupt_record	Chaîne de nom de colonne	Pris en charge pour Auto Loader. Pas pris en charge pour COPY INTO (ancien système). Colonne destinée au stockage des enregistrements malformés et qui ne peuvent pas être analysés. Si l’élément mode de l'analyse est défini comme DROPMALFORMED, cette colonne sera vide.
comment	\0	Un caractère unique	Définit le caractère qui représente un commentaire de ligne lorsqu’il se trouve au début d’une ligne de texte. Utilisez '\0' pour désactiver le saut des commentaires.
dateFormat	yyyy-MM-dd	Chaîne de format de date	Format d’analyse des chaînes de date.
emptyValue	Chaîne vide	Toute chaîne de caractères	Représentation sous forme de chaîne d’une valeur vide.
enableDateTimeParsingFallback	false	true, false	Indique s’il faut revenir au comportement d’analyse de date et d’horodatage hérité lorsqu’une valeur ne peut pas être analysée avec le format spécifié. Lorsque false, l’analyse des échecs déclenche une erreur ou produit une valeur Null en fonction modede .
encoding ou charset	UTF-8	Nom java.nio.charset.Charset	Nom de l’encodage des fichiers CSV. Pour obtenir la liste des options, consultez java.nio.charset.Charset. UTF-16 et UTF-32 ne peuvent pas être utilisées lorsque multiline est true.
enforceSchema	true	true, false	Indique s’il faut appliquer de force le schéma spécifié ou déduit aux fichiers CSV. Si l’option est activée, les en-têtes des fichiers CSV sont ignorés. Cette option est ignorée par défaut lors de l’utilisation d’Auto Loader pour récupérer des données et permettre l’évolution du schéma.
escape	\	Un caractère unique	Caractère d’échappement à utiliser lors de l’analyse des données.
extension	csv	Chaîne d’extension de fichier	Extension de nom de fichier attendue pour les lectures. Les fichiers sans cette extension sont filtrés.
failOnUnknownFields	false	true, false	Indique s’il faut échouer lorsque l’enregistrement CSV contient des colonnes non présentes dans le schéma. Quand false, les colonnes non reconnues sont supprimées ou sauvées en mode silencieux en fonction rescuedDataColumnde .
failOnWidenedFields	false	true, false	Indique s’il faut échouer lorsqu’une valeur de champ ne peut pas être analysée en tant que type de schéma déclaré sans élargir. Lorsque false, les valeurs à l’échelle du type sont sauvées en mode silencieux en fonction rescuedDataColumnde . Le paramètre failOnUnknownFields=true peut masquer les effets de cette option.
header	false	true, false	Indique si les fichiers CSV contiennent un en-tête. Auto Loader suppose que les fichiers comportent des en-têtes lors de l’inférence du schéma.
ignoreLeadingWhiteSpace	false	true, false	Indique s’il faut ignorer les espaces blancs de début pour chaque valeur analysée.
ignoreTrailingWhiteSpace	false	true, false	Indique s’il faut ignorer les espaces blancs de fin pour chaque valeur analysée.
inferSchema	false	true, false	Indique s’il faut déduire les types de données des enregistrements CSV analysés ou supposer que toutes les colonnes sont de type StringType. Nécessite un passage supplémentaire sur les données si la valeur est true. Pour Chargeur automatique, utilisez cloudFiles.inferColumnTypes à la place.
inputBufferSize	1048576 (1 Mo)	Entiers positifs	Taille de la mémoire tampon en octets pour l’analyseur CSV. Utile pour optimiser l’utilisation de la mémoire lors de l’analyse de fichiers CSV volumineux.
lineSep	Aucun, qui couvre \r, \r\net \n	Chaîne	Une chaîne entre deux enregistrements CSV consécutifs.
locale	US	Identificateur java.util.Locale	Un Java paramètres régionaux identifiés qui affectent la date, l’horodatage et l’analyse décimale par défaut dans le fichier CSV.
maxCharsPerColumn	-1	Entiers positifs ou -1 illimités	Nombre maximal de caractères attendus d’une valeur à analyser. Peut être utilisé pour éviter les erreurs de mémoire. La valeur par défaut est -1, ce qui signifie illimité.
maxColumns	20480	Entiers positifs	Limite inconditionnelle du nombre de colonnes qu’un enregistrement peut avoir.
mergeSchema	false	true, false	Indique s’il faut déduire le schéma entre plusieurs fichiers et fusionner le schéma de chaque fichier. Option activée par défaut pour Auto Loader lors de l’inférence du schéma.
mode	PERMISSIVE	PERMISSIVE, , DROPMALFORMEDFAILFAST	Mode de l’analyseur pour la gestion des enregistrements mal formés.
multiLine	false	true, false	Indique si les enregistrements CSV s’étendent sur plusieurs lignes.
nanValue	NaN	Toute chaîne de caractères	Représentation sous forme de chaîne d'une valeur non numérique lors de l'analyse des colonnes FloatType et DoubleType.
negativeInf	-Inf	Toute chaîne de caractères	Représentation sous forme de chaîne de l'infini négatif lors de l'analyse des colonnes FloatType ou DoubleType.
nullValue	Chaîne vide	Toute chaîne de caractères	Représentation sous forme de chaîne d’une valeur Null.
parserCaseSensitive (déconseillé)	false	true, false	Lors de la lecture de fichiers, indique s’il faut aligner les colonnes déclarées dans l’en-tête avec le cas de schéma en respectant la casse. Il s’agit de true par défaut pour Auto Loader. Les colonnes qui diffèrent au niveau de la casse sont récupérées dans rescuedDataColumn si cette option est activée. Cette option a été abandonnée au profit de readerCaseSensitive.
positiveInf	Inf	Toute chaîne de caractères	Représentation sous forme de chaîne de l'infini positif lors de l'analyse des colonnes FloatType ou DoubleType.
preferDate	true	true, false	Tente d'interpréter des chaînes sous forme de dates plutôt que des horodatages lorsque cela est possible. Vous devez également utiliser l’inférence de schéma, soit en activant inferSchema ou en utilisant cloudFiles.inferColumnTypes le chargeur automatique.
quote	"	Un caractère unique	Caractère utilisé pour échapper des valeurs où le délimiteur de champ fait partie de la valeur.
readerCaseSensitive	true	true, false	Spécifie le comportement de respect de la casse lorsque rescuedDataColumn est activé. Si la valeur est true, sauvez les colonnes de données dont les noms diffèrent par cas du schéma. Lorsque la valeur est false, lisez les données de manière non sensible à la casse.
rescuedDataColumn	None	Chaîne de nom de colonne	Indique s’il faut collecter, dans une colonne distincte, toutes les données qui ne peuvent pas être analysées en raison d’une incompatibilité de type de données et d’une incompatibilité de schéma (y compris la casse de colonne). Cette colonne est incluse par défaut lors de l’utilisation d’Auto Loader. Pour plus de détails, reportez-vous à Qu’est-ce que la colonne des données récupérées ?. COPY INTO (hérité) ne prend pas en charge la colonne de données sauvée, car vous ne pouvez pas définir manuellement le schéma à l’aide de COPY INTO. Databricks recommande d’utiliser le chargeur automatique pour la plupart des scénarios d’ingestion.
sep ou delimiter	,	Chaîne	Chaîne de séparateur entre les colonnes.
singleVariantColumn	None	Chaîne de nom de colonne	Lorsqu’il est défini sur un nom de colonne, lit l’enregistrement CSV entier dans une seule VariantType colonne avec ce nom au lieu d’analyser chaque champ dans sa propre colonne. Exige header=true.
skipRows	0	Entiers positifs ou 0	Nombre de lignes à partir du début du fichier CSV à ignorer, y compris les lignes commentées et vides. Si header a la valeur vraie, l’en-tête sera la première ligne non ignorée et non commentée.
timeFormat	HH:mm:ss	Chaîne de format de temps	Format d’analyse des valeurs de TimeType colonne.
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Chaîne de format d’horodatage	Format d’analyse des chaînes de timestamp.
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Chaîne de format d’horodatage	Format d’analyse de l’horodatage sans chaînes de fuseau horaire (TimestampNTZType).
timeZone	None	Chaîne java.time.ZoneId	L’élément java.time.ZoneId à utiliser lors de l'analyse des timestamps et des dates.
unescapedQuoteHandling	STOP_AT_DELIMITER	STOP_AT_CLOSING_QUOTE, , BACK_TO_DELIMITERSTOP_AT_DELIMITER, , SKIP_VALUERAISE_ERROR	Stratégie de gestion des guillemets sans séquence d’échappement. Le comportement de chaque option autorisée est le suivant : STOP_AT_CLOSING_QUOTE : si l’entrée contient des guillemets sans séquence d’échappement, accumule le caractère de guillemet et continue à analyser la valeur comme une valeur entre guillemets, jusqu’à ce qu’un guillemet fermant soit trouvé. BACK_TO_DELIMITER : si l’entrée contient des guillemets sans séquence d’échappement, considère la valeur comme une valeur sans guillemets. L'analyseur accumulera tous les caractères de la valeur analysée actuelle jusqu'à trouver le délimiteur défini par sep. Si la valeur ne contient aucun délimiteur, l’analyseur continue à accumuler les caractères de l’entrée jusqu’à trouver un délimiteur ou une fin de ligne. STOP_AT_DELIMITER : si l’entrée contient des guillemets sans séquence d’échappement, considère la valeur comme une valeur sans guillemets. L'analyseur accumulera tous les caractères jusqu'à trouver le délimiteur défini par sep ou une ligne de fin. SKIP_VALUE: si des guillemets non émis sont trouvés dans l’entrée, le contenu analysé pour la valeur donnée est ignoré (jusqu’à ce que le délimiteur suivant soit trouvé) et la valeur définie dans nullValue sera produite à la place. RAISE_ERROR: si des guillemets non émis sont trouvés dans l’entrée, une TextParsingException valeur est levée.

Excel

Les options suivantes s’appliquent lors de la lecture de fichiers Excel.

Clé	Par défaut	Valeurs valides	Description
dataAddress	None	Chaîne de nom de cellule ou de plage de cellules	Plage de cellules à lire dans Excel syntaxe. En cas d’omission, lit toutes les cellules valides de la première feuille. Permet SheetName!C5:H10 de lire une plage à partir d’une feuille nommée, C5:H10 de lire une plage de la première feuille ou SheetName de lire toutes les données d’une feuille spécifique.
headerRows	0	0, 1	Nombre de lignes initiales à utiliser comme en-têtes de nom de colonne. Quand dataAddress elle est spécifiée, cela s’applique dans la plage de cellules. Lorsque 0, les noms de colonnes sont générés automatiquement en tant que _c1, _c2, _c3, etc.
ignoreMissingSheet	false	true, false	Indique s’il faut ignorer en mode silencieux les fichiers qui ne contiennent pas la feuille spécifiée par dataAddress. Lorsque false, une erreur est levée si un fichier est manquant dans la feuille demandée. S’applique uniquement lorsqu’un nom de feuille est spécifié dans dataAddress.
includePhoneticRuns	false	true, false	Indique s’il faut inclure des annotations phonétiques (telles que pinyin ou furigana) concaténées en valeurs de chaîne de cellule lors de la lecture des fichiers XLSX.
operation	readSheet	readSheet, listSheets	Opération à effectuer sur le classeur Excel. readSheet lit les données d’une feuille. listSheets retourne un struct avec des champs sheetIndex: long et sheetName: String pour chaque feuille.
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Chaîne de format d’horodatage	Chaîne de format personnalisée pour les valeurs timestamp-without-timezone stockées sous forme de chaînes dans Excel. Les formats de date personnalisés suivent les formats des modèles Datetime.
dateFormat	yyyy-MM-dd	Chaîne de format de date	Chaîne de format personnalisée pour les valeurs de chaîne lues en tant que Date. Les formats de date personnalisés suivent les formats des modèles Datetime.

JSON

Les options suivantes s’appliquent lors de la lecture de fichiers JSON.

Clé	Par défaut	Valeurs valides	Description
allowBackslashEscapingAnyCharacter	false	true, false	Indique s’il faut autoriser les barres obliques inverses pour placer dans une séquence d'échappement tout caractère qui suit. Si cette option n’est pas activée, seuls les caractères explicitement listés par la spécification JSON peuvent être placés dans une séquence d’échappement.
allowComments	false	true, false	Indique s’il faut autoriser ou non l’utilisation de commentaires de style Java, C et C++ (variétés '/', '*' et '//') dans le contenu analysé.
allowNonNumericNumbers	true	true, false	Indique s’il faut autoriser l'ensemble des jetons non numériques (NaN) comme valeurs légales de nombres flottants.
allowNumericLeadingZeros	false	true, false	Indique s’il faut autoriser les nombres entiers à commencer par des zéros supplémentaires (pouvant être ignorés) (par exemple, 000001).
allowSingleQuotes	true	true, false	Indique s’il faut autoriser l'utilisation de guillemets simples (apostrophe, caractère '\') pour citer des chaînes de caractères (noms et valeurs de chaînes).
allowUnquotedControlChars	false	true, false	Indique s’il faut autoriser les chaînes JSON à contenir des caractères de contrôle sans séquence d’échappement (caractères ASCII dont la valeur est inférieure à 32, y compris les tabulations et sauts de ligne).
allowUnquotedFieldNames	false	true, false	Indique s’il faut autoriser l’utilisation de noms de champs non cités, qui sont autorisés par JavaScript, mais pas par la spécification JSON.
alternateVariantEncoding	None	Z85	Encodage utilisé pour les valeurs Variant dans le JSON source. Définissez la valeur sur laquelle Z85 décoder les valeurs Variant qui ont été encodées en Base85 au lieu de stockées en tant que JSON inline.
badRecordsPath	None	Chaîne de chemin d’accès	Chemin d’accès pour stocker les fichiers contenant des informations sur les enregistrements JSON incorrects. L’utilisation de l’option badRecordsPath dans une source de données basée sur des fichiers présente les limitations suivantes : Il n’est pas transactionnel et peut entraîner des résultats incohérents. Les erreurs temporaires sont traitées comme des échecs.
columnNameOfCorruptRecord	_corrupt_record	Chaîne de nom de colonne	Colonne destinée au stockage des enregistrements malformés et qui ne peuvent pas être analysés. Si l’élément mode de l'analyse est défini comme DROPMALFORMED, cette colonne sera vide.
dateFormat	yyyy-MM-dd	Chaîne de format de date	Format d’analyse des chaînes de date.
dropFieldIfAllNull	false	true, false	Indique s’il faut ignorer les colonnes de toutes les valeurs Null ou des tableaux/structs vides pendant l’inférence de schéma.
encoding ou charset	UTF-8	Nom java.nio.charset.Charset	Nom de l’encodage des fichiers JSON. Consultez java.nio.charset.Charset pour obtenir la liste des options. Vous ne pouvez pas utiliser UTF-16 et UTF-32 lorsque multiline est true.
inferTimestamp	false	true, false	Indique s’il faut essayer de déduire les chaînes timestamp en tant que TimestampType. Lorsque la valeur est définie true, l’inférence de schéma peut prendre beaucoup plus de temps. Vous devez activer cloudFiles.inferColumnTypes pour une utilisation avec Auto Loader (Chargeur automatique).
lineSep	Aucun, qui couvre \r, \r\net \n	Chaîne	Chaîne entre deux enregistrements JSON consécutifs.
locale	US	Identificateur java.util.Locale	Identificateur de paramètres régionaux Java qui affecte la date, l’horodatage et l’analyse décimale par défaut dans le json.
maxNestingDepth	500	Entiers positifs	Profondeur maximale d’imbrication autorisée pour les objets et tableaux JSON. Augmentez cette valeur pour les documents profondément imbriqués.
maxNumLen	1000	Entiers positifs	Longueur maximale des jetons de nombre dans l’entrée JSON. Augmentez cette valeur pour JSON avec des littéraux numériques volumineux.
maxStringLen	illimité	Entiers positifs	Longueur maximale des valeurs de chaîne dans l’entrée JSON. Définissez pour limiter l’utilisation de la mémoire lors de l’analyse de JSON avec des chaînes volumineuses.
mode	PERMISSIVE	PERMISSIVE, , DROPMALFORMEDFAILFAST	Mode de l’analyseur pour la gestion des enregistrements mal formés.
multiLine	false	true, false	Indique si les enregistrements JSON s’étendent sur plusieurs lignes.
prefersDecimal	false	true, false	Tente d'interpréter les chaînes comme DecimalType plutôt que comme type float ou double lorsque cela est possible. Vous devez également utiliser l’inférence de schéma, soit en activant inferSchema ou en utilisant cloudFiles.inferColumnTypes le chargeur automatique.
primitivesAsString	false	true, false	Indique s’il faut déduire les types primitifs comme les nombres et les valeurs booléennes comme StringType.
readerCaseSensitive	true	true, false	Spécifie le comportement de respect de la casse lorsque rescuedDataColumn est activé. Si la valeur est true, sauvez les colonnes de données dont les noms diffèrent par cas du schéma. Lorsque la valeur est false, lisez les données de manière non sensible à la casse. Disponible dans Databricks Runtime 13.3 et versions ultérieures.
rescuedDataColumn	None	Chaîne de nom de colonne	Indique s’il faut collecter toutes les données qui ne peuvent pas être analysées en raison d’une incompatibilité de type de données ou d’une incompatibilité de schéma (y compris la casse de colonne) à une colonne distincte. Cette colonne est incluse par défaut lors de l’utilisation d’Auto Loader. Pour plus de détails, reportez-vous à Qu’est-ce que la colonne des données récupérées ?. COPY INTO (hérité) ne prend pas en charge la colonne de données sauvée, car vous ne pouvez pas définir manuellement le schéma à l’aide de COPY INTO. Databricks recommande d’utiliser le chargeur automatique pour la plupart des scénarios d’ingestion.
singleVariantColumn	None	Chaîne de nom de colonne	Indique s’il faut ingérer l’intégralité du document JSON, analysé dans une seule colonne Variant avec la chaîne spécifiée comme nom de la colonne. Si ce n’est pas le cas, les champs JSON sont ingérés dans leurs propres colonnes.
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Chaîne de format d’horodatage	Format d’analyse des chaînes de timestamp.
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Chaîne de format d’horodatage	Format d’analyse de l’horodatage sans chaînes de fuseau horaire (TimestampNTZType).
timeZone	None	Chaîne java.time.ZoneId	L’élément java.time.ZoneId à utiliser lors de l'analyse des timestamps et des dates.
upgradeExceptionAsBadRecord	false	true, false	Indique s’il faut traiter les exceptions de mise à niveau de type (par exemple, lorsqu’une valeur ne peut pas être étendue au type de colonne déclaré) comme des enregistrements incorrects plutôt que de lever une exception.

Kafka

Pour obtenir la liste complète des options de lecteur Kafka, consultez les options Kafka DataStreamReader. Les options suivantes s’appliquent uniquement aux lectures par lots à l’aide spark.read.format("kafka")de .

Clé	Par défaut	Valeurs valides	Description
endingOffsets	latest	latestou une chaîne de décalage JSON	Où arrêter la lecture. Dans la chaîne JSON, -1 est le dernier décalage. -2, qui est le décalage le plus ancien, n’est pas autorisé comme offset de fin. Voici un exemple de chaîne de décalage JSON : {"topicA":{"0":50,"1":-1}}.
endingOffsetsByTimestamp	None	Chaîne d’horodatage JSON	Décalages de fin par partition spécifiés en millisecondes. Par exemple : {"topicA":{"0":2000,"1":3000}}.
endingTimestamp	None	Entiers positifs ou 0	Horodatage de fin global en millisecondes appliqués à toutes les partitions.

ORC

Les options suivantes s’appliquent lors de la lecture des fichiers ORC.

Clé	Par défaut	Valeurs valides	Description
mergeSchema	false	true, false	Indique s’il faut déduire le schéma entre plusieurs fichiers et fusionner le schéma de chaque fichier.

Parquet

Les options suivantes s’appliquent lors de la lecture de fichiers Parquet.

Clé	Par défaut	Valeurs valides	Description
datetimeRebaseMode	LEGACY	EXCEPTION, , LEGACYCORRECTED	Contrôle le rebasage des valeurs DATE et TIMESTAMP entre les calendriers julien et grégorien proleptique.
int96RebaseMode	LEGACY	EXCEPTION, , LEGACYCORRECTED	Contrôle la relocalisation des valeurs de timestamp INT96 entre les calendriers julien et grégorien proleptique.
mergeSchema	false	true, false	Indique s’il faut déduire le schéma entre plusieurs fichiers et fusionner le schéma de chaque fichier.
readerCaseSensitive	true	true, false	Spécifie le comportement de respect de la casse lorsque rescuedDataColumn est activé. Si la valeur est true, sauvez les colonnes de données dont les noms diffèrent par cas du schéma. Lorsque la valeur est false, lisez les données de manière non sensible à la casse.
rescuedDataColumn	None	Chaîne de nom de colonne	Indique s’il faut collecter, dans une colonne distincte, toutes les données qui ne peuvent pas être analysées en raison d’une incompatibilité de type de données et d’une incompatibilité de schéma (y compris la casse de colonne). Cette colonne est incluse par défaut lors de l’utilisation d’Auto Loader. Pour plus de détails, reportez-vous à Qu’est-ce que la colonne des données récupérées ?. COPY INTO (hérité) ne prend pas en charge la colonne de données sauvée, car vous ne pouvez pas définir manuellement le schéma à l’aide de COPY INTO. Databricks recommande d’utiliser le chargeur automatique pour la plupart des scénarios d’ingestion.

Magasin d’état

Utilisez ces options avec spark.read.format("statestore") ou la read_statestore fonction table pour lire les données d’état structured Streaming. Consultez Lire les informations d’état de Structured Streaming.

Clé	Par défaut	Valeurs valides	Description
batchId	ID de lot le plus récent	Entiers positifs ou 0	Lot cible à partir duquel lire. Permet d’interroger un état antérieur de la requête. Le lot doit être validé, mais pas encore nettoyé.
operatorId	0	Entiers positifs ou 0	Opérateur cible à partir duquel lire. Utilisez quand la requête a plusieurs opérateurs avec état.
storeName	DEFAULT	Toute chaîne de caractères	Nom du magasin d’états cible à partir duquel lire. Utilisez quand l’opérateur avec état a plusieurs instances de magasin d’état. Vous devez spécifier soit storeName pour joinSide une jointure de flux de flux, mais pas pour les deux.
joinSide	None	left, right	Côté cible à lire pour une jointure de flux de flux. Vous devez spécifier soit storeName pour joinSide une jointure de flux de flux, mais pas pour les deux.
snapshotStartBatchId	None	Entiers positifs ou 0	ID de lot de l’instantané à utiliser comme point de départ lors de la lecture de l’état. Le lecteur reconstruit l’état en relectant les modifications de cet instantané jusqu’à batchId. Utile lorsqu’un instantané est endommagé. Doit être spécifié avec snapshotPartitionId. Impossible d’utiliser avec readChangeFeed. Prend en charge le magasin d’état soutenu par HDFS et le magasin d’état RocksDB avec le point de contrôle de journal des modifications activé. Disponible dans Databricks Runtime 15.4 LTS et versions ultérieures.
snapshotPartitionId	None	Entiers positifs ou 0	Si elle est spécifiée, la requête lit uniquement cette partition. Doit être spécifié avec snapshotStartBatchId. Impossible d’utiliser avec readChangeFeed. Disponible dans Databricks Runtime 15.4 LTS et versions ultérieures.
readChangeFeed	false	true, false	Quand true, retourne les modifications d’état sur une plage spécifiée de lots entre changeStartBatchId et changeEndBatchId. Exige changeStartBatchId. Impossible d’utiliser avec joinSide, , batchIdsnapshotStartBatchIdou snapshotPartitionId. Disponible dans Databricks Runtime 16.4 LTS et versions ultérieures. Pour plus d’informations, consultez Lire les modifications de l’état de diffusion en continu structurée.
changeStartBatchId	None	Entiers positifs ou 0	ID de lot de départ de la plage de flux de modification. Obligatoire quand readChangeFeed est true. S’applique uniquement quand readChangeFeed est défini sur true. Disponible dans Databricks Runtime 16.4 LTS et versions ultérieures.
changeEndBatchId	ID de lot le plus récent	Entiers positifs ou 0	ID de lot de fin de la plage de flux de modification. Doit être supérieur ou égal à changeStartBatchId. S’applique uniquement quand readChangeFeed est défini sur true. Disponible dans Databricks Runtime 16.4 LTS et versions ultérieures.
stateVarName	None	Toute chaîne de caractères	Nom de la variable d’état à lire. Le nom de la variable d’état est le nom unique de chaque variable dans la init fonction d’un StatefulProcessor utilisé par l’opérateur transformWithState . Obligatoire lorsque vous utilisez l’opérateur transformWithState . Disponible dans Databricks Runtime 16.4 LTS et versions ultérieures.
readRegisteredTimers	false	true, false	Lorsque true, lit les minuteurs inscrits utilisés par l’opérateur transformWithState . S’applique uniquement à l’opérateur transformWithState . Disponible dans Databricks Runtime 16.4 LTS et versions ultérieures.
flattenCollectionTypes	true	true, false	Lorsque true, aplatit les enregistrements retournés pour les variables d’état de carte et de liste. Quand false, retourne des enregistrements sous forme de sql Array Spark ou Map. S’applique uniquement à l’opérateur transformWithState . Disponible dans Databricks Runtime 16.4 LTS et versions ultérieures.

Texte

Les options suivantes s’appliquent lors de la lecture de fichiers texte.

Clé	Par défaut	Valeurs valides	Description
encoding	UTF-8	Nom java.nio.charset.Charset	Nom de l’encodage du séparateur de ligne de fichier TEXT. Le contenu du fichier n’est pas affecté par cette option et est lu as-is.
lineSep	Aucun, qui couvre \r, \r\n et \n	Chaîne	Chaîne située entre deux enregistrements «TEXT» consécutifs.
wholeText	false	true, false	Indique si un fichier doit être lu en tant qu’enregistrement unique.

XML

Les options suivantes s’appliquent lors de la lecture de fichiers XML.

Clé	Par défaut	Valeurs valides	Description
rowTag	None	Toute chaîne de caractères	La balise de ligne des fichiers XML à traiter comme une ligne. Dans l’exemple XML <book> <page><page>...<book>, la valeur appropriée est page. C'est une option obligatoire.
samplingRatio	1.0	De 0.0 à 1.0.	Définit une fraction de lignes utilisées pour l’inférence de schéma. Les fonctions intégrées XML ignorent cette option.
excludeAttribute	false	true, false	Indique s’il faut exclure des attributs dans les éléments.
mode	None	PERMISSIVE, , DROPMALFORMEDFAILFAST	Mode de traitement des enregistrements endommagés pendant l’analyse. PERMISSIVE : pour les enregistrements endommagés, place la chaîne malformée dans un champ configuré par columnNameOfCorruptRecord et définit les champs malformés sur null. Pour conserver les enregistrements corrompus, vous pouvez définir un champ de type string nommé columnNameOfCorruptRecord dans un schéma défini par l’utilisateur. Si un schéma n’a pas le champ, les enregistrements endommagés sont supprimés pendant l’analyse. Lors de l’inférence d’un schéma, l’analyseur ajoute implicitement un champ columnNameOfCorruptRecord dans un schéma de sortie. DROPMALFORMED : ignore les enregistrements endommagés. Ce mode n’est pas pris en charge pour les fonctions intégrées XML. FAILFAST : lève une exception lorsque l’analyseur rencontre des enregistrements endommagés.
inferSchema	true	true, false	Si true, tente de déduire un type approprié pour chaque colonne DataFrame résultante. Si false, toutes les colonnes résultantes sont de type string. Les fonctions intégrées XML ignorent cette option.
columnNameOfCorruptRecord	spark.sql.columnNameOfCorruptRecord	Chaîne de nom de colonne	Permet de renommer le nouveau champ qui contient une chaîne mal formée créée par PERMISSIVE le mode.
attributePrefix	None	Toute chaîne de caractères	Le préfixe des attributs permettant de les différencier des éléments. Il s’agira du préfixe pour les noms de champs. La valeur par défaut est _. Peut être vide pour lire du code XML, mais pas pour l’écriture. S’applique également aux options XML DataFrameWriter.
valueTag	_VALUE	Toute chaîne de caractères	Balise utilisée pour les données caractères dans les éléments qui ont également des éléments d’attribut(s) ou d’élément(s) enfant(s). L’utilisateur peut spécifier le champ valueTag dans le schéma ou il sera ajouté automatiquement pendant l’inférence du schéma lorsque les données caractères sont présentes dans des éléments avec d’autres éléments ou attributs. S’applique également aux options XML DataFrameWriter.
encoding	UTF-8	Nom java.nio.charset.Charset	Pour la lecture, décode les fichiers XML par le type d’encodage donné. Pour l’écriture, spécifie l’encodage (charset) des fichiers XML enregistrés. Les fonctions intégrées XML ignorent cette option. S’applique également aux options XML DataFrameWriter.
ignoreSurroundingSpaces	true	true, false	Indique si les espaces blancs entourant les valeurs doivent être ignorés. Les caractères constitués uniquement d'espaces blancs sont ignorés.
rowValidationXSDPath	None	Chaîne de chemin d’accès au fichier	Chemin d’accès à un fichier XSD facultatif utilisé pour valider le code XML de chaque ligne individuellement. Les lignes qui ne parviennent pas à valider sont traitées comme des erreurs d’analyse. Le XSD n’affecte pas le schéma, qu’il soit spécifié ou déduit.
ignoreNamespace	false	true, false	Si true, les préfixes des espaces de noms sur les éléments et attributs XML sont ignorés. Les balises <abc:author> et <def:author>, par exemple, sont traitées comme si elles étaient simplement <author>. Les espaces de noms ne peuvent pas être ignorés sur l’élément rowTag, uniquement ses enfants en lecture. L’analyse XML ne prend pas en compte l’espace de noms même si false.
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Chaîne de format d’horodatage	Chaîne de format de timestamp personnalisée qui suit le format du modèle datetime. Cela s’applique au type timestamp. S’applique également aux options XML DataFrameWriter.
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Chaîne de format d’horodatage	Chaîne de format personnalisée pour l’horodatage sans fuseau horaire qui suit le format de modèle datetime. Cela s’applique au type TimestampNTZType. S’applique également aux options XML DataFrameWriter.
dateFormat	yyyy-MM-dd	Chaîne de format de date	Chaîne de format de date personnalisée qui suit le format de modèle date-heure. Cela s’applique au type de date. S’applique également aux options XML DataFrameWriter.
locale	en-US	Balise de langue IETF BCP 47	Définit des paramètres régionaux comme étiquette de langue au format IETF BCP 47. Par exemple, locale est utilisé pour l’analyse des dates et des horodatages.
nullValue	chaîne null	Toute chaîne de caractères	Définit la représentation sous forme de chaîne de caractères d’une valeur nulle. Quand il s’agit de null, l’analyseur n’écrit pas d’attributs et d’éléments pour les champs. S’applique également aux options XML DataFrameWriter.
readerCaseSensitive	true	true, false	Spécifie le comportement de respect de la casse lorsque rescuedDataColumn est activé. Si la valeur est true, sauvez les colonnes de données dont les noms diffèrent par cas du schéma. Lorsque la valeur est false, lisez les données de manière non sensible à la casse.
rescuedDataColumn	None	Chaîne de nom de colonne	Indique s’il faut collecter toutes les données qui ne peuvent pas être analysées en raison d’une incompatibilité de type de données et d’une incompatibilité de schéma (y compris la casse de colonne) à une colonne distincte. Cette colonne est incluse par défaut lors de l’utilisation d’Auto Loader. Pour plus d’informations, consultez Qu’est-ce que la colonne de données récupérées ? COPY INTO (hérité) ne prend pas en charge la colonne de données sauvée, car vous ne pouvez pas définir manuellement le schéma à l’aide de COPY INTO. Databricks recommande d’utiliser le chargeur automatique pour la plupart des scénarios d’ingestion.
singleVariantColumn	none	Chaîne de nom de colonne	Spécifie le nom de la colonne de variante unique. Si cette option est spécifiée pour la lecture, analysez l’intégralité de l’enregistrement XML dans une seule colonne Variant avec la valeur de chaîne d’option donnée comme nom de la colonne. Si cette option est spécifiée pour l’écriture, écrivez la valeur de la colonne Variant unique dans des fichiers XML. S’applique également aux options XML DataFrameWriter.
useLegacyXMLParser	true	true, false	Indique s’il faut utiliser l’analyseur XML hérité. L’analyseur hérité a une validation moins stricte pour le contenu mal formé, mais il est moins efficace en mémoire. Définissez cette option pour false choisir l’analyseur par défaut le plus strict.
wildcardColName	xs_any	Chaîne de nom de colonne	Nom de colonne utilisé pour capturer des éléments XML qui correspondent à l’élément de schéma générique (xs:any). Impossible d’utiliser avec rescuedDataColumn.

Options DataStreamReader

Utilisez ces options pour DataStreamReader.option() configurer les lectures de diffusion en continu à partir de tables Delta Lake et d’autres sources basées sur des fichiers.

Pour connaître les options de format de fichier (JSON, CSV, Parquet et autres), consultez les options DataFrameReader.

Pour connaître les options du chargeur automatique (cloudFiles.*), consultez Le chargeur automatique.

Example

L’exemple suivant définit maxFilesPerTrigger la valeur pour 10 un flux de table Delta Lake :

Python

df = spark.readStream.format("delta").option("maxFilesPerTrigger", 10).load("/path/to/delta-table")

Scala

val df = spark.readStream.format("delta").option("maxFilesPerTrigger", "10").load("/path/to/delta-table")

Commun

Les options suivantes s’appliquent aux tables Delta Lake et à d’autres sources de diffusion en continu basées sur des fichiers.

Clé	Par défaut	Valeurs valides	Description
cleanSource	off	off, , deletearchive	Comment gérer les fichiers sources après leur traitement par le flux. off n’effectue aucune action. delete supprime définitivement le fichier source. archive déplace le fichier vers sourceArchiveDir. Quand la valeur est définie archive, sourceArchiveDir doit également être définie. Ne s’applique pas à la diffusion en continu de table Delta Lake.
fileNameOnly	false	true, false	Indique s’il faut identifier les fichiers déjà traités par nom de fichier uniquement plutôt que par chemin d’accès complet. Lorsque true, les fichiers à différents chemins d’accès avec le même nom de fichier sont traités comme le même fichier et ne sont pas retratés. Ne s’applique pas à la diffusion en continu de table Delta Lake.
latestFirst	false	true, false	Indique s’il faut traiter les fichiers les plus récemment modifiés au sein de chaque micro-lot. Utile lorsque vous souhaitez traiter les données les plus récentes le plus rapidement possible. Quand true et maxFilesPerTrigger ou maxBytesPerTrigger est défini, maxFileAge est ignoré. Ne s’applique pas à la diffusion en continu de table Delta Lake.
maxBytesPerTrigger	None	Entiers positifs	Maximum souple pour la quantité de données traitées pour chaque micro-lot. Un lot peut traiter plus que la limite si la plus petite unité d’entrée la dépasse. Lorsqu’il est utilisé avec maxFilesPerTrigger, le micro-lot traite les données jusqu’à ce que l’une des limites soit atteinte en premier. Pour Chargeur automatique, utilisez cloudFiles.maxBytesPerTrigger à la place. Voir Common.
maxCachedFiles	10000	Entiers positifs ou 0	Nombre maximal de fichiers non traités à mettre en cache pour les micro-lots suivants. Définissez cette option pour 0 désactiver la mise en cache. Augmentez cette valeur lorsque le répertoire source contient de nombreux nouveaux fichiers pour chaque déclencheur. Ne s’applique pas à la diffusion en continu de table Delta Lake.
maxFileAge	7d	Chaîne de durée telle que 7d ou 4h	Âge maximal des fichiers pris en compte pour le traitement, par rapport à l’horodatage du fichier le plus récemment modifié plutôt qu’à l’heure système actuelle. Les fichiers antérieurs à ce seuil sont ignorés. Ignoré quand latestFirsttrue et maxFilesPerTrigger ou maxBytesPerTrigger est défini. Ne s’applique pas à la diffusion en continu de table Delta Lake.
maxFilesPerTrigger	1000 pour Delta Lake et le chargeur automatique. Aucun maximum pour d’autres sources basées sur des fichiers.	Entiers positifs	Limite supérieure pour le nombre de nouveaux fichiers traités dans chaque micro-lot. Lorsqu’il est utilisé avec maxBytesPerTrigger, le micro-lot traite les données jusqu’à ce que l’une des limites soit atteinte en premier. Pour Chargeur automatique, utilisez cloudFiles.maxFilesPerTrigger à la place. Voir Common.
sourceArchiveDir	None	Chaîne de chemin d’accès	Chemin d’accès au répertoire d’archivage quand cleanSource il est défini sur archive. Les fichiers sources sont déplacés vers ce chemin après le traitement, en conservant leur structure de répertoires relative. Ne s’applique pas à la diffusion en continu de table Delta Lake.

Chargeur automatique

Utilisez ces options avec la cloudFiles source pour configurer le chargeur automatique pour l’ingestion de streaming à partir du stockage cloud. Les options spécifiques à la cloudFiles source sont préfixées cloudFiles pour les conserver dans un espace de noms distinct des autres options de source Structured Streaming .

Commun

Les options suivantes s’appliquent à toutes les configurations du chargeur automatique.

Clé	Par défaut	Valeurs valides	Description
cloudFiles.allowOverwrites	false	true, false	Indique s’il faut autoriser les modifications des fichiers du répertoire d’entrée à remplacer les données existantes. Pour connaître les mises en garde de configuration, consultez Le chargeur automatique traite-t-il à nouveau le fichier lorsque le fichier est ajouté ou remplacé ?.
cloudFiles.backfillInterval	None	Chaîne de durée telle que 1 day ou 1 week	Le chargeur automatique peut déclencher des remplissages asynchrones à un intervalle donné. Pour plus d’informations, consultez Déclencher des remplissages réguliers à l’aide de cloudFiles.backfillInterval. N’utilisez pas quand cloudFiles.useManagedFileEvents est défini sur true.
cloudFiles.cleanSource	OFF	OFF, , DELETEMOVE	Indique s’il faut supprimer ou déplacer automatiquement des fichiers traités à partir du répertoire d’entrée. Lorsqu’il OFF est défini sur (valeur par défaut), aucun fichier n’est supprimé. Lorsqu’il est défini DELETEsur , le chargeur automatique supprime automatiquement les fichiers 30 jours après leur traitement. Pour ce faire, le chargeur automatique doit disposer d’autorisations d’écriture dans le répertoire source. Lorsqu’il est défini sur MOVE, le Chargeur automatique déplace automatiquement les fichiers vers l’emplacement spécifié dans cloudFiles.cleanSource.moveDestination 30 jours après leur traitement. Pour ce faire, le chargeur automatique doit disposer d’autorisations d’écriture dans le répertoire source et de l’emplacement de déplacement. Un fichier est considéré comme traité lorsqu’il a une valeur non Null dans commit_time le résultat de la cloud_files_state fonction table. Consultez cloud_files_stateTVF. L’attente supplémentaire de 30 jours après le traitement peut être configurée à l’aide cloudFiles.cleanSource.retentionDurationde . Passez en revue les considérations suivantes avant d’activer cloudFiles.cleanSource: Azure Databricks ne recommande pas d’utiliser cette option s’il existe plusieurs flux consommant des données à partir de l’emplacement source, car le consommateur le plus rapide supprime les fichiers et ne sera pas ingéré dans les sources plus lentes. L’activation de cette fonctionnalité nécessite que le chargeur automatique conserve un état supplémentaire dans son point de contrôle, ce qui entraîne une surcharge de performances, mais permet une observabilité améliorée par le biais de la cloud_files_state fonction table. Consultez cloud_files_stateTVF. cleanSourceutilise le paramètre actuel pour décider s’il s’agit ou MOVE non d’un DELETE fichier donné. Par exemple, supposons que le paramètre était MOVE lorsque le fichier a été traité à l’origine, mais qu’il a été modifié DELETE lorsque le fichier est devenu candidat pour le nettoyage 30 jours plus tard. Dans ce cas, cleanSource supprime le fichier. Les fichiers ne sont pas assurés d’être nettoyés dès l’expiration retentionDuration . Pour réduire les coûts, le chargeur automatique supprime les fichiers simultanément avec le traitement de flux et se termine dès que le traitement du flux est terminé ou terminé. Les fichiers qui étaient candidats au nettoyage, mais qui n’ont pas pu être nettoyés pendant le traitement du flux seront récupérés la prochaine fois que le chargeur automatique s’exécute. Disponible dans Databricks Runtime 16.4 et versions ultérieures.
cloudFiles.cleanSource.retentionDuration	30 days	Chaîne CalendarInterval telle que 14 days, 2 weeksou 1 month	Durée d’attente avant que les fichiers traités ne deviennent candidats à l’archivage avec cleanSource. Doit être supérieur à 7 jours pour DELETE. Aucune restriction minimale pour MOVE. Disponible dans Databricks Runtime 16.4 et versions ultérieures.
cloudFiles.cleanSource.moveDestination	None	Un chemin de volume de stockage cloud ou de catalogue Unity	Chemin d’accès pour archiver des fichiers traités lorsque cloudFiles.cleanSource est défini sur MOVE. Il peut s’agir d’un chemin de stockage cloud ou d’un chemin de volume du catalogue Unity (par exemple). /Volumes/my_catalog/my_schema/my_volume/archive/ L’emplacement de déplacement doit : Ne pas être un enfant du répertoire source. Si vous placez la destination de déplacement dans le répertoire source, les fichiers archivés sont ingérés à nouveau. Être dans le même emplacement externe, volume ou montage DBFS que la source. Les déplacements entre compartiments et entre conteneurs ne sont pas pris en charge et entraînent une erreur. Le chargeur automatique doit disposer d’autorisations d’écriture dans ce répertoire. Disponible dans Databricks Runtime 16.4 et versions ultérieures.
cloudFiles.format	Aucun (option requise)	avro, binaryFile, , csvjson, orc, parquet, , text,xml	Le format du fichier de données dans le chemin source. Les valeurs valides sont les suivantes : avro : Fichiers Avro binaryFile: fichiers binaires csv: fichiers CSV json: fichiers JSON orc: fichiers ORC parquet : Fichiers Parquet text: fichiers TXT xml: fichiers XML
cloudFiles.includeExistingFiles	true	true, false	Indique si les fichiers existants doivent être inclus dans le chemin d’entrée du traitement du flux ou si seuls les nouveaux fichiers arrivant après la configuration initiale doivent être traités. Cette option est évaluée uniquement lorsque vous démarrez un flux pour la première fois. La modification de cette option après le redémarrage du flux n’a aucun effet.
cloudFiles.inferColumnTypes	false	true, false	Indique s’il faut déduire les types de colonnes exacts lors de l’utilisation de l’inférence de schéma. Par défaut, les colonnes sont déduites sous forme de chaînes lors de l’inférence de jeux de données JSON et CSV. Pour plus d’informations, consultez Inférence de schéma.
cloudFiles.maxBytesPerTrigger	None	Chaîne d’octets telle que 10g	Nombre maximal de nouveaux octets à traiter dans chaque déclencheur. Il s’agit d’une valeur maximale non stricte. Si vous avez des fichiers de 3 Go chacun, Azure Databricks traite 12 Go dans un micro-lot. Un fichier individuel n’est jamais divisé en micro-lots ; il est toujours traité en intégralité dans un seul, même lorsque sa taille dépasse cette limite. En cas d’utilisation avec cloudFiles.maxFilesPerTrigger, Azure Databricks consomme jusqu’à la limite inférieure de cloudFiles.maxFilesPerTrigger ou cloudFiles.maxBytesPerTrigger, selon celle qui est atteinte en premier. Cette option n’a pas d’effet quand elle est utilisée avec Trigger.Once() (Trigger.Once() est déprécié). Dans Databricks Runtime 18.0 et versions ultérieures, cette option est configurée dynamiquement et n’a pas besoin d’être définie manuellement.
cloudFiles.maxFileAge	None	Chaîne de durée	Durée de suivi d’un événement de fichier à des fins de déduplication. Databricks ne recommande pas de régler ce paramètre, sauf si vous ingérez des données de l’ordre de millions de fichiers par heure. Pour plus d’informations, consultez la section sur le suivi des événements file . Un réglage cloudFiles.maxFileAge trop agressif peut entraîner des problèmes de qualité des données, notamment l'ingestion des données en double ou des fichiers manquants. Par conséquent, Databricks recommande un paramètre conservateur pour cloudFiles.maxFileAge, 90 jours, par exemple. Cette durée est similaire à ce que les solutions d'ingestion de données comparables recommandent.
cloudFiles.maxFilesPerTrigger	1000	Entiers positifs	Nombre maximal de nouveaux fichiers à traiter dans chaque déclencheur. En cas d’utilisation avec cloudFiles.maxBytesPerTrigger, Azure Databricks consomme jusqu’à la limite inférieure de cloudFiles.maxFilesPerTrigger ou cloudFiles.maxBytesPerTrigger, selon celle qui est atteinte en premier. Cette option n’a aucun effet lorsqu’elle est utilisée avec Trigger.Once() (déprécié). Dans Databricks Runtime 18.0 et versions ultérieures, cette option est configurée dynamiquement et n’a pas besoin d’être définie manuellement.
cloudFiles.partitionColumns	None	Liste séparée par des virgules de noms de colonnes	Liste séparée par des virgules de colonnes de partition de style Hive que vous souhaitez déduire de la structure de répertoires des fichiers. Les colonnes de partition de style Hive sont des paires clé-valeur combinées par un signe d’égalité tel que <base-path>/a=x/b=1/c=y/file.format. Dans cet exemple, les colonnes de partition sont a, b et c. Par défaut, ces colonnes sont automatiquement ajoutées à votre schéma si vous utilisez l’inférence de schéma et spécifiez les données à partir de laquelle charger des <base-path> données. Si vous spécifiez un schéma, le chargeur automatique s’attend à ce que ces colonnes soient incluses dans le schéma. Si vous ne voulez pas que ces colonnes fassent partie de votre schéma, vous pouvez spécifier "" pour ignorer ces colonnes. En outre, vous pouvez utiliser cette option lorsque vous souhaitez que les colonnes soient déduites du chemin d’accès au fichier dans les structures de répertoire complexes, comme dans l’exemple ci-dessous : <base-path>/year=2022/week=1/file1.csv <base-path>/year=2022/month=2/day=3/file2.csv <base-path>/year=2022/month=2/day=4/file3.csv Spécifier cloudFiles.partitionColumns comme year,month,day retourne year=2022 pour file1.csv, mais les colonnes month et day sont null. month et day sont analysés correctement pour file2.csv et file3.csv.
cloudFiles.schemaEvolutionMode	addNewColumns lorsqu’un schéma n’est pas spécifié, none sinon	addNewColumns, , nonerescue, ,failOnNewColumns	Mode d’évolution du schéma à mesure que de nouvelles colonnes sont découvertes dans les données. Par défaut, les colonnes sont déduites sous forme de chaînes lors de l’inférence de jeux de données JSON. Pour plus d’informations, consultez Évolution de schéma.
cloudFiles.schemaHints	None	Chaîne de schéma	Informations de schéma que vous spécifiez sur Le chargeur automatique pendant l’inférence du schéma. Pour plus d’informations, consultez les conseils de schéma.
cloudFiles.schemaLocation	Aucun (requis pour déduire le schéma)	Chaîne de chemin d’accès	Emplacement dans lequel stocker le schéma inféré et les modifications ultérieures. Pour plus d’informations, consultez Inférence de schéma.
cloudFiles.useStrictGlobber	false	true, false	Indique s’il faut utiliser un globber strict correspondant au comportement de globbing par défaut d’autres sources de fichiers dans Apache Spark. Pour plus d’informations, consultez Modèles de chargement de données courants. Disponible dans Databricks Runtime 12.2 LTS et versions ultérieures.
cloudFiles.validateOptions	true	true, false	Indique s’il faut valider les options d’Auto Loader et renvoyer une erreur pour les options inconnues ou incohérentes.

Liste d’annuaires

L’option suivante s’applique lors de l’utilisation du mode liste d’annuaires.

Clé	Par défaut	Valeurs valides	Description
cloudFiles.useIncrementalListing (déconseillé)	auto sur Databricks Runtime 17.2 et versions ultérieures, false sur Databricks Runtime 17.3 et versions ultérieures	auto, , truefalse	Cette fonctionnalité est déconseillée. Databricks recommande d’utiliser le mode de notification de fichier avec des événements de fichier au lieu de cloudFiles.useIncrementalListing. Indique s’il faut utiliser la liste incrémentielle plutôt que la liste complète en mode Liste de répertoires. Par défaut, Auto Loader fait de son mieux pour détecter automatiquement si un répertoire donné s’applique à la liste incrémentielle. Vous pouvez utiliser explicitement la liste incrémentielle ou la liste de répertoires complète en la définissant respectivement sur true ou false. L’activation incorrecte de la liste incrémentielle sur un répertoire non lexical empêche le chargeur automatique de découvrir de nouveaux fichiers. Fonctionne avec Azure Data Lake Storage (abfss://), S3 (s3://) et GCS (gs://). Disponible dans Databricks Runtime 9.1 LTS et ultérieur.

Notification de fichier

Pour plus d’informations sur la configuration du mode de notification de fichier, notamment les autorisations cloud requises, les instructions d’installation et les méthodes d’authentification, consultez Configurer des flux de chargeur automatique en mode de notification de fichier.

Clé	Par défaut	Valeurs valides	Description
cloudFiles.fetchParallelism	1	Entiers positifs	Nombre de threads à utiliser pour récupérer les messages du service de file d'attente. N’utilisez pas quand cloudFiles.useManagedFileEvents est défini sur true.
cloudFiles.pathRewrites	None	Chaîne de carte JSON	Obligatoire uniquement si vous spécifiez un queueUrl fichier qui reçoit des notifications de fichiers à partir de plusieurs compartiments S3 et que vous souhaitez utiliser des points de montage configurés pour accéder aux données dans ces conteneurs. Utilisez cette option pour réécrire le préfixe du chemin d’accès bucket/key avec le point de montage. Seuls les préfixes peuvent être réécrits. Par exemple, pour la configuration {"<databricks-mounted-bucket>/path": "dbfs:/mnt/data-warehouse"}, le chemin d’accès s3://<databricks-mounted-bucket>/path/2017/08/fileA.json est réécrit en dbfs:/mnt/data-warehouse/2017/08/fileA.json. N’utilisez pas quand cloudFiles.useManagedFileEvents est défini sur true.
cloudFiles.resourceTag	None	Chaînes d’étiquettes clé-valeur	Série de paires de balises clé-valeur pour aider à associer et à identifier les ressources liées, par exemple : cloudFiles.option("cloudFiles.resourceTag.myFirstKey", "myFirstValue") .option("cloudFiles.resourceTag.mySecondKey", "mySecondValue") N’utilisez pas quand cloudFiles.useManagedFileEvents est défini sur true. Définissez plutôt des balises de ressource à l’aide de la console du fournisseur de cloud. Pour plus d’informations, consultez balises de ressources du fournisseur de cloud.
cloudFiles.useManagedFileEvents	false	true, false	Lorsque la valeur est définie true, le chargeur automatique utilise le service d’événements de fichiers pour découvrir les fichiers dans votre emplacement externe. Vous ne pouvez utiliser cette option que si le chemin de chargement se trouve dans un emplacement externe avec les événements de fichier activés. Consultez Utiliser le mode de notification de fichier avec les événements de fichier. Les événements de fichier fournissent des performances au niveau des notifications dans la découverte de fichiers, car le chargeur automatique peut découvrir de nouveaux fichiers après la dernière exécution. Contrairement à la liste des répertoires, ce processus n’a pas besoin de répertorier tous les fichiers du répertoire. Dans certains cas, le chargeur automatique utilise la liste de répertoires même si l’option événements de fichier est activée : Lors du chargement initial, lorsqu’includeExistingFiles est défini sur true, un listing complet du répertoire a lieu pour découvrir tous les fichiers présents dans le répertoire avant le démarrage du Chargeur Automatique. Le service d’événements de fichiers optimise la découverte de fichiers en mettant en cache les fichiers les plus récemment créés. Si le chargeur automatique s’exécute rarement, ce cache peut expirer et le chargeur automatique revient à la liste des répertoires pour découvrir les fichiers et mettre à jour le cache. Pour éviter ce scénario, appelez le chargeur automatique au moins une fois tous les sept jours. Voir Quand le chargeur automatique avec des événements de fichier utilise-t-il la liste des répertoires ? pour obtenir une liste complète des situations où le chargeur automatique utilise la liste de répertoires avec cette option. Disponible dans Databricks Runtime 14.3 LTS et versions ultérieures.
cloudFiles.listOnStart	false	true, false	Lorsqu’il est défini truesur , le chargeur automatique effectue une liste complète de répertoires au démarrage du flux, au lieu de commencer par le jeton de continuation dans le point de contrôle. Utilisez cette option pour récupérer des erreurs, telles que CF_MANAGED_FILE_EVENTS_INVALID_CONTINUATION_TOKEN. Voir Comment récupérer à partir d’une CF_MANAGED_FILE_EVENTS_INVALID_CONTINUATION_TOKEN erreur ?.
cloudFiles.useNotifications	false	true, false	Indique s’il faut utiliser le mode Notification de fichiers pour déterminer l’existence de nouveaux fichiers. Si false, utilisez le mode Liste de répertoires. Consultez Comparer les modes de détection de fichiers Auto Loader. N’utilisez pas quand cloudFiles.useManagedFileEvents est défini sur true.

Balises de ressources du fournisseur de cloud

Le chargeur automatique ajoute les paires d’étiquettes clé-valeur suivantes par défaut sur une base optimale :

• vendor : Databricks
• path : emplacement à partir duquel les données sont chargées. Non disponible dans GCP en raison de limitations des libellés.
• checkpointLocation: emplacement du point de contrôle du flux. Non disponible dans GCP en raison de limitations des libellés.
• streamId : Identificateur unique au niveau mondial pour le flux.

Databricks réserve ces noms de clés et vous ne pouvez pas remplacer leurs valeurs.

Pour plus d’informations sur Azure, consultez Affectation de noms pour les files d’attente et les métadonnées et la couverture de properties.labels dans Abonnements aux événements. Auto Loader stocke ces paires de balises clé-valeur au format JSON en tant qu’étiquettes.

Spécifique au cloud

Le chargeur automatique a des options pour configurer l’infrastructure cloud pour le mode de notification de fichier. Pour obtenir les autorisations cloud requises et les instructions de configuration, consultez Configurer des flux de chargeur automatique en mode de notification de fichier.

Azure

Vous devez spécifier des valeurs pour toutes les options suivantes si vous spécifiez cloudFiles.useNotifications = true et que vous souhaitez que le chargeur automatique configure les services de notification pour vous :

Clé	Par défaut	Valeurs valides	Description
cloudFiles.resourceGroup	None	Toute chaîne de caractères	Groupe de ressources Azure dans lequel le compte de stockage est créé.
cloudFiles.subscriptionId	None	Toute chaîne de caractères	ID d’abonnement Azure dans lequel le groupe de ressources est créé.
databricks.serviceCredential	None	Toute chaîne de caractères	Nom de votre identifiant de service Databricks. Disponible dans Databricks Runtime 16.1 et versions ultérieures.

Si les informations d’identification d’un service Databricks ne sont pas disponibles, vous pouvez spécifier les options d’authentification suivantes à la place :

Clé	Par défaut	Valeurs valides	Description
cloudFiles.clientId	None	Toute chaîne de caractères	ID client ou ID d’application du principal de service.
cloudFiles.clientSecret	None	Toute chaîne de caractères	Secret client du principal de service.
cloudFiles.connectionString	None	Une chaîne de connexion	Chaîne de connexion pour le compte de stockage, basée sur la clé d’accès du compte ou la signature d’accès partagé (SAS).
cloudFiles.tenantId	None	Toute chaîne de caractères	ID de locataire Azure dans lequel le principal de service est créé.

Spécifiez l’option suivante uniquement si vous définissez cloudFiles.useNotifications = true et que vous souhaitez que le chargeur automatique utilise une file d’attente existante :

Clé	Par défaut	Valeurs valides	Description
cloudFiles.queueName	None	Toute chaîne de caractères	Nom de la file d’attente Azure. Si elle est spécifiée, la source de fichiers cloud consomme directement les événements de cette file d’attente au lieu de configurer ses propres Azure Event Grid et services de stockage de file d’attente. Dans ce cas, votre databricks.serviceCredential ou cloudFiles.connectionString nécessite uniquement des autorisations de lecture sur la file d’attente.

Delta Lake

Les options suivantes s’appliquent lors de la lecture à partir d’une table Delta Lake à l’aide spark.readStreamde .

Clé	Par défaut	Valeurs valides	Description
allowSourceColumnDrop	None	Numéro de version ou always	Définissez sur un numéro de version de table Delta ou always pour autoriser le flux à continuer une fois que les colonnes sont supprimées du schéma de la table source. Lorsqu’il est défini sur un numéro de version, reconnaît toutes les modifications de schéma jusqu’à cette version. Exige schemaTrackingLocation. Voir Renommer et supprimer des colonnes avec le mappage de colonnes Delta Lake.
allowSourceColumnRename	None	Numéro de version ou always	Définissez sur un numéro de version de table Delta ou always pour autoriser le flux à continuer une fois que les colonnes sont renommées dans la table source. Lorsqu’il est défini sur un numéro de version, reconnaît toutes les modifications de schéma jusqu’à cette version. Exige schemaTrackingLocation. Voir Renommer et supprimer des colonnes avec le mappage de colonnes Delta Lake.
allowSourceColumnTypeChange	None	Numéro de version ou always	Définissez sur un numéro de version de table Delta ou always pour autoriser le flux à continuer une fois que les types de colonnes sont modifiés dans la table source. Lorsqu’il est défini sur un numéro de version, reconnaît toutes les modifications de schéma jusqu’à cette version. Exige schemaTrackingLocation. Voir Élargissement du type.
excludeRegex	None	Chaîne d’expression régulière Java	Modèle d’expression régulière. Les fichiers dont les chemins correspondent au modèle sont exclus de la lecture en continu. Utile pour filtrer les fichiers qui ne sont pas conformes à la convention d’affectation de noms attendue.
failOnDataLoss	true	true, false	Indique s’il faut échouer à la requête de diffusion en continu si les données sources ont été supprimées en raison de la rétention du journal (logRetentionDuration). Définissez cette option pour false ignorer les données manquantes et poursuivre le traitement. Voir Configurer la conservation des données pour des requêtes de voyage dans le temps.
ignoreChanges (déconseillé)	false	true, false	Disponible dans Databricks Runtime 11.3 LTS et versions antérieures. Émet à nouveau des fichiers de données réécrits après des opérations de modification telles que UPDATE, , MERGE INTO, DELETEou OVERWRITE. Les lignes inchangées peuvent être émises avec de nouvelles lignes, de sorte que les consommateurs en aval doivent gérer les doublons. Les suppressions ne sont pas propagées en aval. Remplacé par skipChangeCommits Databricks Runtime 12.2 LTS et versions ultérieures.
ignoreDeletes (déconseillé)	false	true, false	Ignore les transactions qui suppriment des données aux limites de partition (la partition complète supprime uniquement). Ne gère pas les suppressions non partitionnelles, les mises à jour ou d’autres modifications. Utilisez skipChangeCommits à la place.
readChangeFeed ou readChangeData	false	true, false	Indique s’il faut activer la lecture du flux de données modifiées pour la requête de diffusion en continu. Lorsqu’il est activé, le flux émet des modifications au niveau des lignes (insertions, mises à jour et suppressions) avec des colonnes de métadonnées supplémentaires. Consultez Utiliser le flux de données modifiées sur Azure Databricks.
schemaTrackingLocation	None	Chaîne de chemin d’accès	Chemin d’accès à un répertoire dans lequel Delta Lake effectue le suivi des modifications de schéma pour la lecture en continu. Obligatoire lors de la diffusion en continu à partir de tables avec le mappage de colonnes activé et en utilisant allowSourceColumn* des options pour gérer l’évolution du schéma. Doit se trouver dans la checkpointLocation requête de diffusion en continu. Voir Renommer et supprimer des colonnes avec le mappage de colonnes Delta Lake.
skipChangeCommits	false	true, false	Ignore les transactions qui suppriment ou modifient les enregistrements existants et traitent uniquement les ajouts. Databricks recommande cette option pour la plupart des charges de travail qui n’utilisent pas de flux de données modifiées. Disponible dans Databricks Runtime 12.2 LTS et versions ultérieures. Consultez Ignorer les validations de modification en amont avec skipChangeCommits.
startingTimestamp	Dernière version disponible	Chaîne d’horodatage telle qu’une 2019-01-01T00:00:00.000Z chaîne de date telle que 2019-01-01	Horodatage à partir duquel commencer la lecture. Le flux lit toutes les modifications de table validées au ou après l’horodatage spécifié. Si l’horodatage précède toutes les validations de table disponibles, le flux commence à partir de la validation la plus ancienne disponible. Impossible d’utiliser avec startingVersion. Ignoré si le point de contrôle de streaming existe déjà.
startingVersion	Dernière version disponible	Entier positif, 0ou latest	Version de la table Delta à partir de laquelle commencer la lecture. Le flux lit toutes les modifications validées à ou après la version spécifiée. Spécifiez latest de commencer uniquement à partir des modifications les plus récentes. Impossible d’utiliser avec startingTimestamp. Ignoré si le point de contrôle de streaming existe déjà. Voir Utiliser l’historique des tables.
withEventTimeOrder	false	true, false	Divise l’instantané de la table initiale en compartiments de temps d’événement pour empêcher les enregistrements d’être marqués de manière incorrecte comme des événements tardifs et supprimés dans des requêtes avec des filigranes avec état. Impossible de modifier une fois que le traitement initial des instantanés a commencé sans supprimer le point de contrôle. Disponible dans Databricks Runtime 11.3 LTS et versions ultérieures. Consultez l’instantané initial du processus sans supprimer de données.

Kafka

Utilisez ces options avec l’une ou l’autre spark.readStream.format("kafka") des options spark.read.format("kafka")suivantes :

Clé	Par défaut	Valeurs valides	Description
assign	None	Chaîne JSON telle que {"topicA":[0,1],"topicB":[2,4]}	Partitions spécifiques à consommer. Vous devez spécifier exactement l’une des options ou subscribesubscribePattern l’une assigndes options.
failOnDataLoss	true	true, false	Indique si la requête échoue si des données peuvent avoir été perdues, par exemple en raison de rubriques supprimées ou de troncation de décalage. Définissez cette option pour false ignorer les données manquantes et continuer. Databricks estime de façon prudente si les données ont pu être perdues. Toutefois, cela peut entraîner de fausses alarmes.
fetchoffset.numretries	3	Entiers positifs ou 0	Nombre de nouvelles tentatives lors de l’extraction des décalages Kafka échoue.
fetchoffset.retryintervalms	1000	Entiers positifs ou 0	Intervalle en millisecondes entre les nouvelles tentatives de récupération de décalage.
groupIdPrefix	spark-kafka-source (streaming), spark-kafka-relation (lot)	Toute chaîne de caractères	Préfixe personnalisé à utiliser pour l’ID de groupe de consommateurs Kafka généré automatiquement. Si kafka.group.id elle est définie explicitement, le connecteur ignore cette option.
kafka.group.id	None	Toute chaîne de caractères	ID de groupe de consommateurs Kafka à utiliser lors de la lecture. Utilisez la prudence : les requêtes partageant le même ID de groupe interfèrent entre elles et peuvent lire uniquement des données partielles. Cela peut se produire lors de l’exécution simultanée de charges de travail de traitement par lots et de diffusion en continu, ou lors du redémarrage rapide des requêtes. Si groupIdPrefix est défini, il est ignoré. Pour réduire les problèmes, définissez la configuration session.timeout.ms du consommateur Kafka sur une petite valeur.
includeHeaders	false	true, false	Indique s’il faut inclure des en-têtes de message Kafka en tant que colonne dans la sortie.
kafkaconsumer.polltimeoutms	None	Entiers positifs	Délai d’expiration en millisecondes pour l’appel consommateur poll() Kafka.
kafka.bootstrap.servers	None	Liste séparée par des virgules de host:port chaînes	Liste séparée par des virgules des adresses host :port pour les répartiteurs Kafka. Définit la propriété du bootstrap.servers client Kafka. Si vous constatez qu’il n’existe aucune donnée de Kafka, vérifiez que cette liste d’adresses broker contient des adresses incorrectes. Si la liste d’adresses du répartiteur est incorrecte, il se peut qu’il n’y ait aucune erreur. Les clients Kafka supposent que les répartiteurs seront disponibles et réessayent à jamais lorsqu’ils reçoivent des erreurs réseau.
maxRecordsPerPartition	None	Entiers positifs	Nombre maximal d’enregistrements pour chaque partition Spark. Quand il est défini, le connecteur fractionne les partitions Kafka afin que chaque partition Spark lise au maximum ces nombreux enregistrements. Vous pouvez également utiliser cette option avec minPartitions. Lorsque les deux options sont définies, Spark utilise l’option qui entraîne davantage de partitions.
minPartitions	None	Entiers positifs	Nombre minimal de partitions Spark à lire à partir de Kafka. Quand il est défini, le connecteur fractionne les partitions Kafka volumineuses pour augmenter le parallélisme. Lorsqu’il n’est pas défini, Spark crée une partition pour chaque partition de rubriques Kafka. Utile pour la gestion de l’asymétrie des données ou des pics de charge. Cette option réinitialise les consommateurs Kafka pour chaque déclencheur, ce qui peut affecter les performances avec SSL.
startingOffsets	latest (streaming), earliest (lot)	earliest, latestou une chaîne de décalage JSON	Décalage à partir duquel la requête commence la lecture. Dans la chaîne JSON, -1 est le dernier décalage. -2 est le décalage le plus ancien. Par exemple : {"topicA":{"0":23,"1":-2}}. Pour les requêtes de diffusion en continu, cette option s’applique uniquement lorsqu’une nouvelle requête démarre. Les requêtes reprise utilisent toujours le point de contrôle. Pendant une requête, de nouvelles partitions commencent à lire au plus tôt le décalage. Pour les requêtes par lots, latest n’est pas autorisé.
startingOffsetsByTimestamp	None	Chaîne d’horodatage JSON telle que {"topicA":{"0":1000,"1":2000}}	Liste des décalages de démarrage pour chaque partition, spécifiée sous forme d’horodatages en millisecondes. Lorsqu’aucun décalage n’existe pour un horodatage, le comportement de la requête est déterminé par startingOffsetsByTimestampStrategy. Pour les requêtes de diffusion en continu, cette option s’applique uniquement lorsqu’une nouvelle requête démarre. Les requêtes reprise utilisent toujours le point de contrôle. Pendant une requête, de nouvelles partitions commencent à lire au plus tôt le décalage.
startingOffsetsByTimestampStrategy	error	error, latest	Stratégie à utiliser lorsqu’aucun décalage n’est trouvé pour un horodatage spécifié dans startingOffsetsByTimestamp ou startingTimestamp. error déclenche une exception. latest utilise le décalage disponible le plus récent.
startingTimestamp	None	Entiers positifs ou 0	Horodatage de départ global en millisecondes qui s’applique à toutes les partitions. Lorsqu’aucun décalage n’existe pour l’horodatage, le comportement est contrôlé par startingOffsetsByTimestampStrategy.
subscribe	None	Liste séparée par des virgules des noms de rubriques	Rubriques auxquelles s’abonner. Vous devez spécifier exactement l’une des options ou subscribesubscribePattern l’une assigndes options.
subscribePattern	None	Chaîne d’expression régulière Java	Modèle utilisé pour s’abonner aux rubriques. Vous devez spécifier exactement l’une des options ou subscribesubscribePattern l’une assigndes options. Par exemple : topic.*.

Les options suivantes s’appliquent uniquement aux lectures de diffusion en continu avec spark.readStream.format("kafka"):

Clé	Par défaut	Valeurs valides	Description
bytesEstimateWindowLength	300s	Chaînes de durée telles que 10m ou 600s	Fenêtre de temps utilisée pour estimer les octets restants pour la estimatedTotalBytesBehindLatest métrique. Consultez Récupérer les métriques Kafka.
maxOffsetsPerTrigger	None	Entiers positifs	Nombre maximal de décalages à traiter par intervalle de déclencheur. Les décalages sont distribués proportionnellement entre les partitions de rubrique.
maxTriggerDelay	15m	Chaînes de durée telles que 10m ou 600s	Délai maximal d’attente minOffsetsPerTrigger avant le déclenchement.
minOffsetsPerTrigger	None	Entiers positifs	Nombre minimal de décalages à accumuler avant de déclencher un micro-lot. Quand maxTriggerDelay elle est atteinte, le micro-lot s’exécute indépendamment.

Pour les options de décalage qui s’appliquent uniquement aux lectures par lots avec spark.read.format("kafka"), consultez les options Kafka DataFrameReader.

Authentification

Databricks recommande d’utiliser des informations d’identification de service Unity Catalog pour s’authentifier auprès des services Kafka gérés par le cloud (AWS MSK, Azure Event Hubs ou Google Cloud Managed Kafka).

Clé	Par défaut	Valeurs valides	Description
databricks.serviceCredential	None	Toute chaîne de caractères	Nom d’un service catalogue Unity pour l’authentification auprès des services Kafka gérés par le cloud. Disponible dans Databricks Runtime 16.1 et versions ultérieures.
databricks.serviceCredential.scope	None	Toute chaîne de caractères	Étendue OAuth pour les informations d’identification du service. Définissez cette option uniquement lorsque Azure Databricks ne peut pas déduire automatiquement l’étendue de votre service Kafka.

Lorsqu’aucune information d’identification de service n’est disponible, utilisez les options SASL/SSL (transmises en tant que kafka.* propriétés). Lorsque vous utilisez des informations d’identification de service, vous n’avez pas besoin de spécifier kafka.sasl.mechanism, kafka.sasl.jaas.configou kafka.security.protocol.

Clé	Par défaut	Valeurs valides	Description
kafka.security.protocol	None	Chaîne de protocole de sécurité, telle que SASL_SSL, SSLPLAINTEXT	Protocole de sécurité pour la communication broker.
kafka.sasl.mechanism	None	Chaîne de mécanisme SASL, telle que PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, OAUTHBEARERAWS_MSK_IAM	Mécanisme SASL.
kafka.sasl.jaas.config	None	Chaîne de configuration JAAS	Chaîne de configuration de connexion JAAS.
kafka.sasl.login.callback.handler.class	None	Nom de classe complet	Nom de classe complet d’un gestionnaire de rappel de connexion pour l’authentification SASL.
kafka.sasl.client.callback.handler.class	None	Nom de classe complet	Nom de classe complet d’un gestionnaire de rappel client pour l’authentification SASL.
kafka.ssl.truststore.location	None	Chaîne de chemin d’accès au fichier	Chemin d’accès au fichier de magasin d’approbation SSL.
kafka.ssl.truststore.password	None	Toute chaîne de caractères	Mot de passe du fichier de magasin d’approbation SSL.
kafka.ssl.keystore.location	None	Chaîne de chemin d’accès au fichier	Chemin d’accès au fichier de magasin de clés SSL.
kafka.ssl.keystore.password	None	Toute chaîne de caractères	Mot de passe du fichier keystore SSL.

Pour obtenir des instructions complètes sur la configuration de l’authentification, consultez Authentification.

Pub/Sub

Utilisez ces options pour spark.readStream.format("pubsub") vous abonner à Google Pub/Sub. Les options subscriptionId, topicIdet projectId sont requises.

Clé	Par défaut	Valeurs valides	Description
subscriptionId	None	Toute chaîne de caractères	Obligatoire. ID d’abonnement Pub/Sub. Le connecteur crée l’abonnement s’il n’existe pas.
topicId	None	Toute chaîne de caractères	Obligatoire. ID de la rubrique Pub/Sub.
projectId	None	Toute chaîne de caractères	Obligatoire. ID de projet Google Cloud.
numFetchPartitions	Moitié du nombre d’exécuteurs disponibles lors de l’initialisation de flux	Entiers positifs	Nombre de tâches Spark parallèles qui extraient des lignes de l’abonnement.
maxBytesPerTrigger	None	Entiers positifs	Limite réversible du nombre d’octets à traiter par micro-lot.
maxRecordsPerFetch	1000	Entiers positifs	Nombre de lignes à extraire par tâche avant le traitement.
maxFetchPeriod	10s	Chaîne de durée telle que 1s ou 1m	Durée pendant laquelle chaque tâche doit récupérer des données avant de traiter les lignes. Azure Databricks recommande d’utiliser la valeur par défaut.
deleteSubscriptionOnStreamStop	false	true, false	Lorsque true, l’abonnement, de subscriptionId, est supprimé lorsque la requête de diffusion en continu se termine.
serviceCredential	None	Toute chaîne de caractères	Nom d’un Azure Databricks informations d’identification du service pour l’authentification auprès de Pub/Sub. Disponible dans Databricks Runtime 16.1 et versions ultérieures.
clientEmail	None	Chaîne d’adresse e-mail	Adresse e-mail du compte de service Google. Obligatoire lorsque vous n’utilisez pas d’informations d’identification de service.
clientId	None	Toute chaîne de caractères	ID client du compte de service Google. Obligatoire lorsque vous n’utilisez pas d’informations d’identification de service.
privateKey	None	Chaîne de clé privée	Clé privée pour le compte de service Google. Obligatoire lorsque vous n’utilisez pas d’informations d’identification de service.
privateKeyId	None	Toute chaîne de caractères	ID de clé privée pour le compte de service Google. Obligatoire lorsque vous n’utilisez pas d’informations d’identification de service.

Pour plus d’informations sur Pub/Sub, consultez s’abonner à Google Pub/Sub.

Pulsar

Utilisez ces options pour spark.readStream.format("pulsar") diffuser en continu à partir d’Apache Pulsar. Disponible dans Databricks Runtime 14.1 et versions ultérieures.

Les options suivantes sont requises. Vous devez spécifier exactement l’un des topic, topicsou topicsPattern.

Clé	Par défaut	Valeurs valides	Description
service.url	None	Chaîne d’URL du service Pulsar	Pulsar pour le service Pulsar serviceURL , par exemple pulsar://broker.example.com:6650.
topic	None	Toute chaîne de caractères	Nom d’une rubrique unique à consommer.
topics	None	Liste séparée par des virgules des noms de rubriques	Liste séparée par des virgules des noms de rubriques à consommer.
topicsPattern	None	Chaîne d’expression régulière Java	Chaîne d’expression régulière Java pour faire correspondre les noms de rubriques.

Les options suivantes sont également prises en charge :

Clé	Par défaut	Valeurs valides	Description
admin.url	None	Chaîne d’URL	URL HTTP du service d’administration Pulsar. Obligatoire quand maxBytesPerTrigger est défini.
allowDifferentTopicSchemas	false	true, false	Si plusieurs rubriques avec différents schémas sont lues, utilisez cette option pour désactiver la désérialisation automatique des valeurs de rubrique basée sur des schémas. Seules les valeurs brutes sont retournées quand il s’agit de true.
failOnDataLoss	true	true, false	Indique s’il faut échouer la requête lorsque les données sont perdues. Par exemple, la perte de données peut se produire lorsque des rubriques sont supprimées ou que des messages expirent en raison d’une stratégie de rétention.
maxBytesPerTrigger	None	Entiers positifs	Limite réversible du nombre d’octets à traiter par micro-lot. Exige admin.url.
pollTimeoutMs	120000	Entiers positifs	Délai d’attente de lecture des messages à partir de Pulsar en millisecondes.
predefinedSubscription	None	Toute chaîne de caractères	Nom d’abonnement prédéfini utilisé par le connecteur pour suivre la progression de l’application Spark.
startingOffsets	latest	latest, earliestou une chaîne de décalage JSON	Où commencer la lecture.
subscriptionPrefix	None	Toute chaîne de caractères	Préfixe utilisé par le connecteur pour générer un abonnement aléatoire pour suivre la progression de l’application Spark.
waitingForNonExistedTopic	false	true, false	Indique si le connecteur attend que les rubriques souhaitées soient créées.

Vous pouvez spécifier des configurations supplémentaires de client, d’administrateur et de lecteur Pulsar à l’aide des modèles d’option suivants :

Modèle	Options de configuration
pulsar.admin.*	Configuration de l’administrateur Pulsar
pulsar.client.*	Configuration du client Pulsar, y compris les options d’authentification telles que pulsar.client.authPluginClassName et pulsar.client.authParams.
pulsar.reader.*	Configuration du lecteur Pulsar

Pour plus d’informations sur les options d’authentification client et administrateur Pulsar, consultez Authentification.

Authentification

Azure Databricks prend en charge l’authentification truststore et keystore sur Pulsar. Azure Databricks recommande d’utiliser des secrets pour stocker les détails de l’authentification. Consultez Gestion des secrets.

Clé	Par défaut	Valeurs valides	Description
pulsar.client.authPluginClassName	None	Nom de classe complet	Nom de classe complet du plug-in d’authentification. Par exemple : org.apache.pulsar.client.impl.auth.AuthenticationTls.
pulsar.client.authParams	None	Chaîne d’informations d’identification	Informations d’identification d’authentification transmises au plug-in d’authentification sous forme de chaîne. Par exemple : tlsCertFile:/path/to/my-role.cert.pem,tlsKeyFile:/path/to/my-role.key-pk8.pem.
pulsar.client.useKeyStoreTls	false	true, false	Quand true, active la configuration TLS basée sur KeyStore au lieu de fichiers au format PEM.
pulsar.client.tlsTrustStoreType	None	Toute chaîne de caractères	Format du fichier de magasin d’approbation TLS. Par exemple : JKS.
pulsar.client.tlsTrustStorePath	None	Chaîne de chemin d’accès au fichier	Chemin d’accès au fichier de magasin d’approbation TLS contenant des certificats d’autorité de certification approuvés. Obligatoire quand pulsar.client.useKeyStoreTls est true.
pulsar.client.tlsTrustStorePassword	None	Toute chaîne de caractères	Mot de passe du fichier de magasin d’approbation TLS.

Si le flux utilise un PulsarAdmin, vous pouvez également définir les options suivantes :

Clé	Par défaut	Valeurs valides	Description
pulsar.admin.authPluginClassName	None	Nom de classe complet	Nom de classe complet du plug-in d’authentification pour le client administrateur Pulsar.
pulsar.admin.authParams	None	Chaîne d’informations d’identification	Informations d’identification d’authentification pour le plug-in d’authentification du client administrateur Pulsar.
pulsar.admin.useTls	None	true, false	Indique s’il faut utiliser TLS pour la connexion du client administrateur Pulsar.
pulsar.admin.tlsAllowInsecureConnection	None	true, false	Indique s’il faut autoriser les connexions TLS non sécurisées pour le client administrateur Pulsar.
pulsar.admin.tlsTrustCertsFilePath	None	Chaîne de chemin d’accès au fichier	Chemin d’accès au fichier de certificat TLS approuvé pour le client administrateur Pulsar.
pulsar.admin.useKeyStoreTls	None	true, false	Indique s’il faut utiliser le protocole TLS basé sur KeyStore pour le client d’administration Pulsar.
pulsar.admin.tlsTrustStoreType	None	Toute chaîne de caractères	Format du magasin d’approbations TLS pour le client d’administration Pulsar. Par exemple : JKS.
pulsar.admin.tlsTrustStorePath	None	Chaîne de chemin d’accès au fichier	Chemin d’accès au fichier de magasin d’approbation TLS pour le client administrateur Pulsar. Obligatoire quand pulsar.admin.useKeyStoreTls est true.
pulsar.admin.tlsTrustStorePassword	None	Toute chaîne de caractères	Mot de passe pour le magasin d’approbation TLS du client Administrateur Pulsar.

Pour obtenir des exemples d’authentification, consultez Authentifier auprès de Pulsar.

Options DataFrameWriter

Utilisez ces options avec DataFrameWriter.option() et DataFrameWriterV2.option() pour contrôler la façon dont Azure Databricks écrit des données.

Example

L’exemple suivant définit mergeSchema la valeur pour True écrire une table Delta Lake :

Python

df.write.format("delta").option("mergeSchema", True).saveAsTable("my_table")

Scala

df.write.format("delta").option("mergeSchema", "true").saveAsTable("my_table")

Avro

Les options suivantes s’appliquent lors de l’écriture de fichiers Avro.

Clé	Par défaut	Valeurs valides	Description
avroSchema	None	Chaîne de schéma JSON	Schéma Avro complet sous forme de chaîne JSON. Utilisez cette option pour convertir des types SPARK SQL en types Avro spécifiques. S’applique aux fichiers Avro en lecture et en écriture.
avroSchemaUrl	None	Chaîne d’URL	URL pointant vers un fichier de schéma Avro. Utilisez plutôt avroSchema que lorsque le schéma est stocké en externe. Mutuellement exclusif avec avroSchema. S’applique aux fichiers Avro en lecture et en écriture.
compression	snappy	uncompressed, , deflate, snappy (default)bzip2, , xzzstandard	Codec de compression à utiliser lors de l’écriture. S’applique aux fichiers Avro en lecture et en écriture.
recordName	topLevelRecord	Toute chaîne de caractères	Nom d’enregistrement de niveau supérieur dans le schéma Avro de sortie. S’applique aux fichiers Avro en lecture et en écriture.
positionalFieldMatching	false	true, false	Indique s’il faut faire correspondre les colonnes entre le schéma Spark et le schéma Avro par position de champ au lieu d’un nom. S’applique aux fichiers Avro en lecture et en écriture.
recordNamespace	Chaîne vide	Toute chaîne de caractères	Espace de noms pour l’enregistrement de niveau supérieur dans le schéma Avro de sortie. S’applique aux fichiers Avro en lecture et en écriture.

Delta Lake et Apache Iceberg

Les options suivantes s’appliquent lors de l’écriture de tables Delta Lake et Apache Iceberg.

Clé	Par défaut	Valeurs valides	Description
clusterByAuto	false	true, false	Indique s’il faut activer le clustering liquide automatique, où Azure Databricks sélectionne des colonnes de clustering en fonction des modèles de requête. Valide uniquement avec mode("overwrite"). Impossible d’utiliser le append mode. Disponible dans Databricks Runtime 16.4 et versions ultérieures. S’applique à Utiliser le clustering liquide pour les tables.
mergeSchema	None	true, false	Indique s’il faut activer l’évolution du schéma pour l’opération d’écriture. Les nouvelles colonnes du DataFrame source sont ajoutées au schéma de table cible. S’applique aux ajouts de traitement par lots et de diffusion en continu. S’applique aux schémas de table de mise à jour avec l’évolution du schéma.
overwriteSchema	None	true, false	Indique s’il faut remplacer le schéma de table et le partitionnement lors du remplacement. Nécessite mode("overwrite") sans replaceWhere. Impossible d’utiliser avec partitionOverwriteMode. S’applique aux schémas de table de mise à jour avec l’évolution du schéma.
partitionOverwriteMode	None	static, dynamic	Mode de remplacement de partition. Définissez cette option pour dynamic remplacer uniquement les partitions contenant de nouvelles données, ce qui laisse toutes les autres partitions inchangées. Mode hérité, non pris en charge sur le calcul serverless ou Databricks SQL. S’applique à remplacer de manière sélective les données avec Delta Lake.
replaceOn	None	Chaîne d’expression booléenne	Expression booléenne qui correspond aux lignes de la table cible à remplacer par des lignes de la requête source. Peut référencer des colonnes à partir de la table cible et de la requête source. Les lignes de la cible qui correspondent à une ligne source sont supprimées et remplacées. Si la source est vide, aucune suppression ne se produit. Permet targetAlias de lever l’ambiguïté des références de colonne. Disponible dans Databricks Runtime 17.1 et versions ultérieures. S’applique à remplacer de manière sélective les données avec Delta Lake.
replaceUsing	None	Liste séparée par des virgules de noms de colonnes	Liste séparée par des virgules des noms de colonnes utilisée pour faire correspondre les lignes entre la table cible et la requête source. La cible et la source doivent contenir toutes les colonnes répertoriées. Les lignes de la cible qui correspondent à une ligne source sous comparaison d’égalité sont supprimées et remplacées. NULL les valeurs sont traitées comme non égales et ne correspondent pas. Disponible dans Databricks Runtime 16.3 et versions ultérieures. S’applique à remplacer de manière sélective les données avec Delta Lake.
replaceWhere	None	Chaîne d’expression de prédicat	Expression de prédicat. Remplace atomiquement uniquement les enregistrements qui correspondent au prédicat. S’applique à remplacer de manière sélective les données avec Delta Lake.
targetAlias	None	Toute chaîne de caractères	Alias de chaîne pour la table cible. replaceOn Utilisez ou replaceWhere désambiguez les références de colonne lorsque la condition référence les colonnes de la table cible et de la requête source. S’applique à remplacer de manière sélective les données avec Delta Lake.
txnAppId	None	Toute chaîne de caractères	Chaîne unique identifiant l’application pour les écritures idempotentes dans les foreachBatch opérations. Utilisez-les avec txnVersion pour garantir des écritures exactement une fois dans plusieurs tables Delta Lake. S’applique à Utiliser foreachBatch pour les écritures de tables idempotentes.
txnVersion	None	Entier monotoniquement croissant	Nombre monotoniquement croissant utilisé comme version de transaction pour les écritures idempotentes dans foreachBatch les opérations. Utilisez-les avec txnAppId pour garantir des écritures exactement une fois dans plusieurs tables Delta Lake. S’applique à Utiliser foreachBatch pour les écritures de tables idempotentes.
optimizeWrite	None	true, false	Indique s’il faut activer l’optimisation automatique de l’écriture pour cette opération d’écriture. Remplace la spark.databricks.delta.optimizeWrite.enabled configuration. S’applique à Qu’est-ce que Delta Lake dans Azure Databricks ?.
userMetadata	None	Toute chaîne de caractères	Chaîne définie par l’utilisateur ajoutée aux métadonnées de validation pour l’opération d’écriture. Visible dans la sortie de DESCRIBE HISTORY. S’applique à Enrichir des tables avec des métadonnées personnalisées.

CSV

Les options suivantes s’appliquent lors de l’écriture de fichiers CSV.

Clé	Par défaut	Valeurs valides	Description
charToEscapeQuoteEscaping	\0 (non activé)	Un caractère unique	Caractère utilisé pour échapper au caractère d’échappement lorsqu’il diffère du caractère de guillemet. S’applique à csv (DataFrameWriter).
compression	none	none (default), bzip2, , gziplz4, snappy, , deflate,zstd	Codec de compression à utiliser lors de l’écriture. S’applique à csv (DataFrameWriter).
dateFormat	yyyy-MM-dd	Chaîne de format de date	Chaîne de format pour les valeurs de colonne de date. S’applique à csv (DataFrameWriter).
emptyValue	Chaîne vide	Toute chaîne de caractères	Chaîne écrite pour les valeurs vides (non null). S’applique à csv (DataFrameWriter).
encoding	UTF-8	Nom java.nio.charset.Charset	Encodage de caractères pour les fichiers de sortie. S’applique à csv (DataFrameWriter).
escape	\	Un caractère unique	Caractère utilisé pour échapper les valeurs entre guillemets. S’applique à csv (DataFrameWriter).
escapeQuotes	true	true, false	Indique s’il faut placer les guillemets entre guillemets dans les valeurs de champ entre guillemets. S’applique à csv (DataFrameWriter).
header	false	true, false	Indique s’il faut écrire des noms de colonnes comme première ligne de la sortie. S’applique à csv (DataFrameWriter).
ignoreLeadingWhiteSpace	false	true, false	Indique s’il faut découper les espaces blancs de début des valeurs lors de l’écriture. S’applique à csv (DataFrameWriter).
ignoreTrailingWhiteSpace	false	true, false	Indique s’il faut découper l’espace de fin des valeurs lors de l’écriture. S’applique à csv (DataFrameWriter).
lineSep	\n	Chaîne	Chaîne de séparation de ligne utilisée entre les enregistrements. S’applique à csv (DataFrameWriter).
locale	en-US	Identificateur java.util.Locale	Identificateur java.util.Locale. Un Java paramètres régionaux identifiés qui affectent la date, l’horodatage et l’analyse décimale par défaut dans le fichier CSV.
nullValue	Chaîne vide	Toute chaîne de caractères	Chaîne écrite pour les valeurs Null. S’applique à csv (DataFrameWriter).
quote	"	Un caractère unique	Caractère utilisé pour citer les valeurs de champ qui contiennent le séparateur. S’applique à csv (DataFrameWriter).
quoteAll	false	true, false	Indique s’il faut placer toutes les valeurs de champ entre guillemets, quel que soit le contenu. S’applique à csv (DataFrameWriter).
sep	,	Chaîne	Caractère délimiteur de champ. S’applique à csv (DataFrameWriter).
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Chaîne de format d’horodatage	Chaîne de format pour les valeurs de colonne timestamp. S’applique à csv (DataFrameWriter).
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Chaîne de format d’horodatage	Mettre en forme la chaîne pour l’horodatage sans valeurs de colonne de fuseau horaire (TimestampNTZType).

Excel

Les options suivantes s’appliquent lors de l’écriture de fichiers Excel.

Clé	Par défaut	Valeurs valides	Description
dataAddress	None	Chaîne de référence de feuille ou de cellule	Nom de la feuille ou cellule de départ de l’écriture. En cas d’omission, écrit dans une feuille nommée Sheet1 à partir de la cellule A1. Accepte un nom de feuille (SheetName) ou une référence de cellule unique (SheetName!A1). Les plages de cellules ne sont pas prises en charge pour les écritures.
dateFormatInWrite	yyyy-mm-dd	Chaîne de format de date Excel	Excel chaîne de format de cellule appliquée aux colonnes Date. Utilise Excel syntaxe de format.
headerRows	0	0, 1	Indique s’il faut écrire des noms de colonnes en tant que première ligne.
timestampNTZFormat	yyyy-mm-dd hh:mm:ss	Chaîne de format d’horodatage Excel	Excel chaîne de format de cellule appliquée aux colonnes TimestampNTZ et Timestamp. Utilise Excel syntaxe de format.
version	xlsx	xlsx, xls	Version du format de fichier Excel à écrire.

JSON

Les options suivantes s’appliquent lors de l’écriture de fichiers JSON.

Clé	Par défaut	Valeurs valides	Description
compression	none	none, bzip2, , gziplz4, snappy, , deflate,zstd	Codec de compression à utiliser lors de l’écriture. S’applique à json (DataFrameWriter).
dateFormat	yyyy-MM-dd	Chaîne de format de date	Chaîne de format pour les valeurs de colonne de date. S’applique à json (DataFrameWriter).
encoding	UTF-8	Nom java.nio.charset.Charset	Encodage de caractères pour les fichiers de sortie. S’applique à json (DataFrameWriter).
ignoreNullFields	valeur de spark.sql.jsonGenerator.ignoreNullFields	true, false	Indique s’il faut omettre des champs avec des valeurs Null à partir de la sortie JSON. S’applique à json (DataFrameWriter).
lineSep	\n	Chaîne	Chaîne de séparation de ligne utilisée entre les enregistrements. S’applique à json (DataFrameWriter).
locale	en-US	Identificateur java.util.Locale	Identificateur de paramètres régionaux Java qui affecte la date, l’horodatage et l’analyse décimale par défaut dans le json.
pretty	false	true, false	Indique s’il faut activer une sortie JSON assez (mise en retrait, multiligne).
sortKeys	false	true, false	Indique s’il faut trier les clés d’objets JSON par ordre alphabétique dans la sortie. Utile pour produire une sortie déterministe.
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Chaîne de format d’horodatage	Chaîne de format pour les valeurs de colonne timestamp. S’applique à json (DataFrameWriter).
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Chaîne de format d’horodatage	Mettre en forme la chaîne pour l’horodatage sans valeurs de colonne de fuseau horaire (TimestampNTZType).
writeNonAsciiCharacterAsCodePoint	false	true, false	Indique s’il faut encoder des caractères non ASCII en tant que \uXXXX séquences d’échappement Unicode au lieu de caractères UTF-8 littérals dans la sortie.

ORC

Les options suivantes s’appliquent lors de l’écriture de fichiers ORC.

Clé	Par défaut	Valeurs valides	Description
compression	zstd	none, uncompressed, , snappyzlib, lzo, zstd, , lz4,brotli	Codec de compression à utiliser lors de l’écriture. S’applique à orc (DataFrameWriter).

Parquet

Les options suivantes s’appliquent lors de l’écriture de fichiers Parquet.

Clé	Par défaut	Valeurs valides	Description
compression	snappy	none, uncompressed, , snappygzip, lzo, brotli, lz4, lz4_raw,zstd	Codec de compression à utiliser lors de l’écriture. S’applique au parquet (DataFrameWriter).
spark.sql.parquet.outputTimestampType	INT96	INT96, , TIMESTAMP_MICROSTIMESTAMP_MILLIS	Type physique utilisé pour encoder des colonnes d’horodatage. Utiliser INT96 pour la compatibilité avec les lecteurs Parquet hérités qui ne prennent pas en charge les types d’horodatage standard.

Texte

Les options suivantes s’appliquent lors de l’écriture de fichiers texte.

Clé	Par défaut	Valeurs valides	Description
compression	none	none, bzip2, , gziplz4, snappy, , deflate,zstd	Codec de compression à utiliser lors de l’écriture. S’applique au texte (DataFrameWriter).
encoding	UTF-8	Nom java.nio.charset.Charset	Encodage de caractères pour les fichiers de sortie.
lineSep	\n	Chaîne	Chaîne de séparation de ligne utilisée entre les enregistrements. S’applique au texte (DataFrameWriter).

XML

Les options suivantes s’appliquent lors de l’écriture de fichiers XML.

Clé	Par défaut	Valeurs valides	Description
arrayElementName	item	Toute chaîne de caractères	Nom de l’élément pour les éléments de tableau qui n’ont pas de nom explicite. S’applique au xml (DataFrameWriter).
attributePrefix	_	Toute chaîne de caractères	Préfixe ajouté aux noms de champs correspondant aux attributs XML. S’applique au xml (DataFrameWriter).
compression	none	none, bzip2, , gziplz4, snappy, , deflate,zstd	Codec de compression à utiliser lors de l’écriture. S’applique au xml (DataFrameWriter).
dateFormat	yyyy-MM-dd	Chaîne de format de date	Chaîne de format pour les valeurs de colonne de date. S’applique au xml (DataFrameWriter).
declaration	version="1.0" encoding="UTF-8" standalone="yes"	Chaîne de déclaration XML ou chaîne vide à supprimer	Chaîne de déclaration XML écrite en haut de chaque fichier de sortie. Définissez sur une chaîne vide pour supprimer la déclaration. S’applique au xml (DataFrameWriter).
encoding	UTF-8	Nom java.nio.charset.Charset	Encodage de caractères pour les fichiers de sortie. S’applique au xml (DataFrameWriter).
indent	4 espaces	Toute chaîne de caractères	Chaîne utilisée pour mettre en retrait les éléments enfants dans la sortie. Définissez sur une chaîne vide pour désactiver la mise en retrait et écrire chaque ligne sur une seule ligne.
locale	en-US	Identificateur java.util.Locale	Identificateur de paramètres régionaux Java qui affecte la date, l’horodatage et la mise en forme décimale par défaut dans le code XML.
nullValue	null	Toute chaîne de caractères	Chaîne écrite pour les valeurs Null. Lorsque la valeur est définie null, les attributs et les éléments enfants pour les champs Null sont omis. S’applique au xml (DataFrameWriter).
rootTag	ROWS	Toute chaîne de caractères	Balise d’élément racine qui encapsule tous les éléments de ligne dans la sortie. S’applique au xml (DataFrameWriter).
rowTag	ROW	Toute chaîne de caractères	Balise d’élément qui représente une ligne dans la sortie. S’applique au xml (DataFrameWriter).
singleVariantColumn	None	Chaîne de nom de colonne	Nom de la colonne Variant unique à écrire dans des fichiers XML. S’applique au xml (DataFrameWriter).
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Chaîne de format d’horodatage	Chaîne de format pour les valeurs de colonne timestamp. S’applique au xml (DataFrameWriter).
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Chaîne de format d’horodatage	Mettre en forme la chaîne pour l’horodatage sans valeurs de colonne de fuseau horaire. S’applique au xml (DataFrameWriter).
validateName	true	true, false	Indique s’il faut lever une exception si un nom de colonne n’est pas un identificateur d’élément XML valide. S’applique au xml (DataFrameWriter).
valueTag	_VALUE	Toute chaîne de caractères	Nom de champ utilisé pour les données de caractères dans les éléments XML qui ont également des attributs ou des éléments enfants. S’applique au xml (DataFrameWriter).

Options DataStreamWriter

Utilisez ces options DataStreamWriter.option() pour configurer les écritures de diffusion en continu.

Example

L’exemple suivant définit l’emplacement de point de contrôle d’un flux :

Python

(df.writeStream
  .format("delta")
  .option("checkpointLocation", "/path/to/checkpoint")
  .start("/path/to/table"))

Scala

df.writeStream
  .format("delta")
  .option("checkpointLocation", "/path/to/checkpoint")
  .start("/path/to/table")

Commun

Les options suivantes s’appliquent à toutes les opérations d’écriture de streaming.

Clé	Par défaut	Valeurs valides	Description
checkpointLocation	Aucun (obligatoire)	Chaîne de chemin d’accès	Chemin d’accès au répertoire de point de contrôle de la requête de streaming. Obligatoire pour la tolérance de panne et les garanties de traitement exactement une fois. Chaque requête de streaming doit utiliser un emplacement de point de contrôle unique. Databricks recommande de stocker des points de contrôle dans un volume de catalogue Unity ou un chemin de stockage cloud. Consultez les Points de contrôle Structured Streaming.
path	None	Chaîne de chemin d’accès	Chemin de sortie pour les récepteurs de diffusion en continu basés sur des fichiers, tels que Parquet. S’applique uniquement aux formats basés sur des fichiers.

Récepteur de console

Les options suivantes s’appliquent lors de l’écriture de flux dans le récepteur de console.

Clé	Par défaut	Valeurs valides	Description
numRows	20	Entiers positifs	Nombre de lignes à afficher pour chaque micro-lot lors de l’écriture dans le récepteur de console.
truncate	true	true, false	Indique s’il faut tronquer des chaînes longues lors de l’affichage de lignes. Définissez la valeur pour false afficher les valeurs de chaîne complètes.

Delta Lake

Les options suivantes s’appliquent lors de l’écriture d’un flux dans une table Delta Lake à l’aide format("delta")de . Les options de remplacement uniquement telles que overwriteSchema, replaceWhereet partitionOverwriteMode ne sont pas prises en charge pour les écritures de streaming.

Clé	Par défaut	Valeurs valides	Description
mergeSchema	false	true, false	Indique s’il faut faire évoluer le schéma de table Delta Lake lorsque le DataFrame de streaming contient de nouvelles colonnes. S’applique uniquement au mode de sortie d’ajout. S’applique aux schémas de table de mise à jour avec l’évolution du schéma.
userMetadata	None	Toute chaîne de caractères	Chaîne définie par l’utilisateur ajoutée aux métadonnées de validation pour l’opération d’écriture. Visible dans la sortie de DESCRIBE HISTORY. S’applique à Enrichir des tables avec des métadonnées personnalisées.

Récepteur de fichiers

L’option suivante s’applique lors de l’écriture d’un flux dans des formats basés sur des fichiers (Parquet, JSON, CSV, ORC, texte). Pour obtenir des options spécifiques au format, consultez les options DataFrameWriter.

Clé	Par défaut	Valeurs valides	Description
retention	None	Chaîne de temps telle que 7 days ou 24 hours	Durée de conservation des fichiers de métadonnées récepteur utilisés pour la tolérance de panne et le compactage. Lorsqu’ils ne sont pas définis, les fichiers de métadonnées sont conservés indéfiniment.

Récepteur Kafka

Les options suivantes s’appliquent lors de l’écriture dans Kafka.

Clé	Par défaut	Valeurs valides	Description
kafka.bootstrap.servers	None	Liste séparée par des virgules de host:port chaînes	Obligatoire. Liste séparée par des virgules d’adresses de répartiteur host:port Kafka.
topic	None	Toute chaîne de caractères	Rubrique Kafka cible pour toutes les lignes. Obligatoire si le DataFrame n’inclut pas de topic colonne.
kafka.*	None	Toute valeur de configuration du producteur Kafka	Toute configuration de producteur Kafka précédée kafka.de . Par exemple : kafka.compression.type.

Récepteur de mémoire

Les options suivantes s’appliquent lors de l’écriture de flux dans le récepteur de mémoire.

Clé	Par défaut	Valeurs valides	Description
queryName	Aucun (obligatoire)	Toute chaîne de caractères	Nom de la table en mémoire dans laquelle la requête écrit. Requis pour le récepteur de mémoire. Également configurable via .queryName().
mode	exactlyonce	exactlyonce, atleastonce	Garantie de livraison pour le récepteur de mémoire. exactlyonce utilise le mode micro-batch avec une sémantique exactement une fois. atleastonce utilise le mode continu avec une sémantique au moins une fois.

Options de fonction Spark

Certaines fonctions intégrées Spark SQL acceptent une carte qui contrôle le comportement d’analyse options ou de sérialisation. Passez des options en tant que Python dict ou scala Map[String, String].

Example

L’exemple suivant analyse une colonne JSON lors de la suppression d’enregistrements mal formés :

Python

from pyspark.sql.functions import from_json
from pyspark.sql.types import StructType, StructField, StringType

schema = StructType([StructField("name", StringType())])
df = df.withColumn("parsed", from_json("json_col", schema, {"mode": "DROPMALFORMED"}))

Scala

import org.apache.spark.sql.functions.from_json
import org.apache.spark.sql.types._

val schema = StructType(Seq(StructField("name", StringType)))
val df = df.withColumn("parsed", from_json(col("json_col"), schema, Map("mode" -> "DROPMALFORMED")))

Avro

Les fonctions Avro acceptent les mêmes options que les options de DataFrame correspondantes :

• from_avro et schema_of_avro utilisez les options DataFrameReader Avro.
• to_avro utilise les options DataFrameWriter Avro.

Example

L’exemple suivant décode une colonne Avro avec l’évolution du schéma activée :

Python

from pyspark.sql.functions import from_avro

df = df.withColumn("decoded", from_avro("avro_col", json_schema, {"avroSchemaEvolutionMode": "restart"}))

Scala

import org.apache.spark.sql.avro.functions.from_avro

val df = df.withColumn("decoded", from_avro(col("avro_col"), jsonSchema, Map("avroSchemaEvolutionMode" -> "restart")))

En outre, les variantes du Registre de schémas des from_avroto_avro options suivantes sont les suivantes :

Clé	Par défaut	Valeurs valides	Description
schemaId	None	Entier d’ID de schéma	ID de schéma du Registre de schémas Confluent à utiliser lors du décodage des données Avro codées avec un schéma incompatible avec jsonFormatSchema. S’applique uniquement.from_avro
confluent.schema.registry.*	None	Toute valeur de propriété cliente Confluent SR	Propriétés de configuration du client Confluent Schema Registry. Transmettez une propriété cliente Confluent SR à l’aide de ce préfixe, par exemple confluent.schema.registry.basic.auth.user.info pour les informations d’identification d’authentification de base. Obligatoire pour les variantes du Registre de schémas de from_avro et to_avro.

CSV

Les fonctions CSV acceptent les mêmes options que les options dataFrame correspondantes :

• from_csv et schema_of_csv utiliser les options CSV DataFrameReader.
• to_csv utilise les options CSV DataFrameWriter.

Example

L’exemple suivant lit csv avec un séparateur et NULL une valeur personnalisés :

Python

from pyspark.sql.functions import from_csv
from pyspark.sql.types import StructType, StructField, IntegerType, StringType

schema = StructType([StructField("id", IntegerType()), StructField("name", StringType())])
df = df.withColumn("parsed", from_csv("csv_col", schema, {"sep": "|", "nullValue": "N/A"}))

Scala

import org.apache.spark.sql.functions.from_csv
import org.apache.spark.sql.types._

val schema = StructType(Seq(StructField("id", IntegerType), StructField("name", StringType)))
val df = df.withColumn("parsed", from_csv(col("csv_col"), schema, Map("sep" -> "|", "nullValue" -> "N/A")))

JSON

Les fonctions JSON acceptent les mêmes options que les options de DataFrame correspondantes :

• from_json et schema_of_json utilisez les options JSON DataFrameReader.
• to_json utilise les options JSON DataFrameWriter.

Example

L’exemple suivant écrit JSON avec NULL des champs ignorés et une mise en forme assez activée :

Python

from pyspark.sql.functions import to_json

df = df.withColumn("json_str", to_json("struct_col", {"pretty": "true", "ignoreNullFields": "true"}))

Scala

import org.apache.spark.sql.functions.to_json

val df = df.withColumn("json_str", to_json(col("struct_col"), Map("pretty" -> "true", "ignoreNullFields" -> "true")))

Protobuf

from_protobuf et to_protobuf n’utilisez pas de Source de données basée sur des fichiers. Les données Protobuf sont toujours lues et écrites sous forme de colonnes binaires à l’aide de ces fonctions. Les options sont passées en tant que Map[String, String] respectant la casse.

Example

L’exemple suivant décode une colonne Protobuf à l’aide du mode PERMISSIVE :

Python

from pyspark.sql.functions import from_protobuf

df = df.withColumn("decoded", from_protobuf("proto_col", "MyMessage", "/path/to/descriptor.desc",
    {"mode": "PERMISSIVE", "enums.as.ints": "true"}))

Scala

import org.apache.spark.sql.protobuf.functions.from_protobuf

val df = df.withColumn("decoded", from_protobuf(col("proto_col"), "MyMessage", "/path/to/descriptor.desc",
    Map("mode" -> "PERMISSIVE", "enums.as.ints" -> "true")))

Les fonctions Protobuf utilisent les options suivantes :

Clé	Par défaut	Valeurs valides	Description
mode	FAILFAST	FAILFAST, PERMISSIVE	Comment gérer les enregistrements endommagés. FAILFAST lève une exception. PERMISSIVE définit les champs mal formés sur Null. S’applique à from_protobuf.
recursive.fields.max.depth	-1 (désactivé)	De 0 à 10.	Profondeur maximale de récursivité pour les champs Protobuf récursifs. Définissez cette option pour 0 désactiver la prise en charge des champs récursifs. S’applique à from_protobuf.
convert.any.fields.to.json	false	true, false	Indique s’il faut convertir des champs Protobuf Any en chaîne JSON au lieu d’un STRUCT. S’applique à from_protobuf.
emit.default.values	false	true, false	Indique s’il faut émettre des champs avec des valeurs zéro ou par défaut (sémantique proto3). Lorsque false, les champs avec des valeurs par défaut sont omis à partir de la sortie. S’applique à from_protobuf.
enums.as.ints	false	true, false	Indique si les champs d’énumération doivent être affichés sous forme de valeurs entières au lieu de chaînes. S’applique à from_protobuf.
upcast.unsigned.ints	false	true, false	Indique s’il faut effectuer une mise en mode upcast uint32 vers Long et uint64 empêcher Decimal(20,0) le dépassement d’entier. S’applique à from_protobuf.
unwrap.primitive.wrapper.types	false	true, false	Indique s’il faut annuler google.protobuf les types wrapper (par exemple, Int32Value et StringValue) à leurs types Spark primitifs correspondants. S’applique à from_protobuf.
retain.empty.message.types	false	true, false	Indique s’il faut conserver les types de messages Protobuf vides dans le schéma de sortie en insérant une colonne factice. S’applique à from_protobuf.
schema.registry.subject	None	Toute chaîne de caractères	Nom de l’objet du Registre de schémas. Obligatoire lors de l’utilisation des variantes de Registre de schémas de from_protobuf et to_protobuf.
schema.registry.address	None	Chaîne host:port	Adresse du Registre de schémas (hôte et port). Obligatoire lors de l’utilisation des variantes de Registre de schémas de from_protobuf et to_protobuf.
schema.registry.protobuf.name	None	Toute chaîne de caractères	Spécifie le message Protobuf à utiliser lorsque l’objet du registre de schémas contient plusieurs messages. Optional.
schema.registry.schema.evolution.mode	"restart"	"restart", "none"	Comment les modifications de schéma sont gérées lorsqu’un ID de schéma plus récent est détecté dans un enregistrement entrant. "restart" met fin à la requête avec un UnknownFieldException; configurez les travaux pour redémarrer en cas de défaillance de la prise en charge des modifications. "none" ignore les modifications de l’ID de schéma et analyse les enregistrements plus récents avec le schéma d’origine.
confluent.schema.registry.<option>	—	Toute valeur de client confluent Schema Registry valide	Transmettez n’importe quelle option cliente du Registre de schémas Confluent à l’aide du préfixe "confluent.schema.registry". Par exemple, définissez "confluent.schema.registry.basic.auth.credentials.source""USER_INFO" et "confluent.schema.registry.basic.auth.user.info" configurez "<KEY>:<SECRET>" l’authentification de base.

XML

Les fonctions XML acceptent les mêmes options que les options de DataFrame correspondantes :

• from_xml et schema_of_xml utilisez les options XML DataFrameReader.
• to_xml utilise les options XML DataFrameWriter.

Example

L’exemple suivant écrit du code XML avec des balises racines et de lignes personnalisées :

Python

from pyspark.sql.functions import to_xml

df = df.withColumn("xml_str", to_xml("struct_col", {"rootTag": "records", "rowTag": "record"}))

Scala

import org.apache.spark.sql.functions.to_xml

val df = df.withColumn("xml_str", to_xml(col("struct_col"), Map("rootTag" -> "records", "rowTag" -> "record")))