Naslaginformatie over Databricks Utilities (dbutils)

  • Artikel

Dit artikel is een verwijzing voor Databricks Utilities (dbutils). dbutils Hulpprogramma's zijn beschikbaar in Python-, R- en Scala-notebooks. U kunt de hulpprogramma's gebruiken voor het volgende:

  • Werk efficiënt met bestanden en objectopslag.
  • Werken met geheimen.

Procedure: Lijstprogramma's, lijstopdrachten, Help voor weergaveopdrachten

Hulpprogramma's: gegevens, fs, taken, bibliotheek, notebook, geheimen, widgets, API-bibliotheek voor hulpprogramma's

Beschikbare hulpprogramma's weergeven

Als u beschikbare hulpprogramma's wilt weergeven, samen met een korte beschrijving voor elk hulpprogramma, voert u uit dbutils.help() voor Python of Scala.

In dit voorbeeld worden beschikbare opdrachten voor de Databricks Utilities weergegeven.

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

Beschikbare opdrachten voor een hulpprogramma weergeven

Als u beschikbare opdrachten voor een hulpprogramma wilt weergeven, samen met een korte beschrijving van elke opdracht, voert .help() u de opdracht uit na de programmatische naam voor het hulpprogramma.

In dit voorbeeld worden beschikbare opdrachten weergegeven voor het hulpprogramma Databricks File System (DBFS).

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

Help voor een opdracht weergeven

Als u help voor een opdracht wilt weergeven, voert u de opdrachtnaam .help("<command-name>") uit.

In dit voorbeeld wordt help weergegeven voor de opdracht DBFS kopiëren.

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

Hulpprogramma voor gegevens (dbutils.data)

Belangrijk

Deze functie is beschikbaar als openbare preview.

Notitie

Beschikbaar in Databricks Runtime 9.0 en hoger.

Opdrachten: samenvatten

Met het gegevenshulpprogramma kunt u gegevenssets begrijpen en interpreteren. Als u de beschikbare opdrachten wilt weergeven, voert u het volgende uit 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

opdracht summarize (dbutils.data.summarize)

Hiermee worden samenvattingsstatistieken van een Apache Spark DataFrame of pandas DataFrame berekend en weergegeven. Deze opdracht is beschikbaar voor Python, Scala en R.

Met deze opdracht wordt de volledige inhoud van het DataFrame geanalyseerd. Het uitvoeren van deze opdracht voor zeer grote DataFrames kan erg duur zijn.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.data.help("summarize").

In Databricks Runtime 10.4 LTS en hoger kunt u de extra precise parameter gebruiken om de precisie van de berekende statistieken aan te passen.

Notitie

Deze functie is beschikbaar als openbare preview.

  • Wanneer precise deze is ingesteld op onwaar (de standaardinstelling), bevatten sommige geretourneerde statistieken benaderingen om de uitvoeringstijd te verminderen.
    • Het aantal afzonderlijke waarden voor categorische kolommen kan een relatieve fout van ongeveer 5% hebben voor kolommen met hoge kardinaliteit.
    • Het aantal frequente waarden kan een fout hebben van maximaal 0,01% wanneer het aantal afzonderlijke waarden groter is dan 10000.
    • De histogrammen en percentielramingen kunnen een fout hebben van maximaal 0,01% ten opzichte van het totale aantal rijen.
  • Wanneer precise deze is ingesteld op true, worden de statistieken berekend met een hogere precisie. Alle statistieken, met uitzondering van de histogrammen en percentielen voor numerieke kolommen, zijn nu exact.
    • De histogrammen en percentielramingen kunnen een fout hebben van maximaal 0,0001% ten opzichte van het totale aantal rijen.

De knopinfo boven aan de uitvoer van de gegevenssamenvatting geeft de modus van de huidige uitvoering aan.

In dit voorbeeld worden samenvattingsstatistieken weergegeven voor een Apache Spark DataFrame met benaderingen die standaard zijn ingeschakeld. Als u de resultaten wilt zien, voert u deze opdracht uit in een notebook. Dit voorbeeld is gebaseerd op voorbeeldgegevenssets.

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)

Houd er rekening mee dat de visualisatie si-notatie gebruikt om beknopt numerieke waarden weer te geven die kleiner zijn dan 0,01 of groter dan 10000. Als voorbeeld wordt de numerieke waarde 1.25e-15 weergegeven als 1.25f. Eén uitzondering: de visualisatie maakt gebruik van 'B' voor 1.0e9 (giga) in plaats van 'G'.

