Referenz zu Databricks-Hilfsprogrammen (dbutils)

Dieser Artikel enthält Eine Referenz für Databricks Utilities (dbutils). Die Hilfsprogramme bieten Befehle, mit denen Sie mit Ihrer Databricks-Umgebung aus Notizbüchern arbeiten können. Sie können z. B. Dateien und Objektspeicher verwalten und mit geheimen Schlüsseln arbeiten. dbutils sind in Python-, R- und Scala-Notizbüchern verfügbar.

Hilfsmodule

In der folgenden Tabelle sind die Module "Databricks Utilities" aufgeführt, die Sie mit dbutils.help()abrufen können.

Modul	Beschreibung
Daten	Dienstprogramme für das Verständnis und die Interaktion mit Datensätzen (EXPERIMENTAL)
fs	Dienstprogramme für den Zugriff auf das Databricks-Dateisystem (DBFS)
jobs	Werkzeuge zur Nutzung von Job-Funktionalitäten
Bibliothek	Veraltet. Dienstprogramme zum Verwalten von Bibliotheken mit Sitzungsbereich
Notizbuch	Dienstprogramme für die Verwaltung des Control Flows von Notebooks (EXPERIMENTELL)
Geheimnisse	Dienstprogramme zum Umgang mit Geheimnissen in Notizbüchern
widgets	Hilfsprogramme zum Parametrisieren von Notizbüchern.
api	Dienstprogramme zum Verwalten von Anwendungsbuilds

Befehlshilfe

Um Befehle für ein Hilfsprogrammmodul zusammen mit einer kurzen Beschreibung der einzelnen Befehle auflisten zu können, fügen Sie .help() nach dem Namen des Hilfsmoduls an. Im folgenden Beispiel werden die verfügbaren Befehle für das Notizbuchprogramm aufgelistet:

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

Führen Sie dbutils.<utility-name>.help("<command-name>") aus, um Hilfe für einen Befehl zu erhalten. Im folgenden Beispiel wird die Hilfe für den Befehl "Kopieren" des Dateisystemdiensts dbutils.fs.cpangezeigt:

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

Data-Hilfsprogramm (dbutils.data)

Mit dem Datenhilfsprogramm können Sie Datasets verstehen und damit interagieren.

In der folgenden Tabelle sind die verfügbaren Befehle für dieses Hilfsprogramm aufgeführt, die Sie mit dbutils.data.help()abrufen können.

Befehl	Beschreibung
summarize	Fassen Sie einen Spark DataFrame zusammen, und visualisieren Sie die Statistiken, um schnelle Einblicke zu erhalten

summarize-Befehl (dbutils.data.summarize)

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

Mit diesem Befehl werden zusammenfassende Statistiken für einen Apache Spark-Datenframe oder pandas.DataFrame berechnet und angezeigt. Dieser Befehl ist für Python, Scala und R verfügbar.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.data.help("summarize")

In Databricks Runtime 10.4 LTS und höheren Versionen können Sie zusätzlich den Parameter precise verwenden, um die Genauigkeit der berechneten Statistiken anzupassen.

• Wenn precise auf FALSE festgelegt ist (Standardeinstellung), enthalten einige zurückgegebene Statistiken Näherungen, um die Laufzeit zu verringern.
  • Die Anzahl der eindeutigen Werte für Kategoriespalten kann bei Spalten mit hoher Kardinalität eine relative Fehlerquote von rund 5 % aufweisen.
  • Die Zählung der häufigen Werte kann eine Fehlerquote von bis zu 0,01 % aufweisen, wenn die Anzahl der eindeutigen Werte über 10.000 liegt.
  • Die Histogramme und Perzentilschätzungen können eine Fehlerquote von bis zu 0,01 % bezogen auf die Gesamtzahl der Zeilen aufweisen.
