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

Articolo
01/02/2025

Questo articolo contiene informazioni di riferimento sulle utilità di Databricks (dbutils). Le utilità forniscono comandi che consentono di usare l'ambiente Databricks dai notebook. Ad esempio, è possibile gestire i file e l'archiviazione di oggetti e usare i segreti. dbutils sono disponibili nei notebook Python, R e Scala.

Nota

dbutils supporta solo ambienti di calcolo che usano DBFS.

Moduli di utilità

Nell'table seguente sono elencati i moduli Databricks Utilities, che è possibile recuperare usando dbutils.help().

Modulo	Descrizione
dati	Utilità per la comprensione e l'interazione con i set di dati (EXPERIMENTAL)
fs	Utilità per l'accesso al file system di Databricks (DBFS)
lavori	Utilità per sfruttare le funzionalità dei processi
libreria	Deprecato. Utilità per la gestione delle librerie con ambito sessione
portatile	Utilità per la gestione del flusso di controllo dei notebook (SPERIMENTALE)
segreti	Utilità per sfruttare i segreti all'interno dei notebook
widgets	Utilità per la parametrizzazione dei notebook.
api	Utilità per la gestione delle compilazioni di applicazioni

Guida al comando

Per list comandi per un modulo di utilità insieme a una breve descrizione di ogni comando, aggiungere .help() dopo il nome del modulo di utilità. L'esempio seguente elenca i comandi disponibili per l'utilità notebook:

dbutils.notebook.help()

The notebook module.

exit(value: String): void -> This method lets you exit a notebook with a value
run(path: String, timeoutSeconds: int, arguments: Map): String -> This method runs a notebook and returns its exit value

Per restituire la Guida per un comando, eseguire dbutils.<utility-name>.help("<command-name>"). Nell'esempio seguente viene visualizzata la guida per il comando copy delle utility del file system, dbutils.fs.cp:

dbutils.fs.help("cp")

/**
* Copies a file or directory, possibly across FileSystems.
*
* Example: cp("/mnt/my-folder/a", "dbfs:/a/b")
*
* @param from FileSystem URI of the source file or directory
* @param to FileSystem URI of the destination file or directory
* @param recurse if true, all files and directories will be recursively copied
* @return true if all files were successfully copied
*/
cp(from: java.lang.String, to: java.lang.String, recurse: boolean = false): boolean

Utilità dati (dbutils.data)

Importante

Questa funzionalità è disponibile in anteprima pubblica.

Nota

Disponibile in Databricks Runtime 9.0 e versioni successive.

L'utilità dati consente di comprendere e interagire con i set di dati.

Nell'table seguente sono elencati i comandi disponibili per questa utilità, che è possibile recuperare usando dbutils.data.help().

Comando	Descrizione
riepilogare	Riepiloga un DataFrame Spark e visualizza le statistiche per ottenere informazioni rapide get

comando riepiloga (dbutils.data.summarize)

Nota

Questa funzionalità è disponibile in anteprima pubblica.

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

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

Importante

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

Per visualizzare la guida completa 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.

Quando precise è set su false (impostazione predefinita), alcune statistiche restituite includono approssimazioni per ridurre il tempo di esecuzione.
- Il numero di values distinti per i columns categorici può avere un errore relativo di circa 5% per la cardinalità elevata columns.
- I conteggi dei valori frequenti possono avere un errore fino a 0,01% quando il numero di distinti values è maggiore di 10000.
- Gli istogrammi e le stime percentili possono avere un errore fino allo 0,01% rispetto al numero totale di righe.
Quando precise viene set true, le statistiche vengono calcolate con precisione più elevata. Tutte le statistiche, ad eccezione degli istogrammi e dei percentili per i numerici columns, 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.

Esempio

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 notazione SI per eseguire il rendering conciso values numerico inferiore a 0,01 o superiore 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)

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

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.

Nell'table seguente sono elencati i comandi disponibili per questa utilità, che è possibile recuperare usando dbutils.fs.help().

Comando	Descrizione
cp	Copia un file o una directory, possibilmente tra diversi file system.
head	Restituisce fino ai primi byte 'maxBytes' del file specificato come stringa codificata in UTF-8
ls	Elenca il contenuto di una directory
mkdirs	Crea la directory specificata se non esiste, creando anche le directory padre necessarie
montaggio	Monta la cartella di origine specificata in DBFS al punto di montaggio specificato
monta	Visualizza informazioni su ciò che viene montato all'interno di DBFS
mv	Sposta un file o una directory, possibilmente tra file system
inserire	Scrive la stringa specificata in un file codificato in UTF-8
refreshMounts	Impone a tutti i computer del cluster di refresh la cache di montaggio, assicurandosi di ricevere le informazioni più recenti
rm	Rimuove un file o una directory
smontare	Elimina un punto di montaggio DBFS
updateMount	Simile a mount(), ma aggiorna un punto di montaggio esistente anziché crearne uno nuovo