Bestandssysteemhulpprogramma (dbutils.fs)

Waarschuwing

De Python-implementatie van alle dbutils.fs methoden gebruikt snake_case in plaats camelCase van voor trefwoordopmaak.

Bijvoorbeeld: tijdens dbutils.fs.help() het weergeven van de optie extraConfigs voor dbutils.fs.mount(), in Python zou u het trefwoord extra_configsgebruiken.

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

Met het bestandssysteemhulpprogramma hebt u toegang tot Wat is het Databricks File System (DBFS)?, waardoor u Azure Databricks eenvoudiger kunt gebruiken als bestandssysteem. Als u de beschikbare opdrachten wilt weergeven, voert u het volgende uit 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

cp-opdracht (dbutils.fs.cp)

Kopieert een bestand of map, mogelijk in meerdere bestandssysteemen.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("cp").

In dit voorbeeld wordt het bestand met de naam old_file.txt van /FileStore waaruit /tmp/newhet gekopieerde bestand wordt hernoemd, gekopieerd naar 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

hoofdopdracht (dbutils.fs.head)

Retourneert maximaal het opgegeven maximumaantal bytes van het opgegeven bestand. De bytes worden geretourneerd als een UTF-8-gecodeerde tekenreeks.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("head").

In dit voorbeeld worden de eerste 25 bytes van het bestand in het bestand my_file.txt weergegeven /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!
// "

ls-opdracht (dbutils.fs.ls)

Hiermee wordt de inhoud van een map weergegeven.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("ls").

In dit voorbeeld wordt informatie weergegeven over de inhoud van /tmp. Het modificationTime veld is beschikbaar in Databricks Runtime 10.4 LTS en hoger. In R wordt modificationTime deze geretourneerd als een tekenreeks.

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

mkdirs-opdracht (dbutils.fs.mkdirs)

Hiermee maakt u de opgegeven map als deze niet bestaat. Er worden ook eventuele benodigde bovenliggende mappen gemaakt.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("mkdirs").

In dit voorbeeld wordt de mapstructuur /parent/child/grandchild gemaakt binnen /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

opdracht koppelen (dbutils.fs.mount)

Koppelt de opgegeven bronmap aan DBFS op het opgegeven koppelpunt.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit 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>")))

Zie Verbinding maken naar Azure Data Lake Storage Gen2 en Blob Storage voor aanvullende codevoorbeelden.

opdracht mounts (dbutils.fs.mounts)

Geeft informatie weer over wat er momenteel is gekoppeld in DBFS.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("mounts").

Waarschuwing

Roep dbutils.fs.refreshMounts() alle andere actieve clusters aan om de nieuwe koppeling door te geven. Zie de opdracht refreshMounts (dbutils.fs.refreshMounts).

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Zie Verbinding maken naar Azure Data Lake Storage Gen2 en Blob Storage voor aanvullende codevoorbeelden.

mv command (dbutils.fs.mv)

Hiermee verplaatst u een bestand of map, mogelijk tussen bestandssysteemen. Een verplaatsing is een kopie gevolgd door een verwijdering, zelfs voor verplaatsingen binnen bestandssysteem.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("mv").

In dit voorbeeld wordt het bestand my_file.txt verplaatst naar /FileStore/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

opdracht put (dbutils.fs.put)

Hiermee schrijft u de opgegeven tekenreeks naar een bestand. De tekenreeks is UTF-8 gecodeerd.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("put").

In dit voorbeeld wordt de tekenreeks Hello, Databricks! geschreven naar een bestand met de naam hello_db.txt in /tmp. Als het bestand bestaat, wordt het overschreven.

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

opdracht refreshMounts (dbutils.fs.refreshMounts)

Dwingt alle machines in het cluster om de koppelcache te vernieuwen, zodat ze de meest recente informatie ontvangen.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("refreshMounts").

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Zie Verbinding maken naar Azure Data Lake Storage Gen2 en Blob Storage voor voorbeelden van aanvullende code.

rm-opdracht (dbutils.fs.rm)

Hiermee verwijdert u een bestand of map en eventueel alle inhoud. Als er een bestand is opgegeven, wordt de recurseparameter genegeerd. Als er een map is opgegeven, treedt er een fout op als recurse is uitgeschakeld en de map niet leeg is.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("rm").

In dit voorbeeld wordt de map /tmp verwijderd, inclusief de inhoud van de map.

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

opdracht ontkoppelen (dbutils.fs.unmount)

Hiermee verwijdert u een DBFS-koppelpunt.