• Wenn precise auf TRUE festgelegt ist, werden die Statistiken mit höherer Genauigkeit berechnet. Alle Statistiken mit Ausnahme der Histogramme und Perzentile für numerische Spalten sind jetzt genau.
  • Die Histogramme und Perzentilschätzungen können eine Fehlerquote von bis zu 0,0001 % im Verhältnis zur Gesamtzahl der Zeilen aufweisen.

Die QuickInfo oben in der Ausgabe der Datenzusammenfassung gibt den Modus der aktuellen Ausführung an.

Beispiel

In diesem Beispiel werden zusammenfassende Statistiken für einen Apache Spark-Datenframe angezeigt, für den standardmäßig Näherungswerte aktiviert sind. Führen Sie diesen Befehl in einem Notebook aus, um die Ergebnisse anzuzeigen. Dieses Beispiel basiert auf den Beispieldatensätzen.

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)

Die Visualisierung verwendet die SI-Schreibweise , um numerische Werte, die kleiner als 0,01 oder größer als 10000 sind, präzise zu rendern. Beispielsweise wird der numerische Wert 1.25e-15 als 1.25f gerendert. Eine Ausnahme: Die Visualisierung verwendet B für 1.0e9 (Giga) anstelle von G.

Dateisystem-Hilfsprogramm (dbutils.fs)

Mit dem Dateisystemprogramm können Sie auf Was ist DBFS? zugreifen, was die Verwendung von Azure Databricks als Dateisystem erleichtert.

In der folgenden Tabelle sind die verfügbaren Befehle für dieses Hilfsprogramm aufgeführt, die Sie mit dbutils.fs.help()abrufen können.

Befehl	Beschreibung
cp	Kopiert eine Datei oder ein Verzeichnis, möglicherweise über FileSystems hinweg.
head	Gibt bis zu den ersten "maxBytes"-Bytes der angegebenen Datei als in UTF-8 codierte Zeichenfolge zurück.
ls	Listet den Inhalt eines Verzeichnisses auf.
mkdirs	Erstellt das angegebene Verzeichnis, falls es nicht vorhanden ist, und erstellt auch alle erforderlichen übergeordneten Verzeichnisse.
mount	Stellt das angegebene Quellverzeichnis am angegebenen Bereitstellungspunkt in DBFS bereit.
mounts	Zeigt Informationen darüber an, was in DBFS bereitgestellt wird
mv	Verschiebt eine Datei oder ein Verzeichnis, möglicherweise über FileSystems
put	Schreibt die angegebene Zeichenfolge in eine Datei, codiert in UTF-8
refreshMounts	Erzwingt alle Computer in diesem Cluster, ihren Bereitstellungscache zu aktualisieren, um sicherzustellen, dass sie die neuesten Informationen erhalten.
rm	Entfernt eine Datei oder ein Verzeichnis.
unmount	Löscht einen DBFS-Einbindungspunkt.
updateMount	Ähnelt dem Befehl mount(), aktualisiert jedoch einen vorhandenen Bereitstellungspunkt, anstatt einen neuen zu erstellen.

cp-Befehl (dbutils.fs.cp)

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

Kopiert eine Datei oder ein Verzeichnis, möglicherweise dateisystemübergreifend.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("cp")

Beispiel

In diesem Beispiel wird die Datei mit dem Namen data.csv aus /Volumes/main/default/my-volume/ in das gleiche Volume in new-data.csv kopiert.

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

head-Befehl (dbutils.fs.head)

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

Gibt bis zur angegebenen maximalen Anzahl von Bytes in der angegebenen Datei zurück. Die Byte werden als UTF-8-codierte Zeichenfolge zurückgegeben.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("head")

Beispiel

In diesem Beispiel werden die ersten 25 Byte der Datei data.csv in /Volumes/main/default/my-volume/ angezeigt.

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"

ls-Befehl (dbutils.fs.ls)

ls(dir: String): Seq

Listet den Inhalt eines Verzeichnisses auf.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("ls")