Suggerimento

Nei notebook è possibile usare il %fs comando magic 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.

Comando cp (dbutils.fs.cp)

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

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.fs.help("cp")

Esempio

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)

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

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.fs.help("head")

Esempio

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)

ls(dir: String): Seq

Elenca i contenuti di una directory.

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.fs.help("ls")

Esempio

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)

mkdirs(dir: String): boolean

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.fs.help("mkdirs")

Esempio

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)

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

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.fs.help("mount")

Esempio

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)

mounts: Seq

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.fs.help("mounts")

Esempio

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)

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

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 la guida completa per questo comando, eseguire:

dbutils.fs.help("mv")

Esempio

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)

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

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.fs.help("put")

Esempio

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)

refreshMounts: boolean

Impone a tutti i computer del cluster di refresh la cache di montaggio, assicurandosi di ricevere le informazioni più recenti.

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.fs.help("refreshMounts")

Esempio

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)

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

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 la guida completa per questo comando, eseguire:

dbutils.fs.help("rm")

Esempio

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)

unmount(mountPoint: String): boolean

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 la guida completa per questo comando, eseguire:

dbutils.fs.help("unmount")

Esempio

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)

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

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

Avviso

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.fs.help("updateMount")

Esempio

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)

Fornisce strumenti per sfruttare le funzionalità dei lavori.

Nota

Questa utilità è disponibile solo per Python.

Nell'table seguente sono elencati i moduli disponibili per questa utilità, che è possibile recuperare usando dbutils.jobs.help().

Sottomodulo	Descrizione
taskValues	Fornisce utilità per lo sfruttamento del compito lavorativo values

Sottoutilità taskValues (dbutils.jobs.taskValues)

Nota

Questa sottoutilità è disponibile solo per Python.

Fornisce i comandi per utilizzare l'attività di lavoro values.

Usare questa sotto-utilità per set e getvalues arbitrari durante l'esecuzione di un processo. Queste values vengono chiamate attività values. Qualsiasi attività può getvaluesset dalle attività a monte e setvalues per essere utilizzate dalle attività a valle.

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.

Nell'table seguente sono elencati i comandi disponibili per questa sottoutilità, che è possibile recuperare usando dbutils.jobs.taskValues.help().

Comando	Descrizione
get	Ottiene il contenuto del valore attività specificato per l'attività specificata nell'esecuzione del processo corrente.
set	Imposta o aggiorna un valore attività. È possibile set fino a 250 values attività per l'esecuzione di un processo.

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.

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

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

Per visualizzare la guida completa per questo comando, eseguire:

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

Esempio

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 per il valore del compito che set 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 restituito se si tenta di get il valore dell'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 get il valore di un'attività dall'interno di un notebook in esecuzione al di fuori di un processo di lavoro, 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.

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

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

Per visualizzare la guida completa per questo comando, eseguire:

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

Esempio

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 set un valore di attività con chiave K, si tratta di due attività diverse values 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 set un valore di attività dall'interno di un notebook in esecuzione al di fuori di un job, questo comando non esegue 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)

L'utilità notebook consente di concatenare i notebook e agire sui risultati. Consulta Orchestrare e modularizzare il codice nei notebook.

Nell'table seguente sono elencati i comandi disponibili per questa utilità, che è possibile recuperare usando dbutils.notebook.help().

Comando	Descrizione
uscita	Esce da un ambiente notebook con un risultato.
eseguire	Esegue un notebook e restituisce il relativo valore di uscita

Comando exit (dbutils.notebook.exit)

exit(value: String): void

Chiude un notebook con un valore.

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.notebook.help("exit")

Esempio

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)

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

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 Get l'output per una singola esecuzione (GET /jobs/runs/get-output).

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.notebook.help("run")

Esempio

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)

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.

Nell'table seguente sono elencati i comandi disponibili per questa utilità, che è possibile recuperare usando dbutils.secrets.help().

Comando	Descrizione
get	Ottiene la rappresentazione in formato stringa di un valore segreto con ambito e chiave
getBytes	Ottiene la rappresentazione in byte di un valore segreto specificando l'ambito e la chiave
list	Elenca i metadati dei segreti all'interno di un ambito
listScopes	Elenca gli scopi segreti

comando get (dbutils.secrets.get)

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

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 nascondere il segreto values che potrebbe essere visualizzato nei notebook, non è possibile impedire agli utenti di leggerlo. Per altre informazioni, vedere Offuscamento dei segreti.

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.secrets.help("get")

Esempio

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)

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

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.secrets.help("getBytes")

Esempio

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)

list(scope: String): Seq

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.secrets.help("list")

Esempio

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)

listScopes: Seq

Elenca gli ambiti disponibili.

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.secrets.help("listScopes")

Esempio

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)

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