Waarschuwing

Als u fouten wilt voorkomen, wijzigt u nooit een koppelpunt terwijl andere taken ernaar lezen of schrijven. Nadat u een koppeling hebt gewijzigd, moet u altijd worden uitgevoerd dbutils.fs.refreshMounts() op alle andere actieve clusters om eventuele koppelingsupdates door te geven. Zie de opdracht refreshMounts (dbutils.fs.refreshMounts).

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("unmount").

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

Zie Verbinding maken naar Azure Data Lake Storage Gen2 en Blob Storage voor aanvullende codevoorbeelden.

opdracht updateMount (dbutils.fs.updateMount)

Vergelijkbaar met de dbutils.fs.mount opdracht, maar werkt een bestaand koppelpunt bij in plaats van een nieuw koppelpunt te maken. Retourneert een fout als het koppelpunt niet aanwezig is.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.fs.help("updateMount").

Waarschuwing

Als u fouten wilt voorkomen, wijzigt u nooit een koppelpunt terwijl andere taken ernaar lezen of schrijven. Nadat u een koppeling hebt gewijzigd, moet u altijd worden uitgevoerd dbutils.fs.refreshMounts() op alle andere actieve clusters om eventuele koppelingsupdates door te geven. Zie de opdracht refreshMounts (dbutils.fs.refreshMounts).

Deze opdracht is beschikbaar in Databricks Runtime 10.4 LTS en hoger.

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

Hulpprogramma Taken (dbutils.jobs)

Subhulpprogramma's: taskValues

Notitie

Dit hulpprogramma is alleen beschikbaar voor Python.

Met het hulpprogramma jobs kunt u gebruikmaken van functies voor taken. Als u hulp voor dit hulpprogramma wilt weergeven, voert u het volgende uit dbutils.jobs.help().

Provides utilities for leveraging jobs features.

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

subutiliteit taskValues (dbutils.jobs.taskValues)

Opdrachten: ophalen, instellen

Notitie

Deze subutiliteit is alleen beschikbaar voor Python.

Biedt opdrachten voor het gebruik van taaktaakwaarden.

Gebruik dit subhulpprogramma om willekeurige waarden in te stellen en op te halen tijdens een taakuitvoering. Deze waarden worden taakwaarden genoemd. U kunt in dezelfde taakuitvoering toegang krijgen tot taakwaarden in downstreamtaken. U kunt bijvoorbeeld id's of metrische gegevens communiceren, zoals informatie over de evaluatie van een machine learning-model, tussen verschillende taken binnen een taakuitvoering. Elke taak kan meerdere taakwaarden instellen, ophalen of beide. Elke taakwaarde heeft een unieke sleutel binnen dezelfde taak. Deze unieke sleutel wordt de sleutel van de taakwaarde genoemd. Een taakwaarde wordt geopend met de taaknaam en de sleutel van de taakwaarde.

Als u hulp voor deze subutiliteit wilt weergeven, voert u uit dbutils.jobs.taskValues.help().

opdracht ophalen (dbutils.jobs.taskValues.get)

Notitie

Deze opdracht is alleen beschikbaar voor Python.

In Databricks Runtime 10.4 en eerder, als get de taak niet kan worden gevonden, wordt een Py4JJavaError gegenereerd in plaats van een ValueError.

Hiermee haalt u de inhoud van de opgegeven taakwaarde op voor de opgegeven taak in de huidige taakuitvoering.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.jobs.taskValues.help("get").

Voorbeeld:

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

In het voorgaande voorbeeld:

  • taskKey is de naam van de taak die de taakwaarde instelt. Als de opdracht deze taak niet kan vinden, wordt er een ValueError gegenereerd.
  • key is de naam van de sleutel van de taakwaarde die u hebt ingesteld met de setopdracht (dbutils.jobs.taskValues.set). Als de opdracht de sleutel van deze taakwaarde niet kan vinden, wordt er een ValueError gegenereerd (tenzij default opgegeven).
  • default is een optionele waarde die wordt geretourneerd als key deze niet kan worden gevonden. default kan niet zijn None.
  • debugValue is een optionele waarde die wordt geretourneerd als u de taakwaarde probeert op te halen vanuit een notebook die buiten een taak wordt uitgevoerd. Dit kan handig zijn tijdens foutopsporing wanneer u uw notebook handmatig wilt uitvoeren en een bepaalde waarde wilt retourneren in plaats van een standaardwaarde TypeError in te stellen. debugValue kan niet zijn None.