Beispiel

In diesem Beispiel werden Informationen zum Inhalt von /Volumes/main/default/my-volume/ angezeigt. Das Feld modificationTime ist in Databricks Runtime 10.4 LTS und höheren Versionen verfügbar. In R wird modificationTime als Zeichenfolge zurückgegeben.

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

mkdirs-Befehl (dbutils.fs.mkdirs)

mkdirs(dir: String): boolean

Erstellt das gegebene Verzeichnis, falls es nicht vorhanden ist. Es werden auch alle erforderlichen übergeordneten Verzeichnisse erstellt.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("mkdirs")

Beispiel

In diesem Beispiel wird das Verzeichnis my-data in /Volumes/main/default/my-volume/ erstellt.

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

mount-Befehl (dbutils.fs.mount)

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

Hängt das angegebene Quellverzeichnis an dem angegebenen Einbindungspunkt im DBFS ein.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("mount")

Beispiel

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

Weitere Codebeispiele finden Sie unter Herstellen einer Verbindung mit Azure Data Lake Storage Gen2 und Blob Storage.

mounts-Befehl (dbutils.fs.mounts)

mounts: Seq

Zeigt Informationen zu den aktuell in DBFS bereitgestellten Daten an.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("mounts")

Beispiel

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Weitere Codebeispiele finden Sie unter Herstellen einer Verbindung mit Azure Data Lake Storage Gen2 und Blob Storage.

mv-Befehl (dbutils.fs.mv)

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

Verschiebt eine Datei oder ein Verzeichnis, möglicherweise dateisystemübergreifend. Bei einer Verschiebung wird ein Kopiervorgang mit anschließendem Löschvorgang durchgeführt, selbst bei Verschiebungen innerhalb von Dateisystemen.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("mv")

Beispiel

In diesem Beispiel wird die Datei rows.csv von /Volumes/main/default/my-volume/ nach /Volumes/main/default/my-volume/my-data/verschoben.

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

put-Befehl (dbutils.fs.put)

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

Schreibt die angegebene Zeichenfolge in eine Datei. Die Zeichenfolge ist UTF-8-codiert.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("put")

Beispiel

In diesem Beispiel wird die Zeichenfolge Hello, Databricks! in eine Datei namens hello.txt in /Volumes/main/default/my-volume/ geschrieben. Wenn die Datei bereits vorhanden ist, wird sie überschrieben.

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

refreshMounts-Befehl (dbutils.fs.refreshMounts)

refreshMounts: boolean

Erzwingt, dass alle Computer im Cluster ihren Bereitstellungscache aktualisieren, um sicherzustellen, dass sie die neuesten Informationen erhalten.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("refreshMounts")

Beispiel

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Weitere Codebeispiele finden Sie unter Herstellen einer Verbindung mit Azure Data Lake Storage Gen2 und Blob Storage.

rm-Befehl (dbutils.fs.rm)

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

Entfernt eine Datei oder ein Verzeichnis und optional den gesamten Inhalt. Wenn eine Datei angegeben ist, wird der recurse Parameter ignoriert. Wenn ein Verzeichnis angegeben ist, tritt ein Fehler auf, wenn recurse er deaktiviert ist und das Verzeichnis nicht leer ist.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("rm")

Beispiel

In diesem Beispiel wird das gesamte Verzeichnis /Volumes/main/default/my-volume/my-data/ einschließlich seiner Inhalte entfernt.

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

unmount-Befehl (dbutils.fs.unmount)

unmount(mountPoint: String): boolean

Löscht einen DBFS-Mount-Point.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("unmount")

Beispiel

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

Weitere Codebeispiele finden Sie unter Herstellen einer Verbindung mit Azure Data Lake Storage Gen2 und Blob Storage.

updateMount-Befehl (dbutils.fs.updateMount)

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

