Référence des utilitaires Databricks (`dbutils`)

Article
01/31/2025

Cet article contient des informations de référence pour Databricks Utilities (dbutils). Les utilitaires fournissent des commandes qui vous permettent d’utiliser votre environnement Databricks à partir de notebooks. Par exemple, vous pouvez gérer les fichiers et le stockage d’objets et utiliser des secrets. les dbutils sont disponibles dans les notebooks Python, R et Scala.

Remarque

dbutils prend uniquement en charge les environnements de calcul qui utilisent DBFS.

modules utilitaires

Le tableau suivant répertorie les modules Databricks Utilities, que vous pouvez récupérer à l’aide de dbutils.help().

Module	Description
données	Utilitaires pour comprendre et interagir avec des jeux de données (EXPERIMENTAL)
fs	Utilitaires pour accéder au système de fichiers Databricks (DBFS)
travaux	Utilitaires pour tirer parti des fonctionnalités de travail
bibliothèque	Obsolète. Utilitaires pour gérer les bibliothèques à l’étendue de la session
notebook	Utilitaires pour gérer le flux de contrôle des notebooks (EXPÉRIMENTAL)
secrets	Utilitaires pour l'utilisation des secrets dans les carnets
widgets	Utilitaires de paramétrage des notebooks.
api	Utilitaires de gestion des builds d’application

Aide relative aux commandes

Pour répertorier les commandes d’un module utilitaire, ainsi qu’une brève description de chaque commande, ajoutez .help() après le nom du module utilitaire. L’exemple suivant répertorie les commandes disponibles pour l’utilitaire notebook :

dbutils.notebook.help()

The notebook module.

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

Pour générer de l’aide pour une commande, exécutez dbutils.<utility-name>.help("<command-name>"). L’exemple suivant affiche de l’aide pour la commande de copie des utilitaires de système de fichiers, dbutils.fs.cp:

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.

Remarque

Disponible dans Databricks Runtime 9.0 et ultérieur.

L’utilitaire de données vous permet de comprendre et d’interagir avec les jeux de données.

Le tableau suivant répertorie les commandes disponibles pour cet utilitaire, que vous pouvez récupérer à l’aide de dbutils.data.help().

Commande	Description
résumer	Résumer un DataFrame Spark et visualiser les statistiques pour obtenir des insights rapides

Commande summarize (dbutils.data.summarize)

Remarque

Cette fonctionnalité est disponible en préversion publique.

summarize(df: Object, precise: boolean): void

Calcule et affiche les statistiques récapitulatives d’un Apache Spark tableau ou pandas tableau. Cette commande est disponible pour Python, Scala et R.

Important

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 complète 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.

Lorsque precise a 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 precise a 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 située en haut de la sortie de résumé des données indique le mode de l’exécution actuelle.

Exemple

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)

La visualisation utilise la notation SI pour afficher de manière concise des valeurs numériques inférieures à 0,01 ou supérieures à 1 000. 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)

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.

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, dbutils.fs.help() affiche l’option extraConfigs pour dbutils.fs.mount(). Toutefois, dans Python, vous utiliseriez le mot clé extra_configs.

Le tableau suivant répertorie les commandes disponibles pour cet utilitaire, que vous pouvez récupérer à l’aide de dbutils.fs.help().

Commande	Description
cp	Copie un fichier ou un répertoire, éventuellement sur FileSystems
head	Retourne jusqu’aux premiers octets « maxBytes » du fichier donné en tant que chaîne encodée en UTF-8
ls	Répertorie le contenu d’un répertoire
mkdirs	Crée le répertoire donné s’il n’existe pas, et crée également les répertoires parents nécessaires
montage	Monte le répertoire source donné dans DBFS au point de montage donné
montages	Affiche des informations sur ce qui est monté dans DBFS
mv	Déplace un fichier ou un répertoire, éventuellement entre différents systèmes de fichiers.
put	Écrit la chaîne donnée dans un fichier encodé au format UTF-8
refreshMounts	Force tous les ordinateurs de ce cluster à actualiser leur cache de montage, en s’assurant qu’ils reçoivent les informations les plus récentes
rm	Supprime un fichier ou un répertoire
unmount	Supprime un point de montage DBFS
updateMount	Similaire à mount(), mais met à jour un point de montage existant au lieu de en créer un nouveau