Als u probeert een taakwaarde op te halen vanuit een notebook dat buiten een taak wordt uitgevoerd, wordt met deze opdracht standaard een TypeError waarde gegenereerd. Als het debugValue argument echter is opgegeven in de opdracht, wordt de waarde debugValue geretourneerd in plaats van een TypeError.

opdracht set (dbutils.jobs.taskValues.set)

Notitie

Deze opdracht is alleen beschikbaar voor Python.

Hiermee stelt u een taakwaarde in of werkt u deze bij. U kunt maximaal 250 taakwaarden instellen voor een taakuitvoering.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.jobs.taskValues.help("set").

Enkele voorbeelden:

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

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

In de voorgaande voorbeelden:

  • key is de sleutel van de taakwaarde. Deze sleutel moet uniek zijn voor de taak. Als twee verschillende taken elk een taakwaarde met sleutel Kinstellen, zijn dit twee verschillende taakwaarden met dezelfde sleutel K.
  • value is de waarde voor de sleutel van deze taakwaarde. Met deze opdracht moet de waarde intern in JSON-indeling kunnen worden vertegenwoordigd. De grootte van de JSON-weergave van de waarde mag niet groter zijn dan 48 KiB.

Als u een taakwaarde probeert in te stellen vanuit een notebook dat buiten een taak wordt uitgevoerd, doet deze opdracht niets.

Bibliotheekhulpprogramma (dbutils.library)

De meeste methoden in de dbutils.library submodule zijn afgeschaft. Zie bibliotheekhulpprogramma (dbutils.library) (verouderd).

Mogelijk moet u het Python-proces op Azure Databricks programmatisch opnieuw opstarten om ervoor te zorgen dat lokaal geïnstalleerde of bijgewerkte bibliotheken correct werken in de Python-kernel voor uw huidige SparkSession. Voer de opdracht dbutils.library.restartPython uit om dit te doen. Zie Het Python-proces opnieuw opstarten in Azure Databricks.

Notebook-hulpprogramma (dbutils.notebook)

Opdrachten: afsluiten, uitvoeren

Met het hulpprogramma notebook kunt u notebooks koppelen en actie ondernemen op hun resultaten. Zie Een Databricks-notebook uitvoeren vanuit een ander notebook.

Als u de beschikbare opdrachten wilt weergeven, voert u het volgende uit 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.

afsluitopdracht (dbutils.notebook.exit)

Hiermee wordt een notitieblok afgesloten met een waarde.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.notebook.help("exit").

In dit voorbeeld wordt het notebook afgesloten met de waarde 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

Notitie

Als de uitvoering een query heeft met gestructureerde streaming die op de achtergrond wordt uitgevoerd, wordt de uitvoering niet beëindigd door aanroepen dbutils.notebook.exit() . De uitvoering wordt nog steeds uitgevoerd zolang de query op de achtergrond wordt uitgevoerd. U kunt de query die op de achtergrond wordt uitgevoerd stoppen door te klikken op Annuleren in de cel van de query of door uit te voeren query.stop(). Wanneer de query stopt, kunt u de uitvoering beëindigen met dbutils.notebook.exit().

opdracht uitvoeren (dbutils.notebook.run)

Voert een notebook uit en retourneert de afsluitwaarde. Het notebook wordt standaard uitgevoerd in het huidige cluster.

Notitie

De maximale lengte van de tekenreekswaarde die door de run opdracht wordt geretourneerd, is 5 MB. Zie Uitvoer ophalen voor één uitvoering (GET /jobs/runs/get-output).

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.notebook.help("run").

In dit voorbeeld wordt een notitieblok uitgevoerd met de naam My Other Notebook op dezelfde locatie als het aanroepende notitieblok. Het aangeroepen notebook eindigt met de coderegel dbutils.notebook.exit("Exiting from My Other Notebook"). Als het aangeroepen notebook niet binnen 60 seconden wordt uitgevoerd, wordt er een uitzondering gegenereerd.

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

Hulpprogramma geheimen (dbutils.secrets)

Opdrachten: get, getBytes, list, listScopes

Met het hulpprogramma geheimen kunt u gevoelige referentiegegevens opslaan en openen zonder ze zichtbaar te maken in notebooks. Zie Geheimbeheer en De geheimen gebruiken in een notebook. Als u de beschikbare opdrachten wilt weergeven, voert u het volgende uit 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

opdracht ophalen (dbutils.secrets.get)

Hiermee haalt u de tekenreeksweergave van een geheime waarde op voor het opgegeven geheimenbereik en de opgegeven sleutel.