Ähnelt dem Befehl dbutils.fs.mount, aktualisiert jedoch einen vorhandenen Bereitstellungspunkt, anstatt einen neuen zu erstellen. Gibt einen Fehler zurück, wenn der Bereitstellungspunkt nicht vorhanden ist.

Dieser Befehl ist in Databricks Runtime 10.4 LTS und höheren Versionen verfügbar.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.fs.help("updateMount")

Beispiel

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

Jobs-Hilfsprogramm (dbutils.jobs)

Stellt Hilfsprogramme zur Nutzung von Jobfunktionen bereit.

In der folgenden Tabelle sind die verfügbaren Module für dieses Hilfsprogramm aufgeführt, die Sie mit dbutils.jobs.help()abrufen können.

Untermodul	Beschreibung
taskValues	Stellt Hilfsprogramme für die Nutzung von Auftragswerten zur Verfügung.

taskValues-Unterhilfsprogramm (dbutils.jobs.taskValues)

Stellt Befehle für die Nutzung von Auftragswerten zur Verfügung.

Verwenden Sie dieses Unterprogramm, um beliebige Werte während einer Auftragsausführung festzulegen und abzurufen. Diese Werte werden Aufgabenwerte genannt. Jeder Vorgang kann Werte abrufen, die von upstream-Vorgängen festgelegt werden, und Werte für nachgeschaltete Vorgänge festlegen, die verwendet werden sollen.

Jeder Aufgabenwert hat einen eindeutigen Schlüssel innerhalb derselben Aufgabe. Dieser eindeutige Schlüssel wird als Schlüssel des Aufgabenwerts bezeichnet. Der Zugriff auf einen Aufgabenwert erfolgt über den Aufgabennamen und den Schlüssel des Aufgabenwerts. So können Sie innerhalb eines Auftrags Informationen von Aufgabe zu Aufgabe weitergeben. Sie können z. B. Bezeichner oder Metriken übergeben, z. B. Informationen zur Auswertung eines Machine Learning-Modells, zwischen verschiedenen Aufgaben innerhalb eines Auftragslaufs.

In der folgenden Tabelle sind die verfügbaren Befehle für diese Unternutzung aufgeführt, die Sie mit dbutils.jobs.taskValues.help()abrufen können.

Befehl	Beschreibung
get	Ruft den Inhalt des angegebenen Aufgabenwertes für die angegebene Aufgabe im aktuellen Auftragslauf ab.
set	Legt einen Aufgabenwert fest oder aktualisiert ihn. Sie können bis zu 250 Aufgabenwerte für einen Auftrag festlegen.

get-Befehl (dbutils.jobs.taskValues.get)

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

Ruft den Inhalt des angegebenen Aufgabenwertes für die angegebene Aufgabe im aktuellen Auftragslauf ab.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

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

Beispiel

Beispiele:

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

Im vorherigen Beispiel:

• taskKey ist der Name des Vorgangs, der den Vorgangswert festlegt. Wenn der Befehl diese Aufgabe nicht finden kann, wird ValueError ausgelöst.
• key ist der Name des Schlüssels des Auftragswerts, den Sie mit dem Befehl set (dbutils.jobs.taskValues.set) festgelegt haben. Wenn der Befehl den Schlüssel dieses Aufgabenwerts nicht finden kann, wird ValueError ausgelöst (es sei denn, default ist angegeben).
• default ist ein optionaler Wert, der zurückgegeben wird, wenn key nicht gefunden werden kann. default darf nicht None sein.
• debugValue ist ein optionaler Wert, der zurückgegeben wird, wenn Sie versuchen, den Aufgabenwert aus einem Notebook abzurufen, das außerhalb eines Auftrags ausgeführt wird. Dies kann beim Debuggen nützlich sein, wenn Sie Ihr Notebook manuell ausführen und einen Wert zurückgeben möchten, anstatt standardmäßig ein TypeError auszulösen. debugValue darf nicht None sein.