Conseil

Dans les notebooks, vous pouvez utiliser la %fs commande 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.

Commande cp (dbutils.fs.cp)

cp(from: String, to: String, recurse: boolean = false): boolean

Copie un fichier ou un répertoire, éventuellement entre des systèmes de fichiers.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.fs.help("cp")

Exemple

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)

head(file: String, maxBytes: int = 65536): String

Retourne jusqu’au nombre maximal d’octets spécifié dans le fichier donné. Les octets sont retournés sous la forme d’une chaîne encodée en UTF-8.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.fs.help("head")

Exemple

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)

ls(dir: String): Seq

Copier le contenu d’un répertoire.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.fs.help("ls")

Exemple

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)

mkdirs(dir: String): boolean

Crée le répertoire donné s’il n’existe pas. Crée également les répertoires parents nécessaires.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.fs.help("mkdirs")

Exemple

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)

mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean

Monte le répertoire source spécifié dans DBFS au point de montage spécifié.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.fs.help("mount")

Exemple

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)

mounts: Seq

Affiche des informations sur ce qui est actuellement monté dans DBFS.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.fs.help("mounts")

Exemple

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)

mv(from: String, to: String, recurse: boolean = false): boolean

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 complète de cette commande, exécutez :

dbutils.fs.help("mv")

Exemple

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)

put(file: String, contents: String, overwrite: boolean = false): boolean

Écrit la chaîne spécifiée dans un fichier. La chaîne est encodée en UTF-8.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.fs.help("put")

Exemple

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)

refreshMounts: boolean

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 complète de cette commande, exécutez :

dbutils.fs.help("refreshMounts")

Exemple

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)

rm(dir: String, recurse: boolean = false): boolean

Supprime un fichier ou un répertoire et, éventuellement, tout son contenu. Si un fichier est spécifié, le recurse paramètre est ignoré. Si un répertoire est spécifié, une erreur se produit lorsqu’elle recurse est désactivée et que le répertoire n’est pas vide.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.fs.help("rm")

Exemple

Cet exemple supprime l’intégralité du répertoire /Volumes/main/default/my-volume/my-data/ , y compris son contenu.

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)

unmount(mountPoint: String): boolean

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 complète de cette commande, exécutez :

dbutils.fs.help("unmount")

Exemple

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)

updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean

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.

Avertissement

Cette commande est disponible dans Databricks Runtime 10.4 LTS et versions ultérieures.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.fs.help("updateMount")

Exemple

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)

Fournit des utilitaires pour tirer parti des fonctionnalités de travaux.

Remarque

Cet utilitaire est disponible uniquement pour Python.

Le tableau suivant répertorie les modules disponibles pour cet utilitaire, que vous pouvez récupérer à l’aide de dbutils.jobs.help().

Sous-module	Description
taskValues	Fournit des utilitaires pour tirer parti des valeurs de tâche d’un travail

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 une exécution de travail. Ces valeurs sont appelées valeurs de tâche. Toute tâche peut obtenir des valeurs définies par des tâches en amont et définir des valeurs pour les tâches en aval à utiliser.

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. Vous pouvez l’utiliser pour transmettre des informations en aval de la tâche à la tâche au sein de la même exécution de travail. Par exemple, vous pouvez transmettre des identificateurs ou des métriques, tels que des informations sur l’évaluation d’un modèle Machine Learning, entre différentes tâches au sein d’une exécution de travail.

Le tableau suivant répertorie les commandes disponibles pour cette sous-utilisation, que vous pouvez récupérer à l’aide de dbutils.jobs.taskValues.help().

Commande	Description
obtenir	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.
définir	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.

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.

get(taskKey: String, key: String, default: int, debugValue: int): Seq

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 complète de cette commande, exécutez :