Waarschuwing

Beheer istrators, geheimmakers en gebruikers die toestemming hebben verleend, kunnen Azure Databricks-geheimen lezen. Hoewel Azure Databricks moeite doet om geheime waarden te redacteren die in notebooks kunnen worden weergegeven, is het niet mogelijk om te voorkomen dat dergelijke gebruikers geheimen lezen. Zie Geheime redaction voor meer informatie.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.secrets.help("get").

In dit voorbeeld wordt de tekenreeksweergave van de geheime waarde voor het bereik met de naam en de sleutel opgehaald my-scopemy-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]

opdracht getBytes (dbutils.secrets.getBytes)

Hiermee haalt u de bytesweergave van een geheime waarde op voor het opgegeven bereik en de opgegeven sleutel.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.secrets.help("getBytes").

In dit voorbeeld wordt de byteweergave van de geheime waarde (in dit voorbeeld a1!b2@c3#) opgehaald voor het bereik met de naam my-scope en de sleutel met de naam 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)

list command (dbutils.secrets.list)

Toont de metagegevens voor geheimen binnen het opgegeven bereik.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.secrets.help("list").

In dit voorbeeld worden de metagegevens voor geheimen vermeld binnen het bereik met de naam 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))

listScopes-opdracht (dbutils.secrets.listScopes)

Hiermee worden de beschikbare bereiken weergegeven.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.secrets.help("listScopes").

In dit voorbeeld worden de beschikbare bereiken weergegeven.

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

Hulpprogramma Widgets (dbutils.widgets)

Opdrachten: keuzelijst met invoervak, vervolgkeuzelijst, ophalen, getArgument, multiselect, remove, removeAll, tekst

Met het hulpprogramma widgets kunt u notebooks parameteriseren. Zie Databricks-widgets.

Als u de beschikbare opdrachten wilt weergeven, voert u het volgende uit 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

opdracht keuzelijst met invoervak (dbutils.widgets.combobox)

Hiermee maakt en geeft u een widget met invoervak weer met de opgegeven programmatische naam, standaardwaarde, keuzes en optioneel label.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.widgets.help("combobox").

In dit voorbeeld wordt een widget met een keuzelijst met invoervak gemaakt en weergegeven met de programmatische naam fruits_combobox. Het biedt de keuzes apple, banana, en coconuten dragon fruit is ingesteld op de oorspronkelijke waarde van banana. Deze widget met invoervak heeft een bijbehorend label Fruits. Dit voorbeeld eindigt door de oorspronkelijke waarde van de widget keuzelijst met invoervak af te drukken. 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

vervolgkeuzelijst (dbutils.widgets.dropdown)

Hiermee maakt en geeft u een vervolgkeuzelijstwidget weer met de opgegeven programmatische naam, standaardwaarde, keuzes en optioneel label.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.widgets.help("dropdown").

In dit voorbeeld wordt een vervolgkeuzewidget gemaakt en weergegeven met de programmatische naam toys_dropdown. Het biedt de keuzes alphabet blocks, basketball, en capeen doll is ingesteld op de oorspronkelijke waarde van basketball. Deze vervolgkeuzelijstwidget heeft een bijbehorend label Toys. Dit voorbeeld eindigt door de oorspronkelijke waarde van de vervolgkeuzelijstwidget af te drukken. 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

opdracht ophalen (dbutils.widgets.get)

Hiermee haalt u de huidige waarde van de widget op met de opgegeven programmatische naam. Deze programmatische naam kan een van de volgende zijn:

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.widgets.help("get").

In dit voorbeeld wordt de waarde opgehaald van de widget met de programmatische naam 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

In dit voorbeeld wordt de waarde opgehaald van de notebook-taakparameter met de programmatische naam age. Deze parameter is ingesteld op 35 het moment dat de gerelateerde notebook-taak werd uitgevoerd.

Python

dbutils.widgets.get('age')

# 35

R

dbutils.widgets.get('age')

# [1] "35"

Scala

dbutils.widgets.get("age")

// res6: String = 35

opdracht getArgument (dbutils.widgets.getArgument)

Hiermee haalt u de huidige waarde van de widget op met de opgegeven programmatische naam. Als de widget niet bestaat, kan een optioneel bericht worden geretourneerd.

Notitie

Deze opdracht is afgeschaft. Gebruik in plaats daarvan dbutils.widgets.get .

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.widgets.help("getArgument").