Wenn Sie versuchen, einen Aufgabenwert aus einem Notebook abzurufen, das außerhalb eines Auftrags ausgeführt wird, löst dieser Befehl standardmäßig ein TypeError aus. Wenn jedoch das Argument debugValue im Befehl angegeben ist, wird der Wert von debugValue zurückgegeben, anstatt ein TypeError auszulösen.

set-Befehl (dbutils.jobs.taskValues.set)

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

Legt einen Aufgabenwert fest oder aktualisiert ihn. Sie können bis zu 250 Aufgabenwerte für einen Auftrag festlegen.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

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

Beispiel

Beispiele hierfür sind:

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

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

In den vorherigen Beispielen:

• key ist der Schlüssel für den Aufgabenwert. Dieser Schlüssel muss für die Aufgabe eindeutig sein. Das heißt, wenn von zwei verschiedenen Aufgaben jeweils ein Aufgabenwert mit dem Schlüssel K festgelegt wird, sind dies zwei unterschiedliche Aufgabenwerte, die denselben Schlüssel K aufweisen.
• value ist der Wert für den Schlüssel dieses Aufgabenwerts. Dieser Befehl muss in der Lage sein, den Wert intern im JSON-Format darzustellen. Die Größe der JSON-Darstellung des Werts darf 48 KiB nicht überschreiten.

Wenn Sie versuchen, einen Aufgabenwert in einem Notebook festzulegen, das außerhalb eines Auftrags ausgeführt wird, hat dieser Befehl keine Auswirkung.

Library-Hilfsprogramm (dbutils.library)

Die meisten Methoden im dbutils.library-Untermodul sind veraltet. Weitere Informationen finden Sie unter Library-Hilfsprogramm (dbutils.library) (Legacy).

Möglicherweise müssen Sie den Python-Prozess in Azure Databricks programmgesteuert neu starten, um sicherzustellen, dass lokal installierte oder aktualisierte Bibliotheken im Python-Kernel für Ihre aktuelle SparkSession ordnungsgemäß funktionieren. Führen Sie dazu den Befehl dbutils.library.restartPython aus. Weitere Informationen finden Sie unter Neustarten des Python-Prozesses in Azure Databricks.

Notebook-Hilfsprogramm (dbutils.notebook)

Mit dem Notebookhilfsprogramm können Sie Notebooks verketten und auf deren Ergebnisse reagieren. Weitere Informationen finden Sie unter Orchestrierung von Notebooks und Modularisieren von Code in Notebooks.

In der folgenden Tabelle sind die verfügbaren Befehle für dieses Hilfsprogramm aufgeführt, die Sie mit dbutils.notebook.help()abrufen können.

Befehl	Beschreibung
exit	Beendet ein Notebook mit einem Wert.
run	Führt ein Notebook aus und gibt dessen Exit-Wert zurück.

exit-Befehl (dbutils.notebook.exit)

exit(value: String): void

Beendet ein Notebook mit einem Wert.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.notebook.help("exit")

Beispiel

In diesem Beispiel wird das Notebook mit dem Wert Exiting from My Other Notebook beendet.

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

run-Befehl (dbutils.notebook.run)

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

Führt ein Notebook aus und gibt dessen Exit-Wert zurück. Das Notebook wird standardmäßig im aktuellen Cluster ausgeführt.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.notebook.help("run")

Beispiel

In diesem Beispiel wird ein Notebook mit dem Namen My Other Notebook am selben Ort ausgeführt wie das aufrufende Notebook. Das aufgerufene Notebook endet mit der Codezeile dbutils.notebook.exit("Exiting from My Other Notebook"). Wenn die Ausführung des aufgerufenen Notebooks nicht innerhalb von 60 Sekunden abgeschlossen ist, wird eine Ausnahme ausgelöst.

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

Secrets-Hilfsprogramm (dbutils.secrets)

