Référence des utilitaires Databricks (dbutils)
Cet article est une référence pour les utilitaires Databricks (dbutils). dbutils les utilitaires sont disponibles dans les blocs-notes Python, R et Scala. Vous pouvez utiliser les utilitaires pour :
- Travaillez efficacement avec les fichiers et le stockage d’objets.
- Travaillez avec des secrets.
Comment : Lister les utilitaires, lister les commandes, afficher l'aide des commandes
Utilitaires : données, fs, travaux, bibliothèque, notebook, secrets, widgets, Utilitaires bibliothèque API
Répertorier les utilitaires disponibles
Pour répertorier les utilitaires disponibles, ainsi qu’une brève description de chaque utilitaire, exécutez dbutils.help() pour Python ou Scala.
Cet exemple répertorie les commandes disponibles pour les utilitaires Databricks.
Python
dbutils.help()
Scala
dbutils.help()
This module provides various utilities for users to interact with the rest of Databricks.
credentials: DatabricksCredentialUtils -> Utilities for interacting with credentials within notebooks
data: DataUtils -> Utilities for understanding and interacting with datasets (EXPERIMENTAL)
fs: DbfsUtils -> Manipulates the Databricks filesystem (DBFS) from the console
jobs: JobsUtils -> Utilities for leveraging jobs features
library: LibraryUtils -> Utilities for session isolated libraries
meta: MetaUtils -> Methods to hook into the compiler (EXPERIMENTAL)
notebook: NotebookUtils -> Utilities for the control flow of a notebook (EXPERIMENTAL)
preview: Preview -> Utilities under preview category
secrets: SecretUtils -> Provides utilities for leveraging secrets within notebooks
widgets: WidgetsUtils -> Methods to create and get bound value of input widgets inside notebooks
Répertorier les commandes disponibles pour un utilitaire
Pour répertorier les commandes disponibles pour un utilitaire avec une brève description de chaque commande, exécutez .help() après le nom de programmation de l’utilitaire.
Cet exemple liste les commandes disponibles pour l'utilitaire Databricks File System (DBFS).
Python
dbutils.fs.help()
R
dbutils.fs.help()
Scala
dbutils.fs.help()
dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".
fsutils
cp(from: String, to: String, recurse: boolean = false): boolean -> Copies a file or directory, possibly across FileSystems
head(file: String, maxBytes: int = 65536): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
ls(dir: String): Seq -> Lists the contents of a directory
mkdirs(dir: String): boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
mv(from: String, to: String, recurse: boolean = false): boolean -> Moves a file or directory, possibly across FileSystems
put(file: String, contents: String, overwrite: boolean = false): boolean -> Writes the given String out to a file, encoded in UTF-8
rm(dir: String, recurse: boolean = false): boolean -> Removes a file or directory
mount
mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Mounts the given source directory into DBFS at the given mount point
mounts: Seq -> Displays information about what is mounted within DBFS
refreshMounts: boolean -> Forces all machines in this cluster to refresh their mount cache, ensuring they receive the most recent information
unmount(mountPoint: String): boolean -> Deletes a DBFS mount point
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one
Afficher l’aide pour une commande
Pour afficher l’aide d’une commande, exécutez .help("<command-name>") après le nom de la commande.
Cet exemple affiche l’aide de la commande de copie DBFS.
Python
dbutils.fs.help("cp")
R
dbutils.fs.help("cp")
Scala
dbutils.fs.help("cp")
/**
* Copies a file or directory, possibly across FileSystems.
*
* Example: cp("/mnt/my-folder/a", "dbfs:/a/b")
*
* @param from FileSystem URI of the source file or directory
* @param to FileSystem URI of the destination file or directory
* @param recurse if true, all files and directories will be recursively copied
* @return true if all files were successfully copied
*/
cp(from: java.lang.String, to: java.lang.String, recurse: boolean = false): boolean
Utilitaire de données (dbutils.data)
Important
Cette fonctionnalité est disponible en préversion publique.
Notes
Disponible dans Databricks Runtime 9.0 et ultérieur.
Commandes: synthétiser
L’utilitaire de données vous permet de comprendre et d’interpréter les jeux de données. Pour répertorier les commandes disponibles, exécutez dbutils.data.help().
dbutils.data provides utilities for understanding and interpreting datasets. This module is currently in preview and may be unstable. For more info about a method, use dbutils.data.help("methodName").
summarize(df: Object, precise: boolean): void -> Summarize a Spark DataFrame and visualize the statistics to get quick insights
Commande summarize (dbutils.data.summarize)
Calcule et affiche les statistiques récapitulatives d’un Apache Spark tableau ou pandas tableau. Cette commande est disponible pour Python, Scala et R.
Cette commande analyse le contenu complet du DataFrame. L’exécution de cette commande pour des DataFrames très volumineux peut être très coûteuse.
Pour afficher l’aide de cette commande, exécutez dbutils.data.help("summarize").
Dans Databricks Runtime 10.4 LTS et versions ultérieures, vous pouvez utiliser le paramètre supplémentaire precise pour ajuster la précision des statistiques calculées.
Remarque
Cette fonctionnalité est disponible en préversion publique.
- Lorsque
precisea la valeur false (valeur par défaut), certaines statistiques retournées incluent des approximations pour réduire le temps d’exécution.- Le nombre de valeurs distinctes pour les colonnes catégoriques peut comporter environ 5% d’erreurs relatives pour les colonnes de cardinalité élevée.
- Le nombre de valeurs fréquentes peut avoir une erreur allant jusqu’à 0,01% lorsque le nombre de valeurs distinctes est supérieur à 10000.
- Les estimations des histogrammes et des centiles peuvent avoir une erreur allant jusqu’à 0,01% par rapport au nombre total de lignes.
- Lorsque
precisea la valeur true, les statistiques sont calculées avec une précision plus élevée. Toutes les statistiques, à l’exception des histogrammes et des centiles pour les colonnes numériques, sont désormais exactes.- Les estimations des histogrammes et des centiles peuvent avoir une erreur allant jusqu’à 0,0001% par rapport au nombre total de lignes.
L’info-bulle en haut de la sortie du résumé des données indique le mode de l’exécution actuelle.
Cet exemple affiche des statistiques récapitulatives pour un Apache Spark tableau avec des approximations activées par défaut. Pour afficher les résultats, exécutez cette commande dans un bloc-notes. Cet exemple est basé sur des échantillons de jeux de données.
Python
df = spark.read.format('csv').load(
'/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
header=True,
inferSchema=True
)
dbutils.data.summarize(df)
R
df <- read.df("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv", source = "csv", header="true", inferSchema = "true")
dbutils.data.summarize(df)
Scala
val df = spark.read.format("csv")
.option("inferSchema", "true")
.option("header", "true")
.load("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv")
dbutils.data.summarize(df)
Notez que la visualisation utilise la notation SI pour restituer de façon concise des valeurs numériques inférieures à 0,01 ou supérieures à 10000. Par exemple, la valeur numérique 1.25e-15 sera restituée sous la forme 1.25f. Une exception : la visualisation utilise « B » pour 1.0e9 (giga) au lieu de « G ».
Utilitaire de système de fichiers (dbutils.fs)
Avertissement
L’implémentation Python de toutes les méthodes dbutils.fs utilise snake_case plutôt que camelCase pour la mise en forme de mot clé.
Par exemple : quand dbutils.fs.help() affiche l’option extraConfigs pour dbutils.fs.mount(), dans Python, vous utiliseriez le mot clé extra_configs.
Commandes: cp, head, ls, mkdirs, mount, mounts, mv, put, refreshMounts, rm, unmount, updateMount
L’utilitaire de système de fichiers vous permet d’accéder à Qu’est-ce que DBFS ?, ce qui facilite l’utilisation d’Azure Databricks en tant que système de fichiers.
Dans les notebooks, vous pouvez également utiliser la commande %fs magic pour accéder à DBFS. Par exemple, %fs ls /Volumes/main/default/my-volume/ est identique à dbutils.fs.ls("/Volumes/main/default/my-volume/"). Voir Commandes magic.
Pour répertorier les commandes disponibles, exécutez dbutils.fs.help().
dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".
fsutils
cp(from: String, to: String, recurse: boolean = false): boolean -> Copies a file or directory, possibly across FileSystems
head(file: String, maxBytes: int = 65536): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
ls(dir: String): Seq -> Lists the contents of a directory
mkdirs(dir: String): boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
mv(from: String, to: String, recurse: boolean = false): boolean -> Moves a file or directory, possibly across FileSystems
put(file: String, contents: String, overwrite: boolean = false): boolean -> Writes the given String out to a file, encoded in UTF-8
rm(dir: String, recurse: boolean = false): boolean -> Removes a file or directory
mount
mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Mounts the given source directory into DBFS at the given mount point
mounts: Seq -> Displays information about what is mounted within DBFS
refreshMounts: boolean -> Forces all machines in this cluster to refresh their mount cache, ensuring they receive the most recent information
unmount(mountPoint: String): boolean -> Deletes a DBFS mount point
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one
Commande cp (dbutils.fs.cp)
Copie un fichier ou un répertoire, éventuellement entre des systèmes de fichiers.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("cp").
Cet exemple copie le fichier nommé data.csv de /Volumes/main/default/my-volume/ dans new-data.csv dans le même volume.
Python
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")
# Out[4]: True
R
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")
# [1] TRUE
Scala
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")
// res3: Boolean = true
Commande head (dbutils.fs.head)
Retourne jusqu’au nombre maximal d’octets spécifié pour le fichier donné. Les octets sont retournés sous la forme d’une chaîne encodée en UTF-8.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("head").
Cet exemple affiche les 25 premiers octets du fichier data.csv situé dans /Volumes/main/default/my-volume/ .
Python
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)
# [Truncated to first 25 bytes]
# Out[12]: 'Year,First Name,County,Se'
R
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)
# [1] "Year,First Name,County,Se"
Scala
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)
// [Truncated to first 25 bytes]
// res4: String =
// "Year,First Name,County,Se"
Commande Is (dbutils.fs.ls)
Copier le contenu d’un répertoire.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("ls").
Cet exemple affiche des informations sur le contenu de /Volumes/main/default/my-volume/. Le champ modificationTime est disponible dans Databricks Runtime 10.4 LTS et versions ultérieures. Dans R, modificationTime est retourné sous forme de chaîne.
Python
dbutils.fs.ls("/Volumes/main/default/my-volume/")
# Out[13]: [FileInfo(path='dbfs:/Volumes/main/default/my-volume/data.csv', name='data.csv', size=2258987, modificationTime=1711357839000)]
R
dbutils.fs.ls("/Volumes/main/default/my-volume/")
# For prettier results from dbutils.fs.ls(<dir>), please use `%fs ls <dir>`
# [[1]]
# [[1]]$path
# [1] "/Volumes/main/default/my-volume/data.csv"
# [[1]]$name
# [1] "data.csv"
# [[1]]$size
# [1] 2258987
# [[1]]$isDir
# [1] FALSE
# [[1]]$isFile
# [1] TRUE
# [[1]]$modificationTime
# [1] "1711357839000"
Scala
dbutils.fs.ls("/tmp")
// res6: Seq[com.databricks.backend.daemon.dbutils.FileInfo] = WrappedArray(FileInfo(/Volumes/main/default/my-volume/data.csv, 2258987, 1711357839000))
Commande mkdirs (dbutils.fs.mkdirs)
Crée le répertoire donné s’il n’existe pas. Crée également les répertoires parents nécessaires.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("mkdirs").
Cet exemple crée le répertoire my-data dans /Volumes/main/default/my-volume/.
Python
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")
# Out[15]: True
R
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")
# [1] TRUE
Scala
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")
// res7: Boolean = true
Commande mount (dbutils.fs.mount)
Monte le répertoire source spécifié dans DBFS au point de montage spécifié.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("mount").
Python
dbutils.fs.mount(
source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
mount_point = "/mnt/<mount-name>",
extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})
Scala
dbutils.fs.mount(
source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net/<directory-name>",
mountPoint = "/mnt/<mount-name>",
extraConfigs = Map("<conf-key>" -> dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")))
Pour obtenir des exemples de code supplémentaires, consultez l’article Se connecter à Azure Data Lake Storage Gen2 et au Stockage Blob.
Commande mounts (dbutils.fs.mounts)
Affiche des informations sur ce qui est actuellement monté dans DBFS.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("mounts").
Avertissement
Appelez dbutils.fs.refreshMounts() sur tous les autres clusters en cours d’exécution pour propager le nouveau montage. Consultez la section Commande refreshMounts (dbutils.fs.refreshMounts).
Python
dbutils.fs.mounts()
Scala
dbutils.fs.mounts()
Pour obtenir des exemples de code supplémentaires, consultez l’article Se connecter à Azure Data Lake Storage Gen2 et au Stockage Blob.
Commande mv (dbutils.fs.mv)
Déplace un fichier ou un répertoire, éventuellement sur plusieurs systèmes de fichiers. Un déplacement est une copie suivie d’une suppression, même pour les déplacements dans des systèmes de fichiers.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("mv").
Dans cet exemple, le fichier nommé rows.csv est déplacé de /Volumes/main/default/my-volume/ vers /Volumes/main/default/my-volume/my-data/.
Python
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")
# Out[2]: True
R
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")
# [1] TRUE
Scala
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")
// res1: Boolean = true
Commande put (dbutils.fs.put)
Écrit la chaîne spécifiée dans un fichier. La chaîne est encodée en UTF-8.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("put").
Cet exemple écrit la chaîne Hello, Databricks! dans le fichier nommé hello.txt dans /Volumes/main/default/my-volume/. Si le fichier existe déjà, il sera remplacé.
Python
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", True)
# Wrote 2258987 bytes.
# Out[6]: True
R
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", TRUE)
# [1] TRUE
Scala
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", true)
// Wrote 2258987 bytes.
// res2: Boolean = true
Commande refreshMounts (dbutils.fs.refreshMounts)
Force tous les ordinateurs du cluster à actualiser leur cache de montage, en veillant à ce qu’ils reçoivent les informations les plus récentes.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("refreshMounts").
Python
dbutils.fs.refreshMounts()
Scala
dbutils.fs.refreshMounts()
Pour obtenir des exemples de code supplémentaires, consultez l’article Se connecter à Azure Data Lake Storage Gen2 et au Stockage Blob.
Commande rm (dbutils.fs.rm)
Supprime un fichier ou un répertoire et éventuellement tout son contenu. Si un fichier est spécifié, le paramètre récursivité est ignoré. Si un répertoire est spécifié, une erreur se produit si la récursivité est désactivée et que le répertoire n’est pas vide.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("rm").
Cet exemple supprime le répertoire /Volumes/main/default/my-volume/my-data/ y compris le contenu du répertoire.
Python
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", True)
# Out[8]: True
R
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", TRUE)
# [1] TRUE
Scala
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", true)
// res6: Boolean = true
Commande unmount (dbutils.fs.unmount)
Supprime un point de montage DBFS.
Avertissement
Pour éviter les erreurs, ne modifiez jamais un point de montage quand d’autres travaux le lisent ou y écrivent. Après avoir modifié un montage, exécutez toujours dbutils.fs.refreshMounts() sur tous les autres clusters en cours d’exécution pour propager les mises à jour de montage. Consultez la section Commande refreshMounts (dbutils.fs.refreshMounts).
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("unmount").
dbutils.fs.unmount("/mnt/<mount-name>")
Pour obtenir des exemples de code supplémentaires, consultez l’article Se connecter à Azure Data Lake Storage Gen2 et au Stockage Blob.
Commande updateMount (dbutils.fs.updateMount)
Semblable à la commande dbutils.fs.mount, mais met à jour un point de montage existant au lieu d’en créer un nouveau. Retourne une erreur si le point de montage n’est pas présent.
Pour afficher l’aide de cette commande, exécutez dbutils.fs.help("updateMount").
Avertissement
Pour éviter les erreurs, ne modifiez jamais un point de montage quand d’autres travaux le lisent ou y écrivent. Après avoir modifié un montage, exécutez toujours dbutils.fs.refreshMounts() sur tous les autres clusters en cours d’exécution pour propager les mises à jour de montage. Consultez la section Commande refreshMounts (dbutils.fs.refreshMounts).
Cette commande est disponible dans Databricks Runtime 10.4 LTS et versions ultérieures.
Python
dbutils.fs.updateMount(
source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
mount_point = "/mnt/<mount-name>",
extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})
Scala
dbutils.fs.updateMount(
source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net/<directory-name>",
mountPoint = "/mnt/<mount-name>",
extraConfigs = Map("<conf-key>" -> dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")))
Utilitaire jobs (dbutils.jobs)
Sous-utilitaires : taskValues
Remarque
Cet utilitaire est disponible uniquement pour Python.
L’utilitaire de travaux vous permet de tirer parti des fonctionnalités de travaux. Pour afficher l’aide de cet utilitaire, exécutez dbutils.jobs.help().
Provides utilities for leveraging jobs features.
taskValues: TaskValuesUtils -> Provides utilities for leveraging job task values
Sous-utilitaire taskValues (dbutils.jobs.taskValues)
Remarque
Ce sous-utilitaire est disponible uniquement pour Python.
Fournit des commandes pour tirer parti des valeurs de tâche d’un travail.
Utilisez ce sous-utilitaire pour définir et obtenir des valeurs arbitraires pendant l’exécution d’un travail. Ces valeurs sont appelées valeurs de tâche. Vous pouvez accéder aux valeurs de tâche dans les tâches en aval dans la même exécution de travail. Par exemple, vous pouvez communiquer des identificateurs ou des métriques, comme des informations sur l’évaluation d’un modèle Machine Learning, entre différentes tâches lors de l’exécution d’un travail. Chaque tâche peut définir plusieurs valeurs de tâche, les obtenir ou les deux. Chaque valeur de tâche a une clé unique au sein de la même tâche. Cette clé unique est appelée clé de la valeur de tâche. Une valeur de tâche est accessible avec le nom de la tâche et la clé de la valeur de tâche.
Pour afficher l’aide de ce sous-utilitaire, exécutez dbutils.jobs.taskValues.help().
Commande get (dbutils.jobs.taskValues.get)
Remarque
Cette commande est disponible uniquement pour Python.
Dans Databricks Runtime 10.4 et versions antérieures, si get ne parvient pas à trouver la tâche, une erreur Py4JJavaError est déclenchée au lieu d’une erreur ValueError.
Obtient le contenu de la valeur de tâche spécifiée pour la tâche spécifiée dans l’exécution du travail en cours.
Pour afficher l’aide de cette commande, exécutez dbutils.jobs.taskValues.help("get").
Par exemple :
dbutils.jobs.taskValues.get(taskKey = "my-task", \
key = "my-key", \
default = 7, \
debugValue = 42)
Dans l’exemple précédent :
taskKeyest le nom de la tâche qui définit la valeur de la tâche. Si la commande ne parvient pas à trouver cette tâche, une erreurValueErrorest déclenchée.keyest le nom de la clé de la valeur de tâche que vous définissez avec la commande set (dbutils.jobs.taskValues.set). Si la commande ne parvient pas à trouver la clé de la valeur de cette tâche, une erreurValueErrorest déclenchée (sauf si la valeurdefaultest spécifiée).defaultest une valeur facultative retournée sikeyest introuvable.defaultne peut pas êtreNone.debugValueest une valeur facultative retournée si vous essayez d’obtenir la valeur de tâche à partir d’un notebook qui s’exécute en dehors d’un travail. Cela peut être utile lors du débogage lorsque vous souhaitez exécuter votre notebook manuellement et retourner une valeur au lieu de déclencher une erreurTypeErrorpar défaut.debugValuene peut pas êtreNone.
Si vous essayez d’obtenir une valeur de tâche à partir d’un notebook qui s’exécute en dehors d’un travail, cette commande déclenche une erreur TypeError par défaut. Toutefois, si l’argument debugValue est spécifié dans la commande, la valeur de debugValue est retournée au lieu de déclencher une erreur TypeError.
Commande set (dbutils.jobs.taskValues.set)
Remarque
Cette commande est disponible uniquement pour Python.
Définit ou met à jour une valeur de tâche. Vous pouvez définir jusqu’à 250 valeurs de tâches pour l’exécution d’un travail.
Pour afficher l’aide de cette commande, exécutez dbutils.jobs.taskValues.help("set").
Voici quelques exemples :
dbutils.jobs.taskValues.set(key = "my-key", \
value = 5)
dbutils.jobs.taskValues.set(key = "my-other-key", \
value = "my other value")
Dans les exemples précédents :
keyest la clé de la valeur de la tâche. Cette clé doit être unique à la tâche. Autrement dit, si deux tâches différentes définissent chacune une valeur de tâche avec la cléK, il s’agit de deux valeurs de tâche différentes qui ont la même cléK.valueest la valeur pour la clé de valeur de cette tâche. Cette commande doit être en mesure de représenter la valeur en interne au format JSON. La taille de la représentation JSON de la valeur ne peut pas dépasser 48 Kio.
Si vous essayez de définir une valeur de tâche à partir d’un notebook qui s’exécute en dehors d’un travail, cette commande n’exécute aucune action.
Utilitaire library (dbutils.library)
La plupart des méthodes du sous-module dbutils.library sont déconseillées. Consultez utilitaire bibliothèque (dbutils.library) (hérité).
Vous devrez peut-être redémarrer par programme le processus Python sur Azure Databricks pour vous assurer que les bibliothèques installées localement ou mises à niveau fonctionnent correctement dans le noyau Python pour votre SparkSession actuelle. Pour ce faire, exécutez la commande dbutils.library.restartPython. Consultez Redémarrer le processus Python sur Azure Databricks.
Utilitaire notebook (dbutils.notebook)
L’utilitaire Notebook vous permet de chaîner des blocs-notes et d’agir sur leurs résultats. Consultez Exécuter un notebook Databricks à partir d’un autre notebook.
Pour répertorier les commandes disponibles, exécutez dbutils.notebook.help().
exit(value: String): void -> This method lets you exit a notebook with a value
run(path: String, timeoutSeconds: int, arguments: Map): String -> This method runs a notebook and returns its exit value.
Commande exit (dbutils.notebook.exit)
Quitte un notebook avec une valeur.
Pour afficher l’aide de cette commande, exécutez dbutils.notebook.help("exit").
Cet exemple quitte le bloc-notes avec la valeur Exiting from My Other Notebook.
Python
dbutils.notebook.exit("Exiting from My Other Notebook")
# Notebook exited: Exiting from My Other Notebook
R
dbutils.notebook.exit("Exiting from My Other Notebook")
# Notebook exited: Exiting from My Other Notebook
Scala
dbutils.notebook.exit("Exiting from My Other Notebook")
// Notebook exited: Exiting from My Other Notebook
Notes
Si l’exécution a une requête avec un flux structuré en cours d’exécution en arrière-plan, l’appel dbutils.notebook.exit() n’arrête pas l’exécution. L’exécution continue à s’exécuter tant que la requête est en cours d’exécution en arrière-plan. Vous pouvez arrêter la requête en cours d’exécution en arrière-plan en cliquant sur Annuler dans la cellule de la requête ou en exécutant query.stop(). Lorsque la requête s’arrête, vous pouvez arrêter l’exécution avec dbutils.notebook.exit().
Commande run (dbutils.notebook.run)
Exécute un notebook et renvoie sa valeur de sortie. Le bloc-notes s’exécutera dans le cluster actuel par défaut.
Notes
La longueur maximale de la valeur de chaîne renvoyée par la commande run est de 5 Mo. Consultez obtenir la sortie d’une seule exécution (GET /jobs/runs/get-output).
Pour afficher l’aide de cette commande, exécutez dbutils.notebook.help("run").
Cet exemple exécute un bloc-notes nommé My Other Notebook au même emplacement que le bloc-notes appelant. Le bloc-notes appelé se termine par la ligne de code dbutils.notebook.exit("Exiting from My Other Notebook"). Si l’exécution du bloc-notes appelé ne se termine pas dans les 60 secondes, une exception est levée.
Python
dbutils.notebook.run("My Other Notebook", 60)
# Out[14]: 'Exiting from My Other Notebook'
Scala
dbutils.notebook.run("My Other Notebook", 60)
// res2: String = Exiting from My Other Notebook
Utilitaire secrets (dbutils.secrets)
Commandes: get, getBytes, list, listScopes
L’utilitaire secrets vous permet de stocker et d’accéder à des informations d’identification sensibles sans les rendre visibles dans les blocs-notes. Consultez gestion des secrets et Utilisez les secrets dans un Notebook. Pour répertorier les commandes disponibles, exécutez dbutils.secrets.help().
get(scope: String, key: String): String -> Gets the string representation of a secret value with scope and key
getBytes(scope: String, key: String): byte[] -> Gets the bytes representation of a secret value with scope and key
list(scope: String): Seq -> Lists secret metadata for secrets within a scope
listScopes: Seq -> Lists secret scopes
Commande get (dbutils.secrets.get)
Obtient la représentation sous forme de chaîne d’une valeur secrète pour la portée et la clé des secrets spécifiés.
Avertissement
Les administrateurs, les créateurs de secrets et les utilisateurs autorisés peuvent lire les secrets Azure Databricks. Même si Azure Databricks fait un effort pour supprimer les valeurs secrètes susceptibles d’être affichées dans des notebooks, il n’est pas possible d’empêcher ces utilisateurs de lire les secrets. Pour plus d’informations, consultez Suppression des secrets.
Pour afficher l’aide de cette commande, exécutez dbutils.secrets.help("get").
Cet exemple obtient la représentation sous forme de chaîne de la valeur secrète pour l’étendue nommée my-scope et la clé nommée my-key .
Python
dbutils.secrets.get(scope="my-scope", key="my-key")
# Out[14]: '[REDACTED]'
R
dbutils.secrets.get(scope="my-scope", key="my-key")
# [1] "[REDACTED]"
Scala
dbutils.secrets.get(scope="my-scope", key="my-key")
// res0: String = [REDACTED]
Commande getBytes (dbutils.secrets.getBytes)
Obtient la représentation sous forme de chaîne d’une valeur secrète pour la portée et la clé spécifiés.
Pour afficher l’aide de cette commande, exécutez dbutils.secrets.help("getBytes").
Cet exemple obtient la représentation sous forme d’octet de la valeur secrète (dans cet exemple, a1!b2@c3#) pour l’étendue nommée my-scope et la clé nommée my-key.
Python
dbutils.secrets.getBytes(scope="my-scope", key="my-key")
# Out[1]: b'a1!b2@c3#'
R
dbutils.secrets.getBytes(scope="my-scope", key="my-key")
# [1] 61 31 21 62 32 40 63 33 23
Scala
dbutils.secrets.getBytes(scope="my-scope", key="my-key")
// res1: Array[Byte] = Array(97, 49, 33, 98, 50, 64, 99, 51, 35)
Commande list (dbutils.secrets.list)
Répertorie les métadonnées pour les secrets dans l’étendue spécifiée.
Pour afficher l’aide de cette commande, exécutez dbutils.secrets.help("list").
Cet exemple répertorie les métadonnées pour les secrets dans l’étendue nommée my-scope.
Python
dbutils.secrets.list("my-scope")
# Out[10]: [SecretMetadata(key='my-key')]
R
dbutils.secrets.list("my-scope")
# [[1]]
# [[1]]$key
# [1] "my-key"
Scala
dbutils.secrets.list("my-scope")
// res2: Seq[com.databricks.dbutils_v1.SecretMetadata] = ArrayBuffer(SecretMetadata(my-key))
Commande listScopes (dbutils.secrets.listScopes)
Répertorie les étendues disponibles.
Pour afficher l’aide de cette commande, exécutez dbutils.secrets.help("listScopes").
Cet exemple répertorie les étendues disponibles.
Python
dbutils.secrets.listScopes()
# Out[14]: [SecretScope(name='my-scope')]
R
dbutils.secrets.listScopes()
# [[1]]
# [[1]]$name
# [1] "my-scope"
Scala
dbutils.secrets.listScopes()
// res3: Seq[com.databricks.dbutils_v1.SecretScope] = ArrayBuffer(SecretScope(my-scope))
Utilitaire widgets (dbutils.widgets)
Commandes: combobox, dropdown, get, getArgument, multiselect, remove, removeAll, text
L’utilitaire widgets vous permet de paramétrer les blocs-notes. Consultez Widgets Databricks.
Pour répertorier les commandes disponibles, exécutez dbutils.widgets.help().
combobox(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a combobox input widget with a given name, default value and choices
dropdown(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a dropdown input widget a with given name, default value and choices
get(name: String): String -> Retrieves current value of an input widget
getAll: map -> Retrieves a map of all widget names and their values
getArgument(name: String, optional: String): String -> (DEPRECATED) Equivalent to get
multiselect(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a multiselect input widget with a given name, default value and choices
remove(name: String): void -> Removes an input widget from the notebook
removeAll: void -> Removes all widgets in the notebook
text(name: String, defaultValue: String, label: String): void -> Creates a text input widget with a given name and default value
Commande combobox (dbutils.widgets.combobox)
Crée et affiche un widget de zone de liste déroulante avec le nom de programmation, la valeur par défaut, les choix et l’étiquette facultative spécifiés.
Pour afficher l’aide de cette commande, exécutez dbutils.widgets.help("combobox").
Cet exemple crée et affiche un widget de zone de liste déroulante avec le nom de programmation fruits_combobox. Elle offre les choix apple , banana , coconut et dragon fruit et la valeur initiale de banana. Ce widget de zone de liste déroulante a une étiquette Fruits associée. Cet exemple se termine en imprimant la valeur initiale du widget de zone de liste déroulante, banana.
Python
dbutils.widgets.combobox(
name='fruits_combobox',
defaultValue='banana',
choices=['apple', 'banana', 'coconut', 'dragon fruit'],
label='Fruits'
)
print(dbutils.widgets.get("fruits_combobox"))
# banana
R
dbutils.widgets.combobox(
name='fruits_combobox',
defaultValue='banana',
choices=list('apple', 'banana', 'coconut', 'dragon fruit'),
label='Fruits'
)
print(dbutils.widgets.get("fruits_combobox"))
# [1] "banana"
Scala
dbutils.widgets.combobox(
"fruits_combobox",
"banana",
Array("apple", "banana", "coconut", "dragon fruit"),
"Fruits"
)
print(dbutils.widgets.get("fruits_combobox"))
// banana
SQL
CREATE WIDGET COMBOBOX fruits_combobox DEFAULT "banana" CHOICES SELECT * FROM (VALUES ("apple"), ("banana"), ("coconut"), ("dragon fruit"))
SELECT :fruits_combobox
-- banana
Commande dropdown (dbutils.widgets.dropdown)
Crée et affiche un widget de liste déroulante avec le nom programmatique spécifié, la valeur par défaut, les choix et l'étiquette facultative.
Pour afficher l’aide de cette commande, exécutez dbutils.widgets.help("dropdown").
Cet exemple crée et affiche un widget de zone de liste déroulante avec le nom de programmation toys_dropdown. Elle offre les choix alphabet blocks , basketball , cape et doll et la valeur initiale de basketball. Ce widget de liste déroulante a une étiquette Toys qui l’accompagne. Cet exemple se termine en imprimant la valeur initiale du widget de zone de liste déroulante, basketball.
Python
dbutils.widgets.dropdown(
name='toys_dropdown',
defaultValue='basketball',
choices=['alphabet blocks', 'basketball', 'cape', 'doll'],
label='Toys'
)
print(dbutils.widgets.get("toys_dropdown"))
# basketball
R
dbutils.widgets.dropdown(
name='toys_dropdown',
defaultValue='basketball',
choices=list('alphabet blocks', 'basketball', 'cape', 'doll'),
label='Toys'
)
print(dbutils.widgets.get("toys_dropdown"))
# [1] "basketball"
Scala
dbutils.widgets.dropdown(
"toys_dropdown",
"basketball",
Array("alphabet blocks", "basketball", "cape", "doll"),
"Toys"
)
print(dbutils.widgets.get("toys_dropdown"))
// basketball
SQL
CREATE WIDGET DROPDOWN toys_dropdown DEFAULT "basketball" CHOICES SELECT * FROM (VALUES ("alphabet blocks"), ("basketball"), ("cape"), ("doll"))
SELECT :toys_dropdown
-- basketball
Commande get (dbutils.widgets.get)
Obtient la valeur actuelle du widget avec le nom de programmation spécifié. Ce nom de programmation peut être :
- Nom d’un widget personnalisé dans le bloc-notes, par exemple
fruits_comboboxoutoys_dropdown. - Nom d’un paramètre personnalisé passé au bloc-notes dans le cadre d’une tâche de bloc-notes, par exemple
nameouage. Pour plus d’informations, consultez la couverture des paramètres pour les tâches du bloc-notes dans l’interface utilisateur créer un travail ou lenotebook_paramschamp de l’opération déclencher une nouvelle exécution de travail (POST /jobs/run-now) dans l’API tâches.
Pour afficher l’aide de cette commande, exécutez dbutils.widgets.help("get").
Cet exemple obtient la valeur du widget qui a le nom fruits_combobox de programmation.
Python
dbutils.widgets.get('fruits_combobox')
# banana
R
dbutils.widgets.get('fruits_combobox')
# [1] "banana"
Scala
dbutils.widgets.get("fruits_combobox")
// res6: String = banana
SQL
SELECT :fruits_combobox
-- banana
Cet exemple obtient la valeur du paramètre de tâche Notebook qui a le nom age de programmation. Ce paramètre a été défini sur lors de 35 l’exécution de la tâche du bloc-notes associée.
Python
dbutils.widgets.get('age')
# 35
R
dbutils.widgets.get('age')
# [1] "35"
Scala
dbutils.widgets.get("age")
// res6: String = 35
SQL
SELECT :age
-- 35
Commande getAll (dbutils.widgets.getAll)
Obtient un mappage de tous les noms de widget actuels et leurs valeurs. Cela peut être particulièrement utile pour transmettre rapidement des valeurs de widget à une requête spark.sql().
Cette commande est disponible dans Databricks Runtime 13.3 LTS et versions ultérieures. Elle est disponible uniquement pour Python et Scala.
Pour afficher l’aide de cette commande, exécutez dbutils.widgets.help("getAll").
Cet exemple obtient la carte des valeurs du widget et la transmet en tant qu’arguments de paramètre dans une requête SQL Spark.
Python
df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()
# Query output
Scala
val df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()
// res6: Query output
Commande getArgument (dbutils.widgets.getArgument)
Obtient la valeur actuelle du widget avec le nom de programmation spécifié. Si le widget n’existe pas, un message facultatif peut être retourné.
Notes
Cette commande est déconseillée. Utilisez dbutils.widgets.get à la place.
Pour afficher l’aide de cette commande, exécutez dbutils.widgets.help("getArgument").
Cet exemple obtient la valeur du widget qui a le nom fruits_combobox de programmation. Si ce widget n’existe pas, le message Error: Cannot find fruits combobox est retourné.
Python
dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')
# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# Out[3]: 'banana'
R
dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')
# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# [1] "banana"
Scala
dbutils.widgets.getArgument("fruits_combobox", "Error: Cannot find fruits combobox")
// command-1234567890123456:1: warning: method getArgument in trait WidgetsUtils is deprecated: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
// dbutils.widgets.getArgument("fruits_combobox", "Error: Cannot find fruits combobox")
// ^
// res7: String = banana
Commande multiselect (dbutils.widgets.multiselect)
Crée et affiche un widget multisélection avec le nom programmatique, la valeur par défaut, les choix et l'étiquette facultative spécifiés.
Pour afficher l’aide de cette commande, exécutez dbutils.widgets.help("multiselect").
Cet exemple crée et affiche un widget multi-sélection avec le nom de programmation days_multiselect. Cela offre les choix Monday à Sunday et est réglé sur la valeur initiale de Tuesday. Ce widget multiselect a une étiquette Days of the Week qui l’accompagne. Cet exemple se termine par l'impression de la valeur initiale du widget multiselect, Tuesday.
Python
dbutils.widgets.multiselect(
name='days_multiselect',
defaultValue='Tuesday',
choices=['Monday', 'Tuesday', 'Wednesday', 'Thursday',
'Friday', 'Saturday', 'Sunday'],
label='Days of the Week'
)
print(dbutils.widgets.get("days_multiselect"))
# Tuesday
R
dbutils.widgets.multiselect(
name='days_multiselect',
defaultValue='Tuesday',
choices=list('Monday', 'Tuesday', 'Wednesday', 'Thursday',
'Friday', 'Saturday', 'Sunday'),
label='Days of the Week'
)
print(dbutils.widgets.get("days_multiselect"))
# [1] "Tuesday"
Scala
dbutils.widgets.multiselect(
"days_multiselect",
"Tuesday",
Array("Monday", "Tuesday", "Wednesday", "Thursday",
"Friday", "Saturday", "Sunday"),
"Days of the Week"
)
print(dbutils.widgets.get("days_multiselect"))
// Tuesday
SQL
CREATE WIDGET MULTISELECT days_multiselect DEFAULT "Tuesday" CHOICES SELECT * FROM (VALUES ("Monday"), ("Tuesday"), ("Wednesday"), ("Thursday"), ("Friday"), ("Saturday"), ("Sunday"))
SELECT :days_multiselect
-- Tuesday
Commande remove (dbutils.widgets.remove)
Supprime le widget avec le nom de programmation spécifié.
Pour afficher l’aide de cette commande, exécutez dbutils.widgets.help("remove").
Important
Si vous ajoutez une commande pour supprimer un widget, vous ne pouvez pas ajouter une commande subséquente pour créer un widget dans la même cellule. Vous devez créer le widget dans une autre cellule.
Cet exemple supprime le widget avec le nom fruits_combobox de programmation.
Python
dbutils.widgets.remove('fruits_combobox')
R
dbutils.widgets.remove('fruits_combobox')
Scala
dbutils.widgets.remove("fruits_combobox")
SQL
REMOVE WIDGET fruits_combobox
Commande removeAll (dbutils.widgets.removeAll)
Supprime tous les widgets du bloc-notes.
Pour afficher l’aide de cette commande, exécutez dbutils.widgets.help("removeAll").
Important
Si vous ajoutez une commande pour supprimer tous les widgets, vous ne pouvez pas ajouter une commande ultérieure pour créer des widgets dans la même cellule. Vous devez créer le widget dans une autre cellule.
Cet exemple supprime tous les widgets du bloc-notes.
Python
dbutils.widgets.removeAll()
R
dbutils.widgets.removeAll()
Scala
dbutils.widgets.removeAll()
Commande text (dbutils.widgets.text)
Crée et affiche un widget texte avec le nom programmatique spécifié, la valeur par défaut et l'étiquette facultative.
Pour afficher l’aide de cette commande, exécutez dbutils.widgets.help("text").
Cet exemple crée et affiche un widget de texte avec le nom de programme your_name_text. Elle est définie sur la valeur initiale de Enter your name. Ce widget de texte a une étiquette Your name qui l’accompagne. Cet exemple se termine par l'impression de la valeur initiale du widget texte, Enter your name.
Python
dbutils.widgets.text(
name='your_name_text',
defaultValue='Enter your name',
label='Your name'
)
print(dbutils.widgets.get("your_name_text"))
# Enter your name
R
dbutils.widgets.text(
name='your_name_text',
defaultValue='Enter your name',
label='Your name'
)
print(dbutils.widgets.get("your_name_text"))
# [1] "Enter your name"
Scala
dbutils.widgets.text(
"your_name_text",
"Enter your name",
"Your name"
)
print(dbutils.widgets.get("your_name_text"))
// Enter your name
SQL
CREATE WIDGET TEXT your_name_text DEFAULT "Enter your name"
SELECT :your_name_text
-- Enter your name
Bibliothèque d’API Databricks Utilities
Important
La bibliothèque d’API Databricks Utilities (dbutils-api) est déconseillée. Bien que la bibliothèque dbutils-api soit toujours disponible, Databricks ne prévoit aucun développement de nouvelles fonctionnalités pour elle.
Databricks vous recommande d’utiliser l’une des bibliothèques suivantes à la place :
Pour accélérer le développement d’applications, il peut être utile de compiler, de générer et de tester des applications avant de les déployer en tant que tâches de production. Pour vous permettre de compiler les utilitaires Databricks, Databricks fournit la bibliothèque dbutils-api. Vous pouvez télécharger la bibliothèque dbutils-api à partir de la page Web de l'API DBUtils sur le site Web du référentiel Maven ou inclure la bibliothèque en ajoutant une dépendance à votre fichier de construction :
SBT
libraryDependencies += "com.databricks" % "dbutils-api_TARGET" % "VERSION"Maven
<dependency> <groupId>com.databricks</groupId> <artifactId>dbutils-api_TARGET</artifactId> <version>VERSION</version> </dependency>Gradle
compile 'com.databricks:dbutils-api_TARGET:VERSION'
Remplacez TARGET par la cible souhaitée (par exemple 2.12) et VERSION par la version souhaitée (par exemple 0.0.5). Pour obtenir la liste des cibles et des versions disponibles, consultez la page Web de l'API DBUtils sur le site Web du référentiel Maven.
Une fois que vous avez créé votre application sur cette bibliothèque, vous pouvez déployer l’application.
Important
La bibliothèque dbutils-api vous permet de compiler localement une application qui utilise dbutils, mais pas de l'exécuter. Pour exécuter l’application, vous devez la déployer dans Azure Databricks.
Limites
L’appel dbutils à l’intérieur des exécuteurs peut produire des résultats inattendus ou entraîner des erreurs.
Si vous devez exécuter des opérations de système de fichiers sur des exécuteurs à l’aide de dbutils, plusieurs solutions plus rapides et plus évolutives sont disponibles :
- Pour les opérations de copie ou de déplacement de fichiers, vous pouvez vérifier une option plus rapide d’exécution des opérations de système de fichiers décrite dans paralléliser les opérations de système de fichiers.
- Pour les opérations de liste et de suppression de système de fichiers, vous pouvez faire référence à la liste parallèle et aux méthodes de suppression à l’aide de Spark dans Comment répertorier et supprimer des fichiers plus rapidement dans Databricks.
Pour plus d’informations sur les exécuteurs, consultez vue d’ensemble du mode cluster sur le site Web Apache Spark.
Commentaires
Bientôt disponible : Tout au long de l’année 2024, nous abandonnerons progressivement le mécanisme de retour d’information GitHub Issues pour le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez : https://aka.ms/ContentUserFeedback.
Soumettre et afficher des commentaires pour