Nell'table seguente sono elencati i comandi disponibili per questa utilità, che è possibile recuperare usando dbutils.widgets.help().

Comando	Descrizione
casella combinata	Crea un widget di input della casella combinata con un nome, un valore predefinito e opzioni specificati
elenco a discesa	Crea un widget di input a discesa con un nome dato, un valore predefinito e delle scelte specificate
get	Recupera il valore corrente di un widget di input
getAll	Recupera una mappa di tutti i nomi dei widget e dei relativi values
getArgument	Deprecato. Equivalente a get
selezione multipla	Crea un widget di input a selezione multipla con un nome, un valore predefinito e opzioni specificati
remove	Rimuove un widget di input dal notebook
rimuoviTutto	Rimuove tutti i widget nel notebook
testo	Crea un widget di input di testo con un nome e un valore predefinito specificati

Comando combobox (dbutils.widgets.combobox)

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

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.widgets.help("combobox")

Esempio

In questo esempio viene creato e mostrato un widget casella combinata con il nome programmatico fruits_combobox. Offre le opzioni apple, banana, coconute dragon fruit ed è set al 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

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

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.widgets.help("dropdown")

Esempio

In questo esempio viene creato e mostrato un widget a discesa con il nome programmatico toys_dropdown. Offre le opzioni alphabet blocks, basketball, capee doll ed è set al 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)

get(name: String): String

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 di parameters per le attività del notebook nell'interfaccia utente dei processi o nel campo notebook_params nel Attivare un nuovo processo eseguire (POST /jobs/run-now) nell'API Processi.

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.widgets.help("get")

Esempio

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 è passato da set a 35 quando è stata eseguita 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)

getAll: map

Ottiene una mappatura di tutti i nomi dei widget correnti e di values. Questo può essere particolarmente utile per trasferire rapidamente il widget values 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 la guida completa per questo comando, eseguire:

dbutils.widgets.help("getAll")

Esempio

Questo esempio ottiene la mappa del widget identificato come values e la passa come parametro in una query Spark SQL.

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)

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

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. Invece, usare dbutils.widgets.get.

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.widgets.help("getArgument")

Esempio

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)

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

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.widgets.help("multiselect")

Esempio

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 è set rispetto al 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)

remove(name: String): void

Rimuove il widget con il nome programmatico specificato.

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.widgets.help("remove")

Importante

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

Esempio

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)

removeAll: void

Rimuove tutti i widget dal notebook.

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.widgets.help("removeAll")

Importante

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

Esempio

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)

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

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

Per visualizzare la guida completa per questo comando, eseguire:

dbutils.widgets.help("text")

Esempio

In questo esempio viene creato e mostrato un widget di testo con il nome programmatico your_name_text. È pari a set al 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 Databricks Utilities (dbutils-api) è deprecata. Databricks consiglia di usare una delle opzioni 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 di destinazioni e versioni disponibili, vedere la pagina Web API DBUtils nel 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 di dbutils all'interno di executor può produrre risultati o errori imprevisti.

Se è necessario eseguire operazioni sul file system sugli executor con dbutils, fare riferimento ai metodi di elenco e di eliminazione in parallelo con Spark in Come list ed eliminare i file più rapidamente 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)

Moduli di utilità

Guida al comando

Utilità dati (dbutils.data)

comando riepiloga (dbutils.data.summarize)

Esempio

Python

R

Scala

Utilità file system (dbutils.fs)

Comando cp (dbutils.fs.cp)

Esempio

Python

R

Scala

Comando head (dbutils.fs.head)

Esempio

Python

R

Scala

Comando ls (dbutils.fs.ls)

Esempio

Python

R

Scala

Comando mkdirs (dbutils.fs.mkdirs)

Esempio

Python

R

Scala

Comando mount (dbutils.fs.mount)

Esempio

Python

Scala

Comando mounts (dbutils.fs.mounts)

Esempio

Python

Scala

Comando mv (dbutils.fs.mv)

Esempio

Python

R

Scala

Comando put (dbutils.fs.put)

Esempio

Python

R

Scala

Comando refreshMounts (dbutils.fs.refreshMounts)

Esempio

Python

Scala

Comando rm (dbutils.fs.rm)

Esempio

Python

R

Scala

Comando unmount (dbutils.fs.unmount)

Esempio

Comando updateMount (dbutils.fs.updateMount)

Esempio

Python

Scala

Utilità processi (dbutils.jobs)

Sottoutilità taskValues (dbutils.jobs.taskValues)

comando get (dbutils.jobs.taskValues.get)

Esempio

comando set (dbutils.jobs.taskValues.set)

Esempio

Utilità libreria (dbutils.library)

Utilità notebook (dbutils.notebook)

Comando exit (dbutils.notebook.exit)

Esempio

Python

R

Scala

Comando run (dbutils.notebook.run)

Esempio

Python

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