Aller au contenu principal
Dernière mise à jour le

Référence des infrastructures publiques Databricks (dbutils)

Cette page contient une référence pour les utilitaires Databricks (dbutils). Les infrastructures publiques fournissent des modules avec des commandes qui vous permettent de travailler avec votre environnement Databricks depuis des notebooks. Par exemple, vous pouvez gérer les fichiers et le stockage d'objets, et travailler avec des secrets. dbutils sont disponibles dans les notebooks Python, R et Scala.

remarque

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

Modules d'infrastructures publiques​

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

Module

Description

Identifiants

Utilitaires pour interagir avec les informations d'identification dans les Notebooks.

Données

Utilitaires pour comprendre et interagir avec les datasets (EXPÉRIMENTAL)

fs

Utilitaire pour accéder au système de fichiers Databricks (DBFS)

Jobs

Fonctionnalités pour l'exploitation des caractéristiques de Job

Bibliothèque

Obsolète. Outils pour la gestion des bibliothèques de session

meta

Utilitaires pour se connecter au compilateur (EXPERIMENTAL)

Notebook

Utilitaires de gestion du flux de contrôle des notebooks (EXPÉRIMENTAL)

Aperçu

Infrastructures publiques en préversion

secrets

Outils pour exploiter les secrets dans les Notebooks

Widgets

Outils pour paramétrer les Notebook.

API

Utilitaires pour la gestion des versions d'applications

Module

Description

Identifiants

Utilitaires pour interagir avec les informations d'identification dans les Notebooks.

Données

Utilitaires pour comprendre et interagir avec les datasets (EXPÉRIMENTAL)

fs

Utilitaire pour accéder au système de fichiers Databricks (DBFS)

Jobs

Fonctionnalités pour l'exploitation des caractéristiques de Job

Bibliothèque

Obsolète. Outils pour la gestion des bibliothèques de session

meta

Utilitaires pour se connecter au compilateur (EXPERIMENTAL)

Notebook

Utilitaires de gestion du flux de contrôle des notebooks (EXPÉRIMENTAL)

Aperçu

Infrastructures publiques en préversion

secrets

Outils pour exploiter les secrets dans les Notebooks

Widgets

Outils pour paramétrer les Notebook.

API

Utilitaires pour la gestion des versions d'applications

Aide de la commande​

Pour lister les commandes d'un module utilitaire ainsi qu'une courte 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()
Output
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 afficher l'aide d'une commande, exécutez dbutils.<utility-name>.help("<command-name>"). L'exemple suivant affiche l'aide pour la commande de copie des utilitaires du système de fichiers, dbutils.fs.cp:

dbutils.fs.help("cp")
Output
/**
* 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 d'informations d'identification (dbutils.credentials)​

Le module utilitaire d'identifiants contient des commandes pour interagir avec les identifiants au sein des Notebooks. Cet utilitaire n'est utilisable que sur les clusters avec transmission des identifiants activée.

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

Commande

Description

assumeRole

Définit l'ARN du rôle à assumer lors de la recherche d'informations d'identification pour l'authentification auprès de S3.

getServiceCredentialsProvider

Renvoie un fournisseur d'identifiants de service pour l'identifiant de service donné.

afficherRôleActuel

Affiche le rôle actuellement défini.

showRoles

Affiche l'ensemble des rôles assumés possibles.

Commande

Description

assumeRole

Définit l'ARN du rôle à assumer lors de la recherche d'informations d'identification pour l'authentification auprès de S3.

getServiceCredentialsProvider

Renvoie un fournisseur d'identifiants de service pour l'identifiant de service donné.

afficherRôleActuel

Affiche le rôle actuellement défini.

showRoles

Affiche l'ensemble des rôles assumés possibles.

Commande assumeRole (dbutils.credentials.assumeRole)​

assumeRole(role: String): boolean

Définit l'Amazon Resource Name (ARN) du rôle AWS Identity and Access Management (IAM) à endosser lors de la recherche d'informations d'identification pour s'authentifier auprès d'Amazon S3. Après avoir exécuté cette commande, vous pouvez exécuter des commandes d'accès S3, telles que sc.textFile("s3a://my-bucket/my-file.csv") pour accéder à un objet.

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

dbutils.credentials.help("assumeRole")

Exemple​

Python
dbutils.credentials.assumeRole("arn:aws:iam::123456789012:roles/my-role")

# Out[1]: True

commande getServiceCredentialsProvider (dbutils.credentials.getServiceCredentialsProvider)​

getServiceCredentialsProvider(credentialName: String): Object

Renvoie un fournisseur d'identifiants de service pour l'identifiant de service donné. Le type d'objet renvoyé est spécifique au fournisseur de cloud.

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

dbutils.credentials.help("getServiceCredentialsProvider")

Exemple​

Python
dbutils.credentials.getServiceCredentialsProvider("my-credential")

Commande showCurrentRole (dbutils.credentials.showCurrentRole)​

showCurrentRole: List

Liste le rôle AWS Identity and Access Management (IAM) actuellement défini.

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

dbutils.credentials.help("showCurrentRole")

Exemple​

Python
dbutils.credentials.showCurrentRole()

# Out[1]: ['arn:aws:iam::123456789012:role/my-role-a']

commande showRoles (dbutils.credentials.showRoles)​

showRoles: List

Répertorie l'ensemble des rôles AWS Identity and Access Management (IAM) pouvant être assumés.

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

dbutils.credentials.help("showRoles")

Exemple​

Python
dbutils.credentials.showRoles()

# Out[1]: ['arn:aws:iam::123456789012:role/my-role-a', 'arn:aws:iam::123456789012:role/my-role-b']

Utilitaire de données (dbutils.data)​

info

Aperçu

Cette fonctionnalité est en aperçu public.

remarque

Disponible dans Databricks Runtime 9.0 et versions ultérieures.

Le module d'utilitaires de données contient des commandes pour comprendre et interagir avec les datasets.

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ésumez un DataFrame Spark et visualisez les statistiques pour obtenir des insights rapides

Commande

Description

résumer

Résumez un DataFrame Spark et visualisez les statistiques pour obtenir des insights rapides

commande de résumé (dbutils.data.summarize)​

remarque

Cette fonctionnalité est en aperçu public.

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

Calcule et affiche les statistiques récapitulatives d'un Apache Spark DataFrame ou d'un pandas DataFrame. 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 de très grands DataFrames 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 precise supplémentaire pour ajuster la précision des statistiques calculées.

  • Lorsque precise est défini sur false (the default), certaines statistiques renvoyées incluent des approximations pour réduire le temps d'exécution.

    • Le nombre de valeurs distinctes pour les colonnes catégorielles peut présenter environ 5 % d'erreur relative pour les colonnes à cardinalité élevée.
    • Le décompte des valeurs fréquentes peut présenter une erreur allant jusqu'à 0,01 % lorsque le nombre de valeurs distinctes est supérieur à 10 000.
    • Les histogrammes et les estimations de centiles peuvent présenter une erreur allant jusqu'à 0,01 % par rapport au nombre total de lignes.

  • Lorsque precise est défini sur true, les statistiques sont calculées avec une plus grande précision. Toutes les statistiques, à l'exception des histogrammes et des percentiles pour les colonnes numériques, sont désormais exactes.

    • Les histogrammes et les estimations de centile peuvent présenter 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.

Exemple​

Cet exemple affiche des statistiques récapitulatives pour un DataFrame Apache Spark avec des approximations activées par default. Pour voir les résultats, exécutez cette commande dans un Notebook. Cet exemple est basé sur des Sample datasets.

Python
df = spark.read.format('csv').load(
  '/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
  header=True,
  inferSchema=True
)
dbutils.data.summarize(df)

La visualisation utilise la notation SI pour rendre de manière concise les valeurs numériques inférieures à 0,01 ou supérieures à 10 000. Par exemple, la valeur numérique 1.25e-15 sera affichée comme 1.25f. Une exception : la visualisation utilise « B » pour 1.0e9 (giga) au lieu de « G ».

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

Le module utilitaire du système de fichiers contient des commandes pour accéder à Qu’est-ce que DBFS ?. Pour accéder aux fichiers Workspace, utilisez des commandes Shell telles que %sh ls, car il existe des limitations lors de l'utilisation des commandes dbutils.fs avec les fichiers Workspace.

attention

L'implémentation Python de toutes les méthodes dbutils.fs utilise snake_case plutôt que camelCase pour le formatage des mots-clés.

Par exemple, dbutils.fs.help() affiche l'option extraConfigs pour dbutils.fs.mount(). Cependant, en 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 à travers des systèmes de fichiers

tête

Renvoie jusqu’aux 'max_bytes' premiers octets du fichier donné en tant que String encodée en UTF-8.

ls

Liste le contenu d'un répertoire

mkdirs

Crée le répertoire spécifié s'il n'existe pas, en créant également les répertoires parents nécessaires

Monter

Monte le répertoire source donné dans DBFS au point de montage donné

monte

Affiche des informations sur ce qui est monté dans DBFS

mv

Déplace un fichier ou un répertoire, éventuellement entre les systèmes de fichiers

mettre

Écrit la chaîne donnée dans un fichier, encodée en UTF-8

refreshMounts

Force toutes les machines de ce cluster à refresh leur cache de montage, garantissant ainsi qu'elles reçoivent les informations les plus récentes.

rm

Supprime un fichier ou un répertoire

démonter

Supprime un point de montage DBFS

updateMount

Similaire à mount(), mais met à jour un point de montage existant au lieu d’en créer un nouveau

Commande

Description

cp

Copie un fichier ou un répertoire, éventuellement à travers des systèmes de fichiers

tête

Renvoie jusqu’aux 'max_bytes' premiers octets du fichier donné en tant que String encodée en UTF-8.

ls

Liste le contenu d'un répertoire

mkdirs

Crée le répertoire spécifié s'il n'existe pas, en créant également les répertoires parents nécessaires

Monter

Monte le répertoire source donné dans DBFS au point de montage donné

monte

Affiche des informations sur ce qui est monté dans DBFS

mv

Déplace un fichier ou un répertoire, éventuellement entre les systèmes de fichiers

mettre

Écrit la chaîne donnée dans un fichier, encodée en UTF-8

refreshMounts

Force toutes les machines de ce cluster à refresh leur cache de montage, garantissant ainsi qu'elles reçoivent les informations les plus récentes.

rm

Supprime un fichier ou un répertoire

démonter

Supprime un point de montage DBFS

updateMount

Similaire à mount(), mais met à jour un point de montage existant au lieu d’en créer un nouveau

astuce

Dans les Notebooks, vous pouvez utiliser la commande magique %fs pour accéder à DBFS. Par exemple, %fs ls /Volumes/main/default/my-volume/ est identique à dbutils.fs.ls("/Volumes/main/default/my-volume/"). Voir les commandes magiques.

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/ vers 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

commande head (dbutils.fs.head)​

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

Renvoie jusqu'au nombre maximal d'octets spécifié dans le fichier donné. Les octets sont renvoyés en tant que chaîne encodée 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'

commande ls (dbutils.fs.ls)​

ls(dir: String): Seq

Liste 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. En 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)]

Commande mkdirs (dbutils.fs.mkdirs)​

mkdirs(dir: String): boolean

Crée le répertoire donné s’il n’existe pas. Crée également tous 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

commande de montage (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é.

:::note Compatibilité Serverless

Databricks recommande de s’éloigner de dbutils.fs.mount, car il n’est pas compatible avec l’architecture de compute serverless de Databricks. Utilisez un emplacement externe Unity Catalog avec des volumes externes à la place.

:::

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

dbutils.fs.help("mount")

Exemple​

Python
aws_bucket_name = "my-bucket"
mount_name = "s3-my-bucket"

dbutils.fs.mount("s3a://%s" % aws_bucket_name, "/mnt/%s" % mount_name)

Pour d’autres exemples de code, consultez Connecter à Amazon S3.

commande mounts (dbutils.fs.mounts)​

mounts: Seq

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

:::note Compatibilité Serverless

Databricks recommande de ne plus utiliser dbutils.fs.mounts, car il n'est pas compatible avec l'architecture de compute serverless de Databricks.

:::

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

dbutils.fs.help("mounts")

Exemple​

attention

Appelez dbutils.fs.refreshMounts() sur tous les autres clusters en cours d'exécution pour propager le nouveau montage. Voir commande refreshMounts (dbutils.fs.refreshMounts).

Python
dbutils.fs.mounts()

# Out[11]: [MountInfo(mountPoint='/mnt/databricks-results', source='databricks-results', encryptionType='sse-s3')]

Pour d’autres exemples de code, consultez Connecter à Amazon S3.

commande mv (dbutils.fs.mv)​

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

Déplace un fichier ou un répertoire, éventuellement entre systèmes de fichiers. Un déplacement est une copie suivie d'une suppression, même pour les déplacements au sein des systèmes de fichiers.

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

dbutils.fs.help("mv")

Exemple​

Cet exemple déplace le fichier rows.csv 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

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 un fichier nommé hello.txt dans /Volumes/main/default/my-volume/. Si le fichier existe, il sera écrasé.

Python
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", True)

# Wrote 2258987 bytes.
# Out[6]: True

commande refreshMounts (dbutils.fs.refreshMounts)​

refreshMounts: boolean

Force toutes les machines du cluster à refresh leur cache de montage, garantissant ainsi qu'elles 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()

Pour d’autres exemples de code, consultez Connecter à Amazon S3.

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 paramètre recurse est ignoré. Si un répertoire est spécifié, une erreur se produit lorsque recurse est désactivé 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

commande de démontage (dbutils.fs.unmount)​

unmount(mountPoint: String): boolean

Supprime un point de montage DBFS.

attention

Pour éviter les erreurs, ne modifiez jamais un point de montage pendant que d'autres Jobs le lisent ou l'écrivent. Après avoir modifié un point de montage, exécutez toujours dbutils.fs.refreshMounts() sur tous les autres clusters en cours d'exécution pour propager toute mise à jour de point de montage. Voir la commande refreshMounts (dbutils.fs.refreshMounts).

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

dbutils.fs.help("unmount")

Exemple​

Python
dbutils.fs.unmount("/mnt/<mount-name>")

Pour d’autres exemples de code, consultez Connecter à Amazon S3.

commande updateMount (dbutils.fs.updateMount)​

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

Similaire à la commande dbutils.fs.mount, mais met à jour un point de montage existant au lieu d'en créer un nouveau. Renvoie une erreur si le point de montage n'est pas présent.

attention

Pour éviter les erreurs, ne modifiez jamais un point de montage pendant que d'autres Jobs le lisent ou l'écrivent. Après avoir modifié un point de montage, exécutez toujours dbutils.fs.refreshMounts() sur tous les autres clusters en cours d'exécution pour propager toute mise à jour de point de montage. Voir la commande refreshMounts (dbutils.fs.refreshMounts).

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
aws_bucket_name = "my-bucket"
mount_name = "s3-my-bucket"

dbutils.fs.updateMount("s3a://%s" % aws_bucket_name, "/mnt/%s" % mount_name)

Utilitaire Jobs (dbutils.jobs)​

Le module d'utilitaires des Jobs contient les commandes de fonctionnalités des Jobs.

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

Valeurs de la tâche

Fournit des infrastructures publiques pour tirer parti des valeurs de tâches de Job

Sous-module

Description

Valeurs de la tâche

Fournit des infrastructures publiques pour tirer parti des valeurs de tâches de Job

Sous-utilitaire taskValues (dbutils.jobs.taskValues)​

remarque

Cette sous-utilité est disponible uniquement pour Python.

Fournit des commandes pour exploiter les valeurs de tâche de Job.

Utilisez ce sous-utilitaire pour définir et obtenir des valeurs arbitraires lors de l'exécution d'un job. Ces valeurs sont appelées valeurs de tâche . N'importe quelle tâche peut obtenir les valeurs définies par les tâches en amont et définir des valeurs à utiliser par les tâches en aval.

Chaque valeur de tâche possède une clé unique au sein de la même tâche. Cette clé unique est connue comme la clé de la valeur de la tâche. Une valeur de tâche est accessible avec le nom de la tâche et la clé de la valeur de la tâche. Vous pouvez l'utiliser pour transmettre des informations en aval de tâche en tâche au sein de la même exécution de Job. Par exemple, vous pouvez transmettre des identifiants ou des métriques, telles que des informations sur l'évaluation d'un Modèle de machine learning, entre différentes tâches au sein d'une exécution de Job.

Le tableau suivant répertorie les commandes disponibles pour ce sous-utilitaire, que vous pouvez récupérer en utilisant 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 de Job actuelle.

Définir.

Définit ou met à jour une valeur de tâche. Vous pouvez définir jusqu'à 250 valeurs de tâche pour une exécution de job.

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 de Job actuelle.

Définir.

Définit ou met à jour une valeur de tâche. Vous pouvez définir jusqu'à 250 valeurs de tâche pour une exécution de job.

obtenir la commande (dbutils.jobs.taskValues.get)​

remarque

Cette commande est disponible uniquement pour Python.

Sur Databricks Runtime 10.4 et versions antérieures, si get ne trouve pas la tâche, une Py4JJavaError est levée au lieu d'un 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 de Job actuelle.

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

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

Exemple​

Par exemple :

Python
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 trouve pas cette tâche, une ValueError est levée.
  • key est le nom de la clé de la valeur de tâche que vous avez définie avec la commande set (dbutils.jobs.taskValues.set). Si la commande ne trouve pas la clé de cette valeur de tâche, une ValueError est levée (sauf si default est spécifié).
  • default est une valeur facultative qui est retournée si key est introuvable. default ne peut pas être None.
  • debugValue est une valeur facultative qui est renvoyée si vous essayez d'obtenir la valeur de la tâche à partir d'un Notebook qui s'exécute en dehors d'un job. Cela peut être utile pendant le debugging lorsque vous souhaitez exécuter votre Notebook manuellement et retourner une valeur au lieu de lever une TypeError par default. debugValue ne peut pas être None.

Si vous tentez d'obtenir une valeur de tâche à partir d'un Notebook qui s'exécute en dehors d'un Job, cette commande déclenche une TypeError par default. Toutefois, si l'argument debugValue est spécifié dans la commande, la valeur de debugValue est renvoyée au lieu de générer une 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âche pour une exécution de job.

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

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

Exemple​

Voici quelques exemples :

Python
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 tâche. Cette clé doit être unique pour 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 de la clé de cette valeur de tâche. Cette commande doit pouvoir 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 KiB.

Si vous essayez de définir une valeur de tâche à partir d'un notebook qui s'exécute en dehors d'un job, cette commande ne fait rien.

utilitaire de bibliothèque (dbutils.library)​

La plupart des méthodes du module dbutils.library sont obsolètes. Voir Utilitaire de bibliothèque (dbutils.library) (hérité).

Vous pourriez avoir besoin de redémarrer par programmation le processus Python sur Databricks pour vous assurer que les bibliothèques installées localement ou mises à jour 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 Databricks.

Utilitaire Notebook (dbutils.notebook)​

Le module utilitaire Notebook contient des commandes pour enchaîner les Notebooks et agir sur leurs résultats. Voir Orchestrer les notebooks Databricks et modulariser le code.

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

Description

Quitter

Quitte un Notebook avec une valeur.

Exécuter

Exécute un notebook et renvoie sa valeur de sortie.

commande de sortie (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 notebook avec la valeur Exiting from My Other Notebook.

Python
dbutils.notebook.exit("Exiting from My Other Notebook")

# Notebook exited: Exiting from My Other Notebook
remarque

Si l'exécution comporte une query avec streaming structuré s'exécutant en arrière-plan, l'appel de dbutils.notebook.exit() ne met pas fin à l'exécution. L'exécution continuera de s'exécuter tant que la query s'exécutera en arrière-plan. Vous pouvez arrêter la query exécutée en arrière-plan en cliquant sur Annuler dans la cellule de la query ou en exécutant query.stop(). Lorsque la query s'arrête, vous pouvez terminer l'exécution avec dbutils.notebook.exit().

exécuter la commande (dbutils.notebook.run)​

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

Exécute un notebook et renvoie sa valeur de sortie. Le notebook s'exécutera dans le cluster actuel.

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 Notebook nommé My Other Notebook au même emplacement que le Notebook appelant. Le Notebook appelé se termine par la ligne de code dbutils.notebook.exit("Exiting from My Other Notebook"). Si le notebook appelé ne termine pas son exécution dans les 60 secondes, une exception est levée.

Python
dbutils.notebook.run("My Other Notebook", 60)

# Out[14]: 'Exiting from My Other Notebook'

Utilitaire Secrets (dbutils.secrets)​

Le module utilitaire de gestion des secrets contient des commandes permettant de stocker et d'accéder aux informations d'identification sensibles sans les rendre visibles dans les notebooks. Consultez Gestion des secrets et Étape 3 : Utiliser les secrets dans un Notebook.

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 portée et clé.

getBytes

Obtient la représentation en octets d'une valeur de secret avec un périmètre et une clé.

Liste

Répertorie les métadonnées secrètes pour les secrets au sein d'un périmètre secret.

listScopes

Lister les Secret Scope

Commande

Description

obtenir

Obtient la représentation sous forme de chaîne d'une valeur secrète avec portée et clé.

getBytes

Obtient la représentation en octets d'une valeur de secret avec un périmètre et une clé.

Liste

Répertorie les métadonnées secrètes pour les secrets au sein d'un périmètre secret.

listScopes

Lister les Secret Scope

obtenir la commande (dbutils.secrets.get)​

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

Obtient la représentation textuelle d'une valeur secrète pour le Secret Scope et la clé spécifiés.

attention

Les administrateurs, les créateurs de secrets et les utilisateurs ayant obtenu une autorisation peuvent lire les secrets Databricks. Bien que Databricks s'efforce de masquer les valeurs secrètes qui pourraient être affichées dans les blocs-notes, il n'est pas possible d'empêcher ces utilisateurs de lire les secrets. Pour plus d'informations, veuillez consulter la rédaction des secrets.

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

dbutils.secrets.help("get")

Exemple​

Cet exemple obtient la représentation de chaîne de caractères de la valeur secrète pour le périmètre nommé my-scope et la clé nommée my-key.

Python
dbutils.secrets.get(scope="my-scope", key="my-key")

# Out[14]: '[REDACTED]'

Commande getBytes (dbutils.secrets.getBytes)​

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

Obtient la représentation en octets d'une valeur secrète pour le périmètre 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 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#'

commande de liste (dbutils.secrets.list)​

list(scope: String): Seq

Répertorie les métadonnées des secrets dans le périmètre spécifié.

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

dbutils.secrets.help("list")

Exemple​

Cet exemple répertorie les métadonnées des secrets dans le périmètre nommé my-scope.

Python
dbutils.secrets.list("my-scope")

# Out[10]: [SecretMetadata(key='my-key')]

Commande listScopes (dbutils.secrets.listScopes)​

listScopes: Seq

Liste les portées 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')]

Utilitaire de widgets (dbutils.widgets)​

Le module d'utilitaires de widgets contient des commandes pour paramétrer les Notebooks. Consulter les 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

zone de liste déroulante

Crée un widget d'entrée de zone de liste déroulante avec un nom donné, une valeur default et des choix.

Menu déroulant

Crée un widget d'entrée déroulant avec un nom donné, une valeur default et des choix

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

Obsolète. Équivalent à obtenir

Sélection multiple

Crée un widget d'entrée à sélection multiple avec un nom donné, une valeur default et des choix

Supprimer

Supprime un widget de saisie du Notebook

tout supprimer

Supprime tous les widgets du notebook.

Texte

Crée un widget de saisie de texte avec un nom donné et une valeur default

Commande

Description

zone de liste déroulante

Crée un widget d'entrée de zone de liste déroulante avec un nom donné, une valeur default et des choix.

Menu déroulant

Crée un widget d'entrée déroulant avec un nom donné, une valeur default et des choix

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

Obsolète. Équivalent à obtenir

Sélection multiple

Crée un widget d'entrée à sélection multiple avec un nom donné, une valeur default et des choix

Supprimer

Supprime un widget de saisie du Notebook

tout supprimer

Supprime tous les widgets du notebook.

Texte

Crée un widget de saisie de texte avec un nom donné et une valeur default

commande de boîte combinée (dbutils.widgets.combobox)​

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

Crée et affiche un widget de type liste déroulante avec le nom programmatique spécifié, la valeur par default, les choix et un libellé facultatif.

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 programmatique fruits_combobox. Il offre les choix apple, banana, coconut et dragon fruit et est défini sur la valeur initiale de banana. Ce widget de boîte combinée comporte une étiquette d'accompagnement Fruits. Cet exemple se termine en affichant 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

commande de menu déroulant (dbutils.widgets.dropdown)​

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

Crée et affiche un widget déroulant avec le nom programmatique spécifié, la valeur default, 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 liste déroulante avec le nom programmatique toys_dropdown. Il offre les choix alphabet blocks, basketball, cape et doll et est défini sur la valeur initiale de basketball. Ce widget de liste déroulante a un libellé associé Toys. Cet exemple se termine en affichant la valeur initiale du widget 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

commande get (dbutils.widgets.get)​

get(name: String): String

Obtient la valeur actuelle du widget avec le nom programmatique spécifié. Ce nom programmatique peut être :

  • Le nom d'un widget personnalisé dans le Notebook, par exemple, fruits_combobox ou toys_dropdown.
  • Le nom d'un parameter personnalisé transmis au Notebook dans le cadre d'une tâche de Notebook, par exemple name ou age. Pour plus d'information, consultez la couverture des parameters pour les tâches de Notebook dans l'interface utilisateur des Jobs ou le champ notebook_params dans l'opération Trigger une nouvelle exécution de Job (POST /jobs/run-now) dans l'API Jobs.

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

dbutils.widgets.help("get")

Exemple​

Cet exemple obtient la valeur du widget dont le nom programmatique est fruits_combobox.

Python
dbutils.widgets.get('fruits_combobox')

# banana

Cet exemple obtient la valeur du paramètre de tâche Notebook qui a le nom programmatique age. Ce paramètre a été défini sur 35 lors de l'exécution de la tâche de Notebook associée.

Python
dbutils.widgets.get('age')

# 35

commande getAll (dbutils.widgets.getAll)​

getAll: map

Obtient un mappage de tous les noms et valeurs de widget actuels. Ceci peut être particulièrement utile pour transférer rapidement des valeurs de widget à une query spark.sql().

Cette commande est disponible dans Databricks Runtime 13.3 LTS et versions ultérieures. Il n'est disponible que pour Python et Scala.

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

dbutils.widgets.help("getAll")

Exemple​

Cet exemple obtient la map des valeurs de widget et la transmet en tant qu'arguments de parameter dans une query Spark SQL.

Python
df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()

# Query output

Commande getArgument (dbutils.widgets.getArgument)​

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

Obtient la valeur actuelle du widget avec le nom programmatique spécifié. Si le widget n'existe pas, un message facultatif peut être renvoyé.

remarque

Cette commande est obsolète. 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 dont le nom programmatique est fruits_combobox. Si ce widget n'existe pas, le message Error: Cannot find fruits combobox est renvoyé.

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'

commande de sélection multiple (dbutils.widgets.multiselect)​

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

Crée et affiche un widget de sélection multiple avec le nom programmatique spécifié, la valeur default, les choix et une étiquette facultative.

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

dbutils.widgets.help("multiselect")

Exemple​

Cet exemple crée et affiche un widget de sélection multiple portant le nom programmatique days_multiselect. Il offre les choix Monday à Sunday et est défini sur la valeur initiale de Tuesday. Ce widget de sélection multiple a un libellé associé Days of the Week. Cet exemple se termine par l'impression de la valeur initiale du widget de sélection multiple, 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

commande de suppression (dbutils.widgets.remove)​

remove(name: String): void

Supprime le widget portant le nom programmatique 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 ultérieure 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 programmatique fruits_combobox.

Python
dbutils.widgets.remove('fruits_combobox')

Commande removeAll (dbutils.widgets.removeAll)​

removeAll: void

Supprime tous les widgets du notebook.

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 de commande ultérieure pour créer des widgets dans la même cellule. Vous devez créer les widgets dans une autre cellule.

Exemple​

Cet exemple supprime tous les widgets du Notebook.

Python
dbutils.widgets.removeAll()

commande texte (dbutils.widgets.text)​

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

Crée et affiche un widget de texte avec le nom programmatique spécifié, la valeur default et une é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 programmatique your_name_text. Il est défini sur la valeur initiale de Enter your name. Ce widget de texte est accompagné du libellé Your name. Cet exemple se termine en affichant la valeur initiale du widget de 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

Bibliothèque de l'API Databricks Utilitaires​

important

La bibliothèque de l'API Databricks Utilities (dbutils-api) est dépréciée. Databricks vous recommande d'utiliser l'une des options suivantes à la place :

Pour accélérer le développement d'applications, il peut être utile de compiler, de créer et de tester les applications avant de les déployer en tant que Jobs de production. Pour vous permettre de compiler avec Databricks Utilities, Databricks fournit la bibliothèque dbutils-api. Vous pouvez download la bibliothèque dbutils-api depuis la page Web de l'API DBUtils sur le site Web du Maven repository ou inclure la bibliothèque en ajoutant une dépendance à votre fichier de construction :

  • SBT

    Scala
    libraryDependencies += "com.databricks" % "dbutils-api_TARGET" % "VERSION"

  • Maven

    XML
    <dependency>
        <groupId>com.databricks</groupId>
        <artifactId>dbutils-api_TARGET</artifactId>
        <version>VERSION</version>
    </dependency>

  • Gradle

    Bash
    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 une liste des cibles et versions disponibles, consultez la page web de l'API DBUtils sur le site web du repository Maven.

Une fois que vous avez créé votre application avec cette bibliothèque, vous pouvez la déployer.

important

La bibliothèque dbutils-api vous permet uniquement de compiler localement une application qui utilise dbutils, pas de l'exécuter. Pour exécuter l'application, vous devez la déployer dans Databricks.

Limitations​

L'appel de dbutils à l'intérieur des exécuteurs peut produire des résultats inattendus ou des erreurs.

Si vous avez besoin d’exécuter des opérations de système de fichiers sur des exécuteurs à l’aide de dbutils, consultez Paralléliser les opérations de système de fichiers.

Pour plus d'informations sur les exécuteurs, consultez la Présentation du Mode cluster sur le site web d'Apache Spark.

Sur cette page