Informazioni di riferimento sulle utilità di Databricks (dbutils)

Questo articolo è un riferimento per Le utilità di Databricks (dbutils). dbutils le utilità 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.

Procedura: Elencare utilità, elencare i comandi, visualizzare la Guida ai comandi

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

Elencare le utilità disponibili

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

Questo esempio elenca 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à insieme a una breve descrizione di ogni comando, eseguire .help() dopo il nome programmatico per l'utilità.

Questo esempio elenca i comandi disponibili per l'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 la Guida per un comando

Per visualizzare la Guida per un comando, eseguire .help("<command-name>") dopo il nome del comando.

In questo esempio viene visualizzata la Guida 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: riepilogare

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 summarize (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 la Guida per questo comando, eseguire dbutils.data.help("summarize").

In Databricks Runtime 10.4 LTS e versioni successive è possibile usare il parametro aggiuntivo precise 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 valori distinti per le colonne categorica può avere un errore relativo ~5% per le colonne a cardinalità elevata.
  • I conteggi dei valori frequenti possono avere un errore fino allo 0,01% quando il numero di valori distinct è 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à di esecuzione corrente.

In questo esempio vengono visualizzate statistiche di riepilogo per 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 SI per eseguire il rendering conciso di valori numerici inferiori a 0,01 o superiori a 10000. Ad esempio, il rendering del valore 1.25e-15 numerico verrà eseguito come 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 dbutils.fs metodi 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'è il file system di Databricks (DBFS)?, semplificando l'uso di Azure Databricks come file system. 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 la Guida per questo comando, eseguire dbutils.fs.help("cp").

In questo esempio il file denominato old_file.txt da viene /tmp/newcopiato in /FileStore , rinominando il file copiato in new_file.txt.

Python

dbutils.fs.cp("/FileStore/old_file.txt", "/tmp/new/new_file.txt")

# Out[4]: True

R

dbutils.fs.cp("/FileStore/old_file.txt", "/tmp/new/new_file.txt")

# [1] TRUE

Scala

dbutils.fs.cp("/FileStore/old_file.txt", "/tmp/new/new_file.txt")

// res3: Boolean = true

comando head (dbutils.fs.head)

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

Per visualizzare la Guida per questo comando, eseguire dbutils.fs.help("head").

In questo esempio vengono visualizzati i primi 25 byte del file my_file.txt che si trova in /tmp.

Python

dbutils.fs.head("/tmp/my_file.txt", 25)

# [Truncated to first 25 bytes]
# Out[12]: 'Apache Spark is awesome!\n'

R

dbutils.fs.head("/tmp/my_file.txt", 25)

# [1] "Apache Spark is awesome!\n"

Scala

dbutils.fs.head("/tmp/my_file.txt", 25)

// [Truncated to first 25 bytes]
// res4: String =
// "Apache Spark is awesome!
// "

Comando ls (dbutils.fs.ls)

Elenca il contenuto di una directory.

Per visualizzare la Guida per questo comando, eseguire dbutils.fs.help("ls").

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

Python

dbutils.fs.ls("/tmp")

# Out[13]: [FileInfo(path='dbfs:/tmp/my_file.txt', name='my_file.txt', size=40, modificationTime=1622054945000)]

R

dbutils.fs.ls("/tmp")

# For prettier results from dbutils.fs.ls(<dir>), please use `%fs ls <dir>`

# [[1]]
# [[1]]$path
# [1] "dbfs:/tmp/my_file.txt"

# [[1]]$name
# [1] "my_file.txt"

# [[1]]$size
# [1] 40

# [[1]]$isDir
# [1] FALSE

# [[1]]$isFile
# [1] TRUE

# [[1]]$modificationTime
# [1] "1622054945000"

Scala

dbutils.fs.ls("/tmp")

// res6: Seq[com.databricks.backend.daemon.dbutils.FileInfo] = WrappedArray(FileInfo(dbfs:/tmp/my_file.txt, my_file.txt, 40, 1622054945000))

Comando mkdirs (dbutils.fs.mkdirs)

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

Per visualizzare la Guida per questo comando, eseguire dbutils.fs.help("mkdirs").

In questo esempio viene creata la struttura /parent/child/grandchild di directory all'interno di /tmp.

Python

dbutils.fs.mkdirs("/tmp/parent/child/grandchild")

# Out[15]: True

R

dbutils.fs.mkdirs("/tmp/parent/child/grandchild")

# [1] TRUE

Scala

dbutils.fs.mkdirs("/tmp/parent/child/grandchild")

// res7: Boolean = true

comando mount (dbutils.fs.mount)

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

Per visualizzare la Guida 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 esempi di codice, vedere Connessione in Azure Data Lake Archiviazione Gen2 e Archiviazione BLOB.

Comando mounts (dbutils.fs.mounts)

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

Per visualizzare la Guida 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 esempi di codice, vedere Connessione in Azure Data Lake Archiviazione 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 la Guida per questo comando, eseguire dbutils.fs.help("mv").

In questo esempio il file my_file.txt viene spostato da /FileStore a /tmp/parent/child/granchild.

Python

dbutils.fs.mv("/FileStore/my_file.txt", "/tmp/parent/child/grandchild")

# Out[2]: True

R

dbutils.fs.mv("/FileStore/my_file.txt", "/tmp/parent/child/grandchild")

# [1] TRUE

Scala

dbutils.fs.mv("/FileStore/my_file.txt", "/tmp/parent/child/grandchild")

// res1: Boolean = true

comando put (dbutils.fs.put)

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

Per visualizzare la Guida per questo comando, eseguire dbutils.fs.help("put").

Questo esempio scrive la stringa Hello, Databricks! in un file denominato hello_db.txt in /tmp. Se il file esiste, verrà sovrascritto.

Python

dbutils.fs.put("/tmp/hello_db.txt", "Hello, Databricks!", True)

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

R

dbutils.fs.put("/tmp/hello_db.txt", "Hello, Databricks!", TRUE)

# [1] TRUE

Scala

dbutils.fs.put("/tmp/hello_db.txt", "Hello, Databricks!", true)

// Wrote 18 bytes.
// res2: Boolean = true

Comando refreshMounts (dbutils.fs.refreshMounts)

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

Per visualizzare la Guida per questo comando, eseguire dbutils.fs.help("refreshMounts").

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Per esempi di codice aggiuntivo, vedere Connessione ad Azure Data Lake Archiviazione 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 la directory non è vuota.

Per visualizzare la Guida per questo comando, eseguire dbutils.fs.help("rm").

In questo esempio viene rimossa la directory /tmp , incluso il contenuto della directory.

Python

dbutils.fs.rm("/tmp", True)

# Out[8]: True

R

dbutils.fs.rm("/tmp", TRUE)

# [1] TRUE

Scala

dbutils.fs.rm("/tmp", 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 leggono o scrivono su di esso. Dopo aver modificato un montaggio, eseguire dbutils.fs.refreshMounts() sempre in tutti gli altri cluster in esecuzione per propagare eventuali aggiornamenti di montaggio. Vedere il comando refreshMounts (dbutils.fs.refreshMounts).

Per visualizzare la Guida per questo comando, eseguire dbutils.fs.help("unmount").

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

Per altri esempi di codice, vedere Connessione in Azure Data Lake Archiviazione Gen2 e Archiviazione BLOB.

Comando updateMount (dbutils.fs.updateMount)

Analogamente al dbutils.fs.mount comando, ma aggiorna un punto di montaggio esistente anziché crearne uno nuovo. Restituisce un errore se il punto di montaggio non è presente.

Per visualizzare la Guida per questo comando, eseguire dbutils.fs.help("updateMount").

Avviso

Per evitare errori, non modificare mai un punto di montaggio mentre altri processi leggono o scrivono su di esso. Dopo aver modificato un montaggio, eseguire dbutils.fs.refreshMounts() sempre 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 la Guida 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 denominati valori dell'attività. È possibile accedere ai valori delle attività nelle attività downstream nella stessa esecuzione del processo. Ad esempio, è possibile comunicare identificatori o metriche, ad esempio 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 di attività, ottenerli o entrambi. Ogni valore dell'attività ha una chiave univoca all'interno della stessa attività. Questa chiave univoca è nota come chiave del valore dell'attività. Si accede a un valore dell'attività con il nome dell'attività e la chiave del valore dell'attività.

Per visualizzare la Guida per questa sottoutilità, eseguire dbutils.jobs.taskValues.help().

comando get (dbutils.jobs.taskValues.get)

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 oggetto Py4JJavaError anziché .ValueError

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

Per visualizzare la Guida 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 oggetto ValueError .
• key è il nome della chiave del valore dell'attività impostata con il comando set (dbutils.jobs.taskValues.set).set). Se il comando non riesce a trovare la chiave di questo valore dell'attività, viene generato un ValueError oggetto (a meno che non default sia specificato).
• default è un valore facoltativo restituito se key non è possibile trovare. default non può essere None.
• debugValue è un valore facoltativo restituito se si tenta di ottenere 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 valore TypeError per impostazione predefinita. debugValue non può essere None.

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

comando set (dbutils.jobs.taskValues.set)

Nota

Questo comando è disponibile solo per Python.

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

Per visualizzare la Guida 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 dell'attività. Questa chiave deve essere univoca per l'attività. Ovvero, se due attività diverse impostano un valore di attività con chiave K, si tratta di due valori di attività diversi con la stessa chiave K.
• value è il valore della chiave di questo valore dell'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 48 KiB.

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

Utilità libreria (dbutils.library)

La maggior parte dei metodi nel dbutils.library modulo secondario è 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 sessione 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)

Esce da un notebook con un valore .

Per visualizzare la Guida per questo comando, eseguire dbutils.notebook.help("exit").

Questo esempio esce dal 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 dbutils.notebook.exit() non termina l'esecuzione. L'esecuzione continuerà a essere eseguita 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 restituisce il relativo valore di uscita. Il notebook verrà eseguito nel cluster corrente per impostazione predefinita.

Nota

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

Per visualizzare la Guida 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 di stringa di un valore segreto per l'ambito e la chiave dei segreti specificati.

Avviso

Amministrazione istrators, creatori di segreti e utenti autorizzati a leggere i segreti di Azure Databricks. Anche se Azure Databricks si impegna a redactare i valori dei segreti che potrebbero essere visualizzati nei notebook, non è possibile impedire a tali utenti di leggere i segreti. Per altre informazioni, vedere Rollforward dei segreti.

Per visualizzare la Guida per questo comando, eseguire dbutils.secrets.help("get").

In questo esempio viene recuperata la rappresentazione di 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 di un valore segreto per l'ambito e la chiave specificati.

Per visualizzare la Guida per questo comando, eseguire dbutils.secrets.help("getBytes").

In questo esempio viene recuperata la rappresentazione in byte del valore del segreto (in questo esempio a1!b2@c3#) per l'ambito denominato e la chiave denominata my-scopemy-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 per i segreti all'interno dell'ambito specificato.

Per visualizzare la Guida per questo comando, eseguire dbutils.secrets.help("list").

In questo esempio vengono elencati i metadati per i 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 la Guida 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, elenco a discesa, get, getArgument, multiselect, remove, removeAll, text

L'utilità widget 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
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 visualizza un widget casella combinata con il nome programmatico, il valore predefinito, le scelte e l'etichetta facoltativa specificati.

Per visualizzare la Guida per questo comando, eseguire dbutils.widgets.help("combobox").

In questo esempio viene creato e visualizzato un widget combobox con il nome fruits_comboboxprogrammatico . Offre le opzioni apple, banana, coconute dragon fruit e è impostato sul valore iniziale di banana. Questo widget combobox include un'etichetta Fruitsassociata. Questo esempio termina stampando il valore iniziale del widget combobox, 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

Comando dropdown (dbutils.widgets.dropdown)

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

Per visualizzare la Guida per questo comando, eseguire dbutils.widgets.help("dropdown").

In questo esempio viene creato e visualizzato un widget a discesa con il nome toys_dropdownprogrammatico . Offre le opzioni alphabet blocks, basketball, capee doll e è impostato sul valore iniziale di basketball. Questo widget a discesa ha un'etichetta Toysassociata. 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

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.
• 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 nel campo Creare un'interfaccia utente di processo o nel notebook_params campo Attivare una nuova esecuzione di processo (POST /jobs/run-now) nell'API Processi.

Per visualizzare la Guida per questo comando, eseguire dbutils.widgets.help("get").

Questo esempio ottiene il valore del widget con il nome fruits_comboboxprogrammatico .

Python

dbutils.widgets.get('fruits_combobox')

# banana

R

dbutils.widgets.get('fruits_combobox')

# [1] "banana"

Scala

dbutils.widgets.get("fruits_combobox")

// res6: String = banana

Questo esempio ottiene il valore del parametro dell'attività del notebook con il nome ageprogrammatico . Questo parametro è stato impostato su 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

Comando getArgument (dbutils.widgets.getArgument)

Ottiene il valore corrente del widget con il nome programmatico specificato. Se il widget non esiste, è possibile restituire un messaggio facoltativo.

Nota

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

Per visualizzare la Guida per questo comando, eseguire dbutils.widgets.help("getArgument").

Questo esempio ottiene il valore del widget con il nome fruits_comboboxprogrammatico . 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 visualizza un widget a selezione multipla con il nome programmatico, il valore predefinito, le scelte e l'etichetta facoltativa specificati.

Per visualizzare la Guida per questo comando, eseguire dbutils.widgets.help("multiselect").

In questo esempio viene creato e visualizzato un widget a selezione multipla con il nome days_multiselectprogrammatico . Offre le opzioni Monday tramite Sunday e viene impostato sul valore iniziale di Tuesday. Questo widget di selezione multipla ha un'etichetta Days of the Weekassociata. Questo esempio termina stampando il valore iniziale del widget multi-selezione, 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

comando remove (dbutils.widgets.remove)

Rimuove il widget con il nome programmatico specificato.

Per visualizzare la Guida 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 fruits_comboboxprogrammatico .

Python

dbutils.widgets.remove('fruits_combobox')

R

dbutils.widgets.remove('fruits_combobox')

Scala

dbutils.widgets.remove("fruits_combobox")

Comando removeAll (dbutils.widgets.removeAll)

Rimuove tutti i widget dal notebook.

Per visualizzare la Guida 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 widget nella stessa cella. È necessario creare i widget in un'altra cella.

Questo esempio rimuove tutti i widget dal notebook.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

comando text (dbutils.widgets.text)

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

Per visualizzare la Guida per questo comando, eseguire dbutils.widgets.help("text").

In questo esempio viene creato e visualizzato un widget di testo con il nome your_name_textprogrammatico . Viene impostato sul valore iniziale di Enter your name. Questo widget di testo ha un'etichetta Your nameassociata. 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

Libreria api di Utilità di Databricks

Importante

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

Databricks consiglia invece di usare una delle librerie seguenti:

• Utilità di Databricks per Scala, con Java
• Utilità di Databricks per Scala, con Scala

Per accelerare lo sviluppo di applicazioni, può essere utile compilare, compilare e testare applicazioni prima di distribuirle come processi di produzione. Per consentire la compilazione in base alle utilità di Databricks, Databricks fornisce la dbutils-api libreria. È possibile scaricare la dbutils-api libreria dalla pagina Web dell'API DBUtils nel 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 nel sito Web del repository Maven.

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

Importante

La dbutils-api libreria 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 dbutils all'interno di executor può produrre risultati imprevisti o potenzialmente generare errori.

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

• Per le operazioni di copia o spostamento di file, è possibile controllare un'opzione più veloce per eseguire operazioni di file system descritte in Parallelizzare le operazioni di filesystem).
• Per le operazioni di elenco ed eliminazione del file system, è possibile fare riferimento a metodi di elenco ed eliminazione paralleli che usano Spark in Come elencare ed eliminare file più velocemente in Databricks.

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