Informazioni di riferimento sulle utilità di Databricks (`dbutils`)

Articolo
11/21/2024

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.

Nota

dbutils supporta solo ambienti di calcolo che usano DBFS.

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.

La descrizione comando nella parte superiore dell'output di riepilogo dei dati indica la modalità dell'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)

La visualizzazione usa la notazione SI per eseguire il rendering conciso dei 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, dbutils.fs.help() visualizza l'opzione extraConfigs per dbutils.fs.mount(). In Python, tuttavia, 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 il %fs comando magic per accedere a DBFS. Ad esempio, %fs ls /Volumes/main/default/my-volume/ è identico a duties.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 di byte specificato nel file specificato. 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 recurse parametro viene ignorato. Se si specifica una directory, si verifica un errore quando recurse è disabilitato e la directory non è vuota.

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

In questo esempio viene rimossa l'intera directory /Volumes/main/default/my-volume/my-data/ , incluso il relativo contenuto.

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

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 sottoutilitta per impostare e ottenere valori arbitrari durante l'esecuzione di un processo. Questi valori sono detti valori attività. Qualsiasi attività può ottenere valori impostati dalle attività upstream e impostare i valori per le attività downstream da usare.

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à. È possibile usarlo per passare le informazioni downstream dall'attività all'attività all'interno della stessa esecuzione del processo. Ad esempio, è possibile passare identificatori o metriche, ad esempio informazioni sulla valutazione di un modello di Machine Learning, tra attività diverse all'interno di un'esecuzione del processo.

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 dell'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à a essere eseguita finché la query è in esecuzione 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 Passaggio 3: 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

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:

Nome di un widget personalizzato nel 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 dbutils-api libreria consente solo di compilare localmente un'applicazione che usa dbutils, non per 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, fare riferimento ai metodi di elenco ed eliminazione paralleli usando Spark in Come elencare ed eliminare i file più velocemente in Databricks.

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

Condividi tramite

Informazioni di riferimento sulle utilità di Databricks (dbutils)

Elencare le utilità disponibili

Python

Scala

Elencare i comandi disponibili per un'utilità

Python

R

Scala

Visualizzare l’aiuto online per un comando

Python

R

Scala

Utilità dati (dbutils.data)

comando riepiloga (dbutils.data.summarize)

Python

R

Scala

Utilità file system (dbutils.fs)

Comando cp (dbutils.fs.cp)

Python

R

Scala

Comando head (dbutils.fs.head)

Python

R

Scala

Comando ls (dbutils.fs.ls)

Python

R

Scala

Comando mkdirs (dbutils.fs.mkdirs)

Python

R

Scala

Comando mount (dbutils.fs.mount)

Python

Scala

Comando mounts (dbutils.fs.mounts)

Python

Scala

Comando mv (dbutils.fs.mv)

Python

R

Scala

Comando put (dbutils.fs.put)

Python

R

Scala

Comando refreshMounts (dbutils.fs.refreshMounts)

Python

Scala

Comando rm (dbutils.fs.rm)

Python

R

Scala

Comando unmount (dbutils.fs.unmount)

Comando updateMount (dbutils.fs.updateMount)

Python

Scala

Utilità processi (dbutils.jobs)

Sottoutilità taskValues (dbutils.jobs.taskValues)

Comando get (dbutils.jobs.taskValues.get)

Comando set (dbutils.jobs.taskValues.set)

Utilità libreria (dbutils.library)

Utilità notebook (dbutils.notebook)

Comando exit (dbutils.notebook.exit)

Python

R

Scala

Comando run (dbutils.notebook.run)

Python

Scala

Utilità segreti (dbutils.secrets)

Comando get (dbutils.secrets.get)

Python

R

Scala

Comando getBytes (dbutils.secrets.getBytes)

Python

Informazioni di riferimento sulle utilità di Databricks (`dbutils`)