Condividi tramite

Informazioni di riferimento sulle utilità di Databricks (dbutils)

  • Articolo

Questo articolo contiene informazioni di riferimento per le utilità di Databricks (dbutils). Le utilità dbutils sono disponibili nei notebook Python, R e Scala. È possibile usare le utilità per:

  • Usare file e archiviazione di oggetti in modo efficiente.
  • Usare i segreti.

Come fare a: elencare le utilità, elencare i comandi, visualizzare l’aiuto online ai comandi

Utilità: dati, fs, processi, libreria, notebook, segreti, widget, libreria API utilità

Elencare le utilità disponibili

Per elencare le utilità disponibili con a una breve descrizione di ogni utilità, eseguire dbutils.help() per Python o Scala.

In questo esempio vengono elencati i comandi disponibili per le utilità di 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

Elencare i comandi disponibili per un'utilità

Per elencare i comandi disponibili per un'utilità con a una breve descrizione di ogni comando, eseguire .help() dopo il nome programmatico dell'utilità.

In questo esempio vengono elencati i comandi disponibili per le utilità DBFS (Databricks File System).

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

Visualizzare l’aiuto online per un comando

Per visualizzare l’aiuto online per un comando, eseguire .help("<command-name>") dopo il nome del comando.

In questo esempio viene mostrato l’aiuto online per il comando di copia 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

Utilità dati (dbutils.data)

Importante

Questa funzionalità è disponibile in anteprima pubblica.

Nota

Disponibile in Databricks Runtime 9.0 e versioni successive.

Comandi: riepiloga

L'utilità dati consente di comprendere e interpretare i set di dati. Per elencare i comandi disponibili, eseguire 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

comando riepiloga (dbutils.data.summarize)

Calcola e visualizza statistiche di riepilogo di un DataFrame Apache Spark o di un DataFrame pandas. Questo comando è disponibile per Python, Scala e R.

Questo comando analizza il contenuto completo del DataFrame. L'esecuzione di questo comando per DataFrame di grandi dimensioni può essere molto costosa.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.data.help("summarize").

In Databricks Runtime 10.4 LTS e versioni successive è possibile usare il parametro precise aggiuntivo per regolare la precisione delle statistiche calcolate.

Nota

Questa funzionalità è disponibile in anteprima pubblica.

  • Se precise è impostato su false (impostazione predefinita), alcune statistiche restituite includono approssimazioni per ridurre il tempo di esecuzione.
    • Il numero di diversi valori per le colonne di categoria può avere un errore relativo del 5% circa per le colonne a cardinalità elevata.
    • Il conteggio dei valori frequenti può avere un errore fino allo 0,01% quando il numero dei valori distinti è maggiore di 10000.
    • Gli istogrammi e le stime percentili possono avere un errore fino allo 0,01% rispetto al numero totale di righe.
  • Se precise è impostato su true, le statistiche vengono calcolate con una precisione maggiore. Tutte le statistiche ad eccezione degli istogrammi e dei percentili per le colonne numeriche sono ora esatte.
    • Gli istogrammi e le stime percentili possono avere un errore fino allo 0,0001% rispetto al numero totale di righe.

Il tooltip nella parte superiore dell'output di riepilogo dei dati indica la modalità di esecuzione corrente.

In questo esempio vengono visualizzate statistiche di riepilogo di un DataFrame Apache Spark con approssimazioni abilitate per impostazione predefinita. Per visualizzare i risultati, eseguire questo comando in un notebook. Questo esempio è basato su set di dati di esempio.

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)

Si noti che la visualizzazione usa la notazione del sistema internazionale di misura per rendere in modo conciso di valori numerici inferiori a 0,01 o superiori a 10000. Ad esempio, il valore numerico 1.25e-15 verrà reso con 1.25f. Un'eccezione: la visualizzazione usa "B" per 1.0e9 (giga) anziché "G".

Utilità file system (dbutils.fs)

Avviso

L'implementazione Python di tutti i metodi dbutils.fs usa snake_case anziché camelCase per la formattazione delle parole chiave.