In dit voorbeeld wordt de waarde opgehaald van de widget met de programmatische naam fruits_combobox. Als deze widget niet bestaat, wordt het bericht Error: Cannot find fruits combobox geretourneerd.

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

opdracht multiselect (dbutils.widgets.multiselect)

Hiermee maakt en geeft u een widget met meerdere selecties weer met de opgegeven programmatische naam, standaardwaarde, keuzes en optioneel label.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.widgets.help("multiselect").

In dit voorbeeld wordt een widget met meerdere selecties gemaakt en weergegeven met de programmatische naam days_multiselect. Het biedt de keuzes Monday door Sunday en wordt ingesteld op de oorspronkelijke waarde van Tuesday. Deze widget voor meerdere selecties heeft een bijbehorend label Days of the Week. Dit voorbeeld eindigt door de initiële waarde van de widget multiselect af te drukken, 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

opdracht verwijderen (dbutils.widgets.remove)

Hiermee verwijdert u de widget met de opgegeven programmatische naam.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.widgets.help("remove").

Belangrijk

Als u een opdracht toevoegt om een widget te verwijderen, kunt u geen volgende opdracht toevoegen om een widget in dezelfde cel te maken. U moet de widget maken in een andere cel.

In dit voorbeeld wordt de widget met de programmatische naam fruits_comboboxverwijderd.

Python

dbutils.widgets.remove('fruits_combobox')

R

dbutils.widgets.remove('fruits_combobox')

Scala

dbutils.widgets.remove("fruits_combobox")

removeAll-opdracht (dbutils.widgets.removeAll)

Hiermee verwijdert u alle widgets uit het notitieblok.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.widgets.help("removeAll").

Belangrijk

Als u een opdracht toevoegt om alle widgets te verwijderen, kunt u geen volgende opdracht toevoegen om widgets in dezelfde cel te maken. U moet de widgets in een andere cel maken.

In dit voorbeeld worden alle widgets uit het notitieblok verwijderd.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

tekstopdracht (dbutils.widgets.text)

Hiermee maakt en geeft u een tekstwidget weer met de opgegeven programmatische naam, standaardwaarde en optioneel label.

Als u help voor deze opdracht wilt weergeven, voert u het volgende uit dbutils.widgets.help("text").

In dit voorbeeld wordt een tekstwidget gemaakt en weergegeven met de programmatische naam your_name_text. De waarde is ingesteld op de oorspronkelijke waarde van Enter your name. Deze tekstwidget heeft een bijbehorend label Your name. Dit voorbeeld eindigt door de initiële waarde van de tekstwidget af te drukken. 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

Api-bibliotheek voor Databricks Utilities

Belangrijk

De Databricks Utilities API-bibliotheek (dbutils-api) is afgeschaft. Hoewel deze bibliotheek nog steeds beschikbaar is, plant Databricks geen nieuw functiewerk voor de dbutils-api bibliotheek.

Databricks raadt u aan een van de volgende bibliotheken te gebruiken:

Om de ontwikkeling van toepassingen te versnellen, kan het handig zijn om toepassingen te compileren, bouwen en testen voordat u ze implementeert als productietaken. Databricks biedt de dbutils-api bibliotheek om u te compileren op basis van Databricks Utilities. U kunt de dbutils-api bibliotheek downloaden van de DBUtils-API-webpagina op de website van de Maven-opslagplaats of de bibliotheek opnemen door een afhankelijkheid toe te voegen aan uw buildbestand:

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

Vervang door TARGET het gewenste doel (bijvoorbeeld 2.12) en VERSION door de gewenste versie (bijvoorbeeld 0.0.5). Zie de DBUtils-API-webpagina op de website van de Maven-opslagplaats voor een lijst met beschikbare doelen en versies.

Zodra u uw toepassing hebt gebouwd op basis van deze bibliotheek, kunt u de toepassing implementeren.

Belangrijk

Met de dbutils-api bibliotheek kunt u lokaal een toepassing compileren die gebruikmaakt dbutilsvan, maar niet om deze uit te voeren. Als u de toepassing wilt uitvoeren, moet u deze implementeren in Azure Databricks.

Beperkingen

Het aanroepen dbutils binnen uitvoerders kan onverwachte resultaten opleveren of mogelijk leiden tot fouten.

Als u bestandssysteembewerkingen op uitvoerders wilt uitvoeren met behulp van dbutils, zijn er verschillende snellere en schaalbare alternatieven beschikbaar:

Zie Overzicht van clustermodus op de Apache Spark-website voor meer informatie over uitvoerders.