Mit dem Hilfsprogramm für Geheimnisse können Sie vertrauliche Anmeldeinformationen speichern und darauf zugreifen, ohne sie in den Notebooks sichtbar zu machen. Weitere Informationen finden Sie unter "Geheime Verwaltung " und "Schritt 3: Verwenden der geheimen Schlüssel in einem Notizbuch".

In der folgenden Tabelle sind die verfügbaren Befehle für dieses Hilfsprogramm aufgeführt, die Sie mit dbutils.secrets.help()abrufen können.

Befehl	Beschreibung
get	Ruft die Zeichenfolgendarstellung eines geheimen Werts mit Bereich und Schlüssel ab.
getBytes	Ruft die Zeichenfolgendarstellung eines geheimen Werts mit Bereich und Schlüssel ab.
liste	Listet vertrauliche Metadaten für Geheimnisse innerhalb eines Bereichs auf.
listScopes	Listet Geheimnisbereiche auf.

get-Befehl (dbutils.secrets.get)

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

Ruft die Zeichenfolgendarstellung eines Geheimniswerts für den angegebenen Geheimnisbereich und Schlüssel ab.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.secrets.help("get")

Beispiel

In diesem Beispiel wird die Zeichenfolgendarstellung des Geheimniswerts für den Bereich my-scope und den Schlüssel my-key abgerufen.

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]

getBytes-Befehl (dbutils.secrets.getBytes)

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

Ruft die Bytedarstellung eines Geheimniswerts für den angegebenen Bereich und Schlüssel ab.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.secrets.help("getBytes")

Beispiel

In diesem Beispiel wird die Byte-Darstellung des geheimen Werts (in diesem Beispiel a1!b2@c3#) für den Bereich namens my-scope und den Schlüssel namens my-key abgerufen.

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)

list-Befehl (dbutils.secrets.list)

list(scope: String): Seq

Listet die Metadaten für Geheimnisse innerhalb des angegebenen Bereichs auf.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.secrets.help("list")

Beispiel

In diesem Beispiel werden die Metadaten für Geheimnisse innerhalb des Bereichs my-scope aufgelistet.

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

listScopes-Befehl (dbutils.secrets.listScopes)

listScopes: Seq

Listet die verfügbaren Bereiche auf.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.secrets.help("listScopes")

Beispiel

In diesem Beispiel werden die verfügbaren Bereiche aufgelistet.

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

Widgets-Hilfsprogramm (dbutils.widgets)

Mit dem Widgets-Hilfsprogramm können Sie Notebooks parametrisieren. Weitere Informationen finden Sie unter Databricks-Widgets

In der folgenden Tabelle sind die verfügbaren Befehle für dieses Hilfsprogramm aufgeführt, die Sie mit dbutils.widgets.help()abrufen können.

Befehl	Beschreibung
combobox	Erstellt ein Kombinationsfeld-Eingabe-Widget mit einem bestimmten Namen, Standardwert und Auswahlmöglichkeiten.
dropdown	Erstellt ein Dropdowneingabe-Widget mit einem bestimmten Namen, Standardwert und Auswahlmöglichkeiten.
get	Ruft den aktuellen Wert eines Eingabe-Widgets ab.
getAll	Ruft eine Karte aller Widgetnamen und deren Werte ab.
getArgument	Veraltet (Nicht mehr empfohlen) Entspricht get
multiselect	Erstellt ein Multiselect-Eingabe-Widget mit einem bestimmten Namen, Standardwert und Auswahlmöglichkeiten.
remove	Entfernt ein Eingabe-Widget aus dem Notizbuch.
removeAll	Entfernt alle Widgets im Notizbuch.
text	Erstellt ein Texteingabe-Widget mit einem bestimmten Namen und Standardwert.

combobox-Befehl (dbutils.widgets.combobox)

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