dbutils.jobs.taskValues.help("get")

Exemple

Par exemple :

dbutils.jobs.taskValues.get(taskKey    = "my-task", \
                            key        = "my-key", \
                            default    = 7, \
                            debugValue = 42)

Dans l’exemple précédent :

taskKey est 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 erreur ValueError est déclenchée.
key est 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 erreur ValueError est déclenchée (sauf si la valeur default est spécifiée).
default est une valeur facultative retournée si key est introuvable. default ne peut pas être None.
debugValue est 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 erreur TypeError par défaut. debugValue ne peut pas être None.

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.

set(key: String, value: String): boolean

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 complète de cette commande, exécutez :

dbutils.jobs.taskValues.help("set")

Exemple

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 :

key est 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.
value est 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 Orchestrer des notebooks et modulariser le code dans les notebooks.

Le tableau suivant répertorie les commandes disponibles pour cet utilitaire, que vous pouvez récupérer à l’aide de dbutils.notebook.help().

Commande	Description
quitter	Quitte un notebook avec une valeur
exécuter	Exécute un notebook et renvoie sa valeur de sortie

Commande exit (dbutils.notebook.exit)

exit(value: String): void

Quitte un notebook avec une valeur.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.notebook.help("exit")

Exemple

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

Remarque

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 continuera à s’exécuter tant que la requête s’exécute 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)

run(path: String, timeoutSeconds: int, arguments: Map): String

Exécute un notebook et renvoie sa valeur de sortie. Le bloc-notes s’exécutera dans le cluster actuel par défaut.

Remarque

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 complète de cette commande, exécutez :

dbutils.notebook.help("run")

Exemple

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)

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 la gestion des secrets et l’étape 3 : Utiliser les secrets dans un bloc-notes.

Le tableau suivant répertorie les commandes disponibles pour cet utilitaire, que vous pouvez récupérer à l’aide de dbutils.secrets.help().

Commande	Description
obtenir	Obtient la représentation sous forme de chaîne d’une valeur secrète avec étendue et clé
getBytes	Obtient la représentation en octets d’une valeur secrète avec l’étendue et la clé
lister	Répertorie les métadonnées secrètes pour les secrets dans une étendue
listScopes	Répertorie les étendues de secrets

Commande get (dbutils.secrets.get)

get(scope: String, key: String): String

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 complète de cette commande, exécutez :

dbutils.secrets.help("get")

Exemple

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)

getBytes(scope: String, key: String): byte[]

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 complète de cette commande, exécutez :

dbutils.secrets.help("getBytes")

Exemple

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)

list(scope: String): Seq

Répertorie les métadonnées pour les secrets dans l’étendue spécifiée.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.secrets.help("list")

Exemple

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)

listScopes: Seq

Répertorie les étendues disponibles.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.secrets.help("listScopes")

Exemple

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)

L’utilitaire widgets vous permet de paramétrer les blocs-notes. Consultez Widgets Databricks.

Le tableau suivant répertorie les commandes disponibles pour cet utilitaire, que vous pouvez récupérer à l’aide de dbutils.widgets.help().

Commande	Description
combobox	Crée un widget de zone de liste déroulante avec un nom donné, une valeur par défaut et des choix.
liste déroulante	Crée un widget d’entrée de liste déroulante avec un nom, une valeur par défaut et des choix donnés
obtenir	Récupère la valeur actuelle d’un widget d’entrée
getAll	Récupère une carte de tous les noms de widgets et de leurs valeurs
getArgument	Déprécié. Équivaut à « obtenir »
sélection multiple	Crée un widget d’entrée à sélection multiple avec un nom, une valeur par défaut et des choix donnés
supprimer	Supprime un widget d’entrée du notebook
removeAll	Supprime tous les widgets du bloc-notes
texte	Crée un widget d’entrée de texte avec un nom donné et une valeur par défaut

Commande combobox (dbutils.widgets.combobox)

combobox(name: String, defaultValue: String, choices: Seq, label: String): void

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 complète de cette commande, exécutez :

dbutils.widgets.help("combobox")

Exemple

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

dropdown(name: String, defaultValue: String, choices: Seq, label: String): void

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 complète de cette commande, exécutez :

dbutils.widgets.help("dropdown")

Exemple

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)

get(name: String): String

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 notebook, par exemple, fruits_combobox ou toys_dropdown.
Nom d’un paramètre personnalisé passé au bloc-notes dans le cadre d’une tâche de bloc-notes, par exemple name ou age. Pour plus d’informations, consultez la couverture des paramètres des tâches du notebook dans l’IU des projets ou le champ notebook_params de l’opération Déclencher l'exécution d’un nouveau projet (POST /jobs/run-now) dans l’API des projets.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.widgets.help("get")

Exemple

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)

getAll: map

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 complète de cette commande, exécutez :

dbutils.widgets.help("getAll")

Exemple

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)

getArgument(name: String, optional: String): String

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é.

Remarque

Cette commande est déconseillée. Utilisez dbutils.widgets.get à la place.

Pour afficher l’aide complète de cette commande, exécutez :

dbutils.widgets.help("getArgument")

Exemple

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)

multiselect(name: String, defaultValue: String, choices: Seq, label: String): void

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 complète de cette commande, exécutez :

dbutils.widgets.help("multiselect")

Exemple

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)

remove(name: String): void

Supprime le widget avec le nom de programmation spécifié.

Pour afficher l’aide complète 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.

Exemple

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)

removeAll: void

Supprime tous les widgets du bloc-notes.

Pour afficher l’aide complète 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.

Exemple

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)

text(name: String, defaultValue: String, label: String): void

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 complète de cette commande, exécutez :

dbutils.widgets.help("text")

Exemple

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. Databricks vous recommande d’utiliser l’un des éléments suivants à 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.12et 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 dbutils-api bibliothèque vous permet uniquement de compiler localement une application qui utilise dbutils, et non 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 des erreurs.

Si vous devez exécuter des opérations de système de fichiers sur des exécuteurs à l’aide dbutilsdes exécuteurs, reportez-vous aux méthodes de référencement et de suppression parallèles à l’aide de Spark dans How to list and delete files 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.

Partager via

Référence des utilitaires Databricks (dbutils)

modules utilitaires

Aide relative aux commandes

Utilitaire de données (dbutils.data)

Commande summarize (dbutils.data.summarize)

Exemple

Python

R

Scala

Utilitaire de système de fichiers (dbutils.fs)

Commande cp (dbutils.fs.cp)

Exemple

Python

R

Scala

Commande head (dbutils.fs.head)

Exemple

Python

R

Scala

Commande Is (dbutils.fs.ls)

Exemple

Python

R

Scala

Commande mkdirs (dbutils.fs.mkdirs)

Exemple

Python

R

Scala

Commande mount (dbutils.fs.mount)

Exemple

Python

Scala

Commande mounts (dbutils.fs.mounts)

Exemple

Python

Scala

Commande mv (dbutils.fs.mv)

Exemple

Python

R

Scala

Commande put (dbutils.fs.put)

Exemple

Python

R

Scala

Commande refreshMounts (dbutils.fs.refreshMounts)

Exemple

Python

Scala

Commande rm (dbutils.fs.rm)

Exemple

Python

R

Scala

Commande unmount (dbutils.fs.unmount)

Exemple

Commande updateMount (dbutils.fs.updateMount)

Exemple

Python

Scala

Utilitaire jobs (dbutils.jobs)

Sous-utilitaire taskValues (dbutils.jobs.taskValues)

Commande get (dbutils.jobs.taskValues.get)

Exemple

Commande set (dbutils.jobs.taskValues.set)

Exemple

Utilitaire library (dbutils.library)

Utilitaire notebook (dbutils.notebook)

Commande exit (dbutils.notebook.exit)

Exemple

Python

R

Scala

Commande run (dbutils.notebook.run)

Exemple

Python

Référence des utilitaires Databricks (`dbutils`)