Ad esempio: mentre dbutils.fs.help() visualizza l'opzione extraConfigs per dbutils.fs.mount(), in Python si userà la parola chiave extra_configs.

Comandi: cp, head, ls, mkdirs, mount, mounts, mv, put, refreshMounts, rm, unmount, updateMount

L'utilità file system consente di accedere a Che cos'è DBFS?, semplificando l'uso di Azure Databricks come file system.

Nei notebook è possibile usare anche il comando magic %fs per accedere a DBFS. Ad esempio, %fs ls /Volumes/main/default/my-volume/ è identico a dbutils.fs.ls("/Volumes/main/default/my-volume/"). Vedere i comandi magic.

Per elencare i comandi disponibili, eseguire 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

Comando cp (dbutils.fs.cp)

Copia un file o una directory, possibilmente tra file system.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("cp").

In questo esempio il file denominato data.csv viene copiato da /Volumes/main/default/my-volume/ a new-data.csv nello stesso 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

Comando head (dbutils.fs.head)

Restituisce fino al numero massimo specificato di byte di un determinato file. I byte vengono restituiti come stringa con codifica UTF-8.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("head").

In questo esempio vengono visualizzati i primi 25 byte del file data.csv che si trova in /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"

Comando ls (dbutils.fs.ls)

Elenca i contenuti di una directory.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("ls").

In questo esempio vengono visualizzate informazioni sul contenuto di /Volumes/main/default/my-volume/. Il campo modificationTime è disponibile in Databricks Runtime 10.4 LTS e versioni successive. In R, modificationTime viene restituito come stringa.

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

Comando mkdirs (dbutils.fs.mkdirs)

Crea la directory specificata, se non esiste. Crea anche le directory padre necessarie.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("mkdirs").

Nell'esempio riportato di seguito la directory my-data viene creata in /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

Comando mount (dbutils.fs.mount)

Monta la directory di origine specificata in DBFS nel punto di montaggio specificato.

Per visualizzare l’aiuto online per questo comando, eseguire 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>")))

Per altri codici di esempio, vedere Connettersi ad Azure Data Lake Storage Gen2 e archiviazione BLOB.

Comando mounts (dbutils.fs.mounts)

Mostra informazioni su ciò che è attualmente montato all'interno di DBFS.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("mounts").

Avviso

Chiamare dbutils.fs.refreshMounts() su tutti gli altri cluster in esecuzione per propagare il nuovo montaggio. Vedere il comando refreshMounts (dbutils.fs.refreshMounts).

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Per altri codici di esempio, vedere Connettersi ad Azure Data Lake Storage Gen2 e archiviazione BLOB.

Comando mv (dbutils.fs.mv)

Sposta un file o una directory, possibilmente tra file system. Uno spostamento è una copia seguita da un'eliminazione, anche per gli spostamenti all'interno dei file system.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("mv").

In questo esempio il file rows.csv viene spostato da /Volumes/main/default/my-volume/ a /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

Comando put (dbutils.fs.put)

Scrive in un file la stringa specificata. La stringa è con codifica UTF-8.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("put").

Nell'esempio riportato di seguito la stringa Hello, Databricks! viene scritta nel file denominato hello.txt in /Volumes/main/default/my-volume/. Se il file esiste già, verrà sovrascritto.

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

Comando refreshMounts (dbutils.fs.refreshMounts)

Forza tutti i computer del cluster ad aggiornare la cache di montaggio, assicurandosi che ricevano le informazioni più recenti.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("refreshMounts").

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Per altri codici di esempio, vedere Connettersi ad Azure Data Lake Storage Gen2 e archiviazione BLOB.

Comando rm (dbutils.fs.rm)

Rimuove un file o una directory e, facoltativamente, tutto il relativo contenuto. Se viene specificato un file, il parametro recurse viene ignorato. Se si specifica una directory, si verifica un errore se la directory è disabilitata e se la directory non è vuota.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("rm").

In questo esempio viene rimossa la directory /Volumes/main/default/my-volume/my-data/, incluso il contenuto della directory.

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

Comando unmount (dbutils.fs.unmount)

Elimina un punto di montaggio DBFS.

