Partager via

Référence des utilitaires Databricks (dbutils)

  • Article

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 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 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)

Commandes : get, set

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 :

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

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 :

  • 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)

Commandes: quitter, exécuter

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_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 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 plus d’informations sur les exécuteurs, consultez vue d’ensemble du mode cluster sur le site Web Apache Spark.