Erstellt ein Kombinationsfeld-Widget mit dem angegebenen programmatischen Namen, dem Standardwert, den Auswahlmöglichkeiten sowie einer optionalen Bezeichnung, und zeigt es an.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.widgets.help("combobox")

Beispiel

In diesem Beispiel wird ein Kombinationsfeld-Widget mit dem programmatischen Namen fruits_combobox erstellt und angezeigt. Es stellt die Optionen apple, banana, coconut und dragon fruit zur Auswahl und ist auf den Anfangswert banana festgelegt. Außerdem wird diesem combobox-Widget die Beschriftung Fruits zugeordnet. Am Ende dieses Beispiels wird der Anfangswert des Kombinationsfeld-Widgets (banana) ausgegeben.

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-Befehl (dbutils.widgets.dropdown)

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

Erstellt ein Dropdown-Widget mit dem angegebenen programmatischen Namen, dem Standardwert, den Auswahlmöglichkeiten sowie einer optionalen Bezeichnung, und zeigt es an.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.widgets.help("dropdown")

Beispiel

In diesem Beispiel wird ein Dropdown-Widget mit dem programmatischen Namen toys_dropdown erstellt und angezeigt. Es stellt die Optionen alphabet blocks, basketball, cape und doll zur Auswahl und ist auf den Anfangswert basketball festgelegt. Außerdem wird dem Dropdown-Widget die Beschriftung Toys zugeordnet. Am Ende dieses Beispiels wird der Anfangswert des Dropdown-Widgets (basketball) ausgegeben.

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

get-Befehl (dbutils.widgets.get)

get(name: String): String

Ruft den aktuellen Wert des Widgets mit dem angegebenen programmatischen Namen ab. Dieser programmatische Name kann einer der beiden folgenden sein:

• Der Name eines benutzerdefinierten Widgets im Notizbuch, z. B fruits_combobox . oder toys_dropdown.
• Der Name eines benutzerdefinierten Parameters, der als Teil einer Notebookaufgabe an das Notebook übergeben wird, z. B. name oder age. Weitere Informationen finden Sie im Abschnitt über die Parameter für Notebookaufgaben in der Benutzeroberfläche für Aufträge oder im Feld notebook_params des Vorgangs zum Auslösen einer neuen Auftragsausführung (POST /jobs/run-now) in der Auftrags-API.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.widgets.help("get")

Beispiel

In diesem Beispiel wird der Wert des Widgets mit dem programmatischen Namen fruits_combobox abgerufen.

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 diesem Beispiel wird der Wert des Parameters der Notebook-Aufgabe mit dem programmatischen Namen age abgerufen. Dieser Parameter wurde auf 35 festgelegt, als die zugehörige Notebookaufgabe ausgeführt wurde.

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

getAll-Befehl (dbutils.widgets.getAll)

getAll: map

Ruft eine Abbildung aller aktuellen Widget-Namen und -Werte ab. Dies kann besonders hilfreich sein, um Widgetwerte schnell an eine spark.sql() Abfrage zu übergeben.

Dieser Befehl ist in Databricks Runtime 13.3 LTS und höheren Versionen verfügbar. Es ist nur für Python und Scala verfügbar.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.widgets.help("getAll")

Beispiel

In diesem Beispiel wird die Zuordnung von Widgetwerten und als Parameterargumente in einer Spark SQL-Abfrage übergeben.

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

getArgument-Befehl (dbutils.widgets.getArgument)

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

Ruft den aktuellen Wert des Widgets mit dem angegebenen programmatischen Namen ab. Wenn das Widget nicht vorhanden ist, kann eine optionale Meldung zurückgegeben werden.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.widgets.help("getArgument")

Beispiel

In diesem Beispiel wird der Wert des Widgets mit dem programmatischen Namen fruits_combobox abgerufen. Wenn dieses Widget nicht vorhanden ist, wird die Meldung Error: Cannot find fruits combobox zurückgegeben.

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

multiselect-Befehl (dbutils.widgets.multiselect)

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

Erstellt ein Mehrfachauswahl-Widget mit dem angegebenen programmatischen Namen, dem Standardwert, den Auswahlmöglichkeiten sowie einer optionalen Bezeichnung, und zeigt es an.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.widgets.help("multiselect")

Beispiel

In diesem Beispiel wird ein Mehrfachauswahl-Widget mit dem programmatischen Namen days_multiselect erstellt und angezeigt. Es stellt die Optionen Monday bis Sunday zur Auswahl und ist auf den Anfangswert Tuesday festgelegt. Außerdem wird dem Mehrfachauswahl-Widget die Beschriftung Days of the Week zugeordnet. Am Ende dieses Beispiels wird der Anfangswert des Mehrfachauswahl-Widgets (Tuesday) ausgegeben.

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

remove-Befehl (dbutils.widgets.remove)

remove(name: String): void

Entfernt das Widget mit dem angegebenen programmatischen Namen.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.widgets.help("remove")

Beispiel

In diesem Beispiel wird das Widget mit dem programmatischen Namen fruits_combobox entfernt.

Python

dbutils.widgets.remove('fruits_combobox')

R

dbutils.widgets.remove('fruits_combobox')

Scala

dbutils.widgets.remove("fruits_combobox")

SQL

REMOVE WIDGET fruits_combobox

removeAll-Befehl (dbutils.widgets.removeAll)

removeAll: void

Entfernt alle Widgets aus dem Notebook.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.widgets.help("removeAll")

Beispiel

In diesem Beispiel werden alle Widgets aus dem Notebook entfernt.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

text-Befehl (dbutils.widgets.text)

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

Erstellt ein Text-Widget mit dem angegebenen programmatischen Namen, dem Standardwert sowie einer optionalen Bezeichnung, und zeigt es an.

Führen Sie Folgendes aus, um die vollständige Hilfe für diesen Befehl anzuzeigen:

dbutils.widgets.help("text")

Beispiel

In diesem Beispiel wird ein Text-Widget mit dem programmatischen Namen your_name_text erstellt und angezeigt. Es wird auf den Anfangswert Enter your name festgelegt. Außerdem wird dem Text-Widget die Beschriftung Your name zugeordnet. Am Ende dieses Beispiels wird der Anfangswert des Text-Widgets (Enter your name) ausgegeben.

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

API-Bibliothek für Databricks-Hilfsprogramme

Um die Anwendungsentwicklung zu beschleunigen, kann es nützlich sein, Anwendungen vor der Bereitstellung als Produktionsaufträge zu kompilieren, zu erstellen und zu testen. Um eine Kompilierung mit den Databricks-Hilfsprogrammen zu ermöglichen, stellt Databricks die Bibliothek dbutils-api zur Verfügung. Sie können die Bibliothek dbutils-api von der Webseite DBUtils API der Maven Repository-Website herunterladen oder die Bibliothek durch Hinzufügen einer Abhängigkeit in Ihre Builddatei einschließen:

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

Ersetzen Sie TARGET durch das gewünschte Ziel (z. B 2.12. ) und VERSION durch die gewünschte Version (z. B 0.0.5. ). Eine Liste der verfügbaren Ziele und Versionen finden Sie auf der Webseite DBUtils API der Maven Repository-Website.

Sobald Sie Ihre Anwendung mit dieser Bibliothek kompiliert haben, können Sie die Anwendung bereitstellen.

Einschränkungen

Das Aufrufen von dbutils innerhalb von Executoren kann zu unerwarteten Ergebnissen oder Fehlern führen.

Wenn Sie Dateisystemvorgänge auf Ausführungsinstanzen mit dbutilsausführen müssen, sehen Sie sich Parallelisierung von Dateisystemoperationenan.

Informationen zu Executors finden Sie unter Cluster Mode Overview (Clustermodus – Übersicht) auf der Apache Spark-Website.