Avviso

Per evitare errori, non modificare mai un punto di montaggio mentre altri processi stanno leggendo o scrivendo su di esso. Dopo aver modificato un montaggio, eseguire sempre dbutils.fs.refreshMounts() in tutti gli altri cluster in esecuzione per propagare eventuali aggiornamenti di montaggio. Vedere il comando refreshMounts (dbutils.fs.refreshMounts).

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("unmount").

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

Per altri codici di esempio, vedere Connettersi ad Azure Data Lake Storage Gen2 e archiviazione BLOB.

Comando updateMount (dbutils.fs.updateMount)

È simile al comando dbutils.fs.mount, ma aggiorna un punto di montaggio esistente anziché crearne uno nuovo. Se il punto di montaggio non è presente, restituisce un errore.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.fs.help("updateMount").

Avviso

Per evitare errori, non modificare mai un punto di montaggio mentre altri processi stanno leggendo o scrivendo su di esso. Dopo aver modificato un montaggio, eseguire sempre dbutils.fs.refreshMounts() in tutti gli altri cluster in esecuzione per propagare eventuali aggiornamenti di montaggio. Vedere il comando refreshMounts (dbutils.fs.refreshMounts).

Questo comando è disponibile in Databricks Runtime 10.4 LTS e versioni successive.

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

Utilità processi (dbutils.jobs)

Sottoutilità: taskValues

Nota

Questa utilità è disponibile solo per Python.

L'utilità processi consente di sfruttare le funzionalità dei processi. Per visualizzare l’aiuto online per questa utilità, eseguire dbutils.jobs.help().

Provides utilities for leveraging jobs features.

taskValues: TaskValuesUtils -> Provides utilities for leveraging job task values

Sottoutilità taskValues (dbutils.jobs.taskValues)

Comandi: get, set

Nota

Questa sottoutilità è disponibile solo per Python.

Fornisce i comandi per sfruttare i valori delle attività di processo.

Usare questa utilità secondaria per impostare e ottenere valori arbitrari durante l'esecuzione di un processo. Questi valori sono detti valori attività. È possibile accedere ai valori attività nelle attività downstream della stessa esecuzione del processo. Ad esempio, è possibile comunicare identificatori o metriche, come le informazioni sulla valutazione di un modello di Machine Learning, tra attività diverse all'interno di un'esecuzione del processo. Ogni attività può impostare più valori attività, ottenerli o entrambe le operazioni. Ogni valore attività ha una chiave univoca all'interno della stessa attività. Questa chiave univoca è nota come chiave del valore attività. Si accede a un valore attività con il nome dell'attività e la chiave del valore attività.

Per visualizzare l’aiuto online per questa sottoutilità, eseguire dbutils.jobs.taskValues.help().

Comando get (dbutils.jobs.taskValues.get)

Nota

Nota: questo comando è disponibile solo per Python.

In Databricks Runtime 10.4 e versioni precedenti, se get non riesce a trovare l'attività, viene generato un Py4JJavaError anziché un ValueError.

Ottiene il contenuto del valore attività specificato per l'attività specificata nell'esecuzione del processo corrente.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.jobs.taskValues.help("get").

Ad esempio:

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

Nell'esempio precedente:

  • taskKey è il nome dell'attività che imposta il valore attività. Se il comando non riesce a trovare questa attività, viene generato un ValueError.
  • key è il nome della chiave del valore attività impostata con il comando set (dbutils.jobs.taskValues.set). Se il comando non riesce a trovare la chiave di questo valore attività, viene generato un ValueError (a meno che non sia specificato default).
  • default è un valore facoltativo restituito se non è possibile trovare key. default non può essere None.
  • debugValue è un valore facoltativo che viene restituito se si tenta di ottenere il valore attività dall'interno di un notebook in esecuzione all'esterno di un processo. Questo può essere utile durante il debug quando si vuole eseguire manualmente il notebook e restituire un valore anziché generare un TypeError per impostazione predefinita. debugValue non può essere None.

Se si tenta di ottenere un valore attività dall'interno di un notebook in esecuzione all'esterno di un processo, questo comando genera un TypeError per impostazione predefinita. Tuttavia, se l'argomento debugValue viene specificato nel comando, viene restituito il valore di debugValue e non generato un TypeError.

Comando set (dbutils.jobs.taskValues.set)

Nota

Nota: questo comando è disponibile solo per Python.

Imposta o aggiorna un valore attività. È possibile configurare fino a 250 valori attività per l'esecuzione di un processo.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.jobs.taskValues.help("set").

Alcuni esempi includono:

dbutils.jobs.taskValues.set(key   = "my-key", \
                            value = 5)

dbutils.jobs.taskValues.set(key   = "my-other-key", \
                            value = "my other value")

Negli esempi precedenti:

  • key è la chiave del valore attività. Questa chiave deve essere univoca per l'attività. Ovvero, se due attività diverse impostano un valore attività con chiave K, si tratta di due valori attività diversi con la stessa chiave K.
  • value è il valore della chiave di questo valore attività. Questo comando deve essere in grado di rappresentare il valore internamente in formato JSON. Le dimensioni della rappresentazione JSON del valore non possono superare i 48 KiB.

Se si tenta di impostare un valore attività dall'interno di un notebook in esecuzione all'esterno di un processo, questo comando attiva alcuna operazione.

Utilità libreria (dbutils.library)

La maggior parte dei metodi del modulo secondario dbutils.library è deprecata. Vedere Utilità libreria (dbutils.library) (legacy).

Potrebbe essere necessario riavviare a livello di codice il processo Python in Azure Databricks per assicurarsi che le librerie installate o aggiornate in locale funzionino correttamente nel kernel Python per la SparkSession corrente. A tale scopo, eseguire il comando dbutils.library.restartPython. Vedere Riavviare il processo Python in Azure Databricks.

Utilità notebook (dbutils.notebook)

Comandi: exit, run

L'utilità notebook consente di concatenare i notebook e agire sui risultati. Vedere Eseguire un notebook di Databricks da un altro notebook.

Per elencare i comandi disponibili, eseguire 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.

Comando exit (dbutils.notebook.exit)

Chiude un notebook con un valore.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.notebook.help("exit").

In questo esempio viene chiuso il notebook con il valore 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

Nota

Se l'esecuzione dispone di una query con flusso strutturato in esecuzione in background, la chiamata a dbutils.notebook.exit() non termina l'esecuzione. L'esecuzione continuerà finché la query viene eseguita in background. È possibile arrestare la query in esecuzione in background facendo clic su Annulla nella cella della query o eseguendo query.stop(). Quando la query viene arrestata, è possibile terminare l'esecuzione con dbutils.notebook.exit().

Comando run (dbutils.notebook.run)

Esegue un notebook e ne restituisce il valore di uscita. Il notebook verrà eseguito nel cluster corrente per impostazione predefinita.

Nota

La lunghezza massima del valore stringa restituito dal comando run è di 5 MB. Vedere Ottenere l'output per una singola esecuzione (GET /jobs/runs/get-output).

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.notebook.help("run").

Questo esempio esegue un notebook denominato My Other Notebook nella stessa posizione del notebook chiamante. Il notebook chiamato termina con la riga di codice dbutils.notebook.exit("Exiting from My Other Notebook"). Se il notebook chiamato non termina l'esecuzione entro 60 secondi, viene generata un'eccezione.

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

Utilità segreti (dbutils.secrets)

Comandi: get, getBytes, list, listScopes

L'utilità segreti consente di archiviare e accedere alle informazioni sulle credenziali riservate senza renderle visibili nei notebook. Vedere Gestione dei segreti e Usare i segreti in un notebook. Per elencare i comandi disponibili, eseguire 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

Comando get (dbutils.secrets.get)

Ottiene la rappresentazione stringa del valore di un segreto per l'ambito e la chiave dei segreti specificati.

Avviso

Gli amministratori, gli autori di segreti e gli utenti autorizzati possono leggere i segreti di Azure Databricks. Anche se Azure Databricks si impegna a eliminare i valori dei segreti che potrebbero essere visualizzati nei notebook, non è possibile impedire a tali utenti di leggere i segreti. Per altre informazioni, vedere Offuscamento dei segreti.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.secrets.help("get").

In questo esempio viene recuperata la rappresentazione stringa del valore del segreto per l'ambito denominato my-scope e la chiave denominata 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]

Comando getBytes (dbutils.secrets.getBytes)

Ottiene la rappresentazione in byte del valore di un segreto per l'ambito e la chiave specificati.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.secrets.help("getBytes").

In questo esempio viene recuperata la rappresentazione in byte del valore del segreto (nell’esempio, a1!b2@c3#) per l'ambito denominato my-scope e la chiave denominata 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)

Comando list (dbutils.secrets.list)

Elenca i metadati dei segreti all'interno dell'ambito specificato.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.secrets.help("list").

In questo esempio vengono elencati i metadati dei segreti all'interno dell'ambito denominato 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))

Comando listScopes (dbutils.secrets.listScopes)

Elenca gli ambiti disponibili.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.secrets.help("listScopes").

In questo esempio vengono elencati gli ambiti disponibili.

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

Utilità Widgets (dbutils.widgets)

Comandi: combobox, dropdown, get, getArgument, multiselect, remove, removeAll, text

L'utilità widgets consente di parametrizzare i notebook. Vedere Widget di Databricks.

Per elencare i comandi disponibili, eseguire 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

Comando combobox (dbutils.widgets.combobox)

Crea e mostra un widget casella combinata con il nome programmatico, il valore predefinito, le scelte e l'etichetta facoltativa specificati.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.widgets.help("combobox").

In questo esempio viene creato e mostrato un widget casella combinata con il nome programmatico fruits_combobox. Offre le opzioni apple, banana, coconut e dragon fruit ed è impostato sul valore iniziale di banana. Questo widget casella combinata include un'etichetta Fruits associata. Questo esempio termina stampando il valore iniziale del widget casella combinata, 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

Comando dropdown (dbutils.widgets.dropdown)

Crea e mostra un widget a discesa con il nome programmatico, il valore predefinito, le scelte e l'etichetta facoltativa specificati.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.widgets.help("dropdown").

In questo esempio viene creato e mostrato un widget a discesa con il nome programmatico toys_dropdown. Offre le opzioni alphabet blocks, basketball, cape e doll ed è impostato sul valore iniziale di basketball. Questo widget a discesa ha un'etichetta Toys associata. Questo esempio termina stampando il valore iniziale del widget a discesa, 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

Comando get (dbutils.widgets.get)

Ottiene il valore corrente del widget con il nome programmatico specificato. Questo nome programmatico può essere:

  • Il nome di un widget personalizzato del notebook, ad esempio fruits_combobox o toys_dropdown.
  • Il nome di un parametro personalizzato passato al notebook come parte di un'attività del notebook, ad esempio name o age. Per altre informazioni, vedere la copertura dei parametri per le attività del notebook nell'interfaccia utente per i processi o il campo notebook_params nell'operazione Attiva una nuova esecuzione processo (POST /jobs/run-now) nell'API Processi.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.widgets.help("get").

In questo esempio si ottiene il valore del widget con il nome programmatico fruits_combobox.

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

In questo esempio si ottiene il valore del parametro dell’attività del notebook con il nome programmatico age. Questo parametro era impostato su 35 quando era in esecuzione l'attività del notebook correlata.

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

Comando getAll (dbutils.widgets.getAll)

Ottiene un mapping di tutti i nomi e i valori correnti dei widget. Ciò può essere utile in particolare per passare rapidamente i valori dei widget a una query spark.sql().

Questo comando è disponibile in Databricks Runtime 13.3 LTS e versioni successive. È disponibile solo per Python e Scala.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.widgets.help("getAll").

In questo esempio si ottiene la mappa dei valori del widget e la si passa come argomenti di parametro in una query 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

Comando getArgument (dbutils.widgets.getArgument)

Ottiene il valore corrente del widget con il nome programmatico specificato. Se il widget non esiste, può essere restituito un messaggio facoltativo.

Nota

Questo comando è deprecato. Usare invece dbutils.widgets.get.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.widgets.help("getArgument").

In questo esempio si ottiene il valore del widget con il nome programmatico fruits_combobox. Se questo widget non esiste, viene restituito il messaggio Error: Cannot find fruits combobox.

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

Comando multiselect (dbutils.widgets.multiselect)

Crea e mostra un widget a selezione multipla con il nome programmatico, il valore predefinito, le scelte e l'etichetta facoltativa specificati.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.widgets.help("multiselect").

In questo esempio viene creato e mostrato un widget a selezione multipla con il nome programmatico days_multiselect. Offre le opzioni da Monday a Sunday, ed è impostato sul valore iniziale di Tuesday. Questo widget a selezione multipla ha un'etichetta Days of the Week associata. Questo esempio termina stampando il valore iniziale del widget a selezione multipla, 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

Comando remove (dbutils.widgets.remove)

Rimuove il widget con il nome programmatico specificato.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.widgets.help("remove").

Importante

Se si aggiunge un comando per rimuovere un widget, non è possibile aggiungere un comando successivo per creare un widget nella stessa cella. È necessario creare il widget in un'altra cella.

In questo esempio viene rimosso il widget con il nome programmatico fruits_combobox.

Python

dbutils.widgets.remove('fruits_combobox')

R

dbutils.widgets.remove('fruits_combobox')

Scala

dbutils.widgets.remove("fruits_combobox")

SQL

REMOVE WIDGET fruits_combobox

Comando removeAll (dbutils.widgets.removeAll)

Rimuove tutti i widget dal notebook.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.widgets.help("removeAll").

Importante

Se si aggiunge un comando per rimuovere tutti i widget, non è possibile aggiungere un comando successivo per creare alcun widget nella stessa cella. È necessario creare i widget in un'altra cella.

In questo esempio vengono rimossi tutti i widget dal notebook.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

Comando text (dbutils.widgets.text)

Crea e mostra un widget di testo con il nome programmatico, il valore predefinito e l'etichetta facoltativa specificati.

Per visualizzare l’aiuto online per questo comando, eseguire dbutils.widgets.help("text").

In questo esempio viene creato e mostrato un widget di testo con il nome programmatico your_name_text. È impostato sul valore iniziale di Enter your name. Questo widget di testo ha un'etichetta Your name associata. Questo esempio termina stampando il valore iniziale del widget di testo, 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

Libreria dell'API delle utilità di Databricks

Importante

La libreria dell'API delle utilità di Databricks (dbutils-api) è deprecata. Anche se questa libreria è ancora disponibile, Databricks non pianifica alcuna nuova funzionalità per la libreria dbutils-api.

Databricks consiglia invece di usare una delle librerie seguenti:

Per accelerare lo sviluppo di applicazioni, può essere utile compilare, creare e testare le applicazioni prima di distribuirle come processi di produzione. Per consentire la compilazione in base alle utilità di Databricks, Databricks fornisce la libreria dbutils-api. È possibile scaricare la libreria dbutils-api dalla pagina Web dell'API DBUtils del sito Web del repository Maven o includere la libreria aggiungendo una dipendenza al file di compilazione:

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

Sostituire TARGET con la destinazione desiderata (ad esempio 2.12) e VERSION con la versione desiderata (ad esempio 0.0.5). Per un elenco delle destinazioni e delle versioni disponibili, vedere la pagina Web dell'API DBUtils del sito Web del repository Maven.

Dopo aver compilato l'applicazione in base a questa libreria, è possibile distribuire l'applicazione.

Importante

La libreria dbutils-api consente di compilare localmente un'applicazione che usa dbutils, ma non di eseguirla. Per eseguire l'applicazione, è necessario distribuirla in Azure Databricks.

Limiti

La chiamata a dbutils all'interno di executor può produrre risultati imprevisti o generare potenziali errori.

Se è necessario eseguire operazioni di file system su executor usando dbutils, sono disponibili diverse alternative più veloci e scalabili:

Per informazioni sugli executor, vedere Panoramica della modalità cluster nel sito Web Apache Spark.