Dela via

Referens för Databricks Utilities (dbutils)

  • Artikel

Den här artikeln är en referens för Databricks Utilities (dbutils). dbutils Verktyg är tillgängliga i Notebook-filer för Python, R och Scala. Du kan använda verktygen för att:

  • Arbeta effektivt med filer och objektlagring.
  • Arbeta med hemligheter.

Anvisningar: Lista verktyg, listkommandon, visa kommandohjälp

Verktyg: data, fs, jobb, bibliotek, notebook-fil, hemligheter, widgetar, API-bibliotek för verktyg

Lista tillgängliga verktyg

Om du vill visa en lista över tillgängliga verktyg tillsammans med en kort beskrivning för varje verktyg kör du dbutils.help() för Python eller Scala.

I det här exemplet visas tillgängliga kommandon för Databricks Utilities.

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

Lista tillgängliga kommandon för ett verktyg

Om du vill visa tillgängliga kommandon för ett verktyg tillsammans med en kort beskrivning av varje kommando kör .help() du efter det programmatiska namnet för verktyget.

I det här exemplet visas tillgängliga kommandon för dbfs-verktyget (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

Visa hjälp för ett kommando

Om du vill visa hjälp för ett kommando kör du .help("<command-name>") efter kommandonamnet.

I det här exemplet visas hjälp för DBFS-kopieringskommandot.

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

Dataverktyg (dbutils.data)

Viktigt!

Den här funktionen finns som allmänt tillgänglig förhandsversion.

Kommentar

Tillgänglig i Databricks Runtime 9.0 och senare.

Kommandon: sammanfatta

Med dataverktyget kan du förstå och tolka datauppsättningar. Om du vill visa en lista över tillgängliga kommandon kör du 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

summarize-kommandot (dbutils.data.summarize)

Beräknar och visar sammanfattningsstatistik för en Apache Spark DataFrame eller Pandas DataFrame. Det här kommandot är tillgängligt för Python, Scala och R.

Det här kommandot analyserar det fullständiga innehållet i DataFrame. Det kan vara mycket dyrt att köra det här kommandot för mycket stora DataFrames.

Om du vill visa hjälp för det här kommandot kör du dbutils.data.help("summarize").

I Databricks Runtime 10.4 LTS och senare kan du använda den extra precise parametern för att justera precisionen för den beräknade statistiken.

Kommentar

Den här funktionen finns som allmänt tillgänglig förhandsversion.

  • När precise är inställt på false (standard) innehåller vissa returnerade statistik uppskattningar för att minska körningstiden.
    • Antalet distinkta värden för kategoriska kolumner kan ha ett relativt fel på ~5 % för kolumner med hög kardinalitet.
    • Antalet frekventa värden kan ha ett fel på upp till 0,01 % när antalet distinkta värden är större än 1 0000.
    • Histogram och percentiluppskattningar kan ha ett fel på upp till 0,01 % i förhållande till det totala antalet rader.
  • När precise är inställt på sant beräknas statistiken med högre precision. All statistik förutom histogram och percentiler för numeriska kolumner är nu exakta.
    • Histogram och percentiluppskattningar kan ha ett fel på upp till 0,0001 % i förhållande till det totala antalet rader.

Knappbeskrivningen överst i datasammanfattningens utdata anger läget för den aktuella körningen.

I det här exemplet visas sammanfattningsstatistik för en Apache Spark DataFrame med approximationer aktiverade som standard. Om du vill se resultatet kör du det här kommandot i en notebook-fil. Det här exemplet baseras på exempeldatauppsättningar.

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)

Observera att visualiseringen använder SI-notation för att kortfattat återge numeriska värden som är mindre än 0,01 eller större än 1 0000. Till exempel återges det numeriska värdet 1.25e-15 som 1.25f. Ett undantag: visualiseringen använder "B" för (giga) i stället för 1.0e9 "G".

Filsystemverktyg (dbutils.fs)

Varning

Python-implementeringen av alla dbutils.fs metoder använder snake_case i stället camelCase för nyckelordsformatering.

Till exempel: när dbutils.fs.help() du visar alternativet extraConfigs för dbutils.fs.mount()i Python använder du nyckelordet extra_configs.

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

Med filsystemverktyget kan du komma åt Vad är DBFS?, vilket gör det enklare att använda Azure Databricks som ett filsystem.

I notebook-filer kan du också använda det %fs magiska kommandot för att komma åt DBFS. Till exempel %fs ls /Volumes/main/default/my-volume/ är samma som dbutils.fs.ls("/Volumes/main/default/my-volume/"). Se magiska kommandon.

Om du vill visa en lista över tillgängliga kommandon kör du 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-kommando (dbutils.fs.cp)

Kopierar en fil eller katalog, eventuellt över filsystem.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("cp").

I det här exemplet kopieras filen med namnet data.csv från /Volumes/main/default/my-volume/ till new-data.csv i samma volym.

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

huvudkommando (dbutils.fs.head)

Returnerar upp till det angivna maximala antalet byte för den angivna filen. Byte returneras som en UTF-8-kodad sträng.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("head").

I det här exemplet visas de första 25 byteen av filen data.csv som finns i /Volumes/main/default/my-volume/.

Python

dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)

# [Truncated to first 25 bytes]
# Out[12]: 'Year,First Name,County,Se'

R

dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)

# [1] "Year,First Name,County,Se"

Scala

dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)

// [Truncated to first 25 bytes]
// res4: String =
// "Year,First Name,County,Se"

ls-kommandot (dbutils.fs.ls)

Visar en lista över innehållet i en katalog.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("ls").

Det här exemplet visar information om innehållet i /Volumes/main/default/my-volume/. Fältet modificationTime är tillgängligt i Databricks Runtime 10.4 LTS och senare. I R modificationTime returneras som en sträng.

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

kommandot mkdirs (dbutils.fs.mkdirs)

Skapar den angivna katalogen om den inte finns. Skapar även alla nödvändiga överordnade kataloger.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("mkdirs").

Det här exemplet skapar katalogen my-data i /Volumes/main/default/my-volume/.

Python

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

# Out[15]: True

R

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

# [1] TRUE

Scala

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

// res7: Boolean = true

monteringskommando (dbutils.fs.mount)

Monterar den angivna källkatalogen i DBFS vid den angivna monteringspunkten.

Om du vill visa hjälp för det här kommandot kör du 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>")))

Ytterligare kodexempel finns i Ansluta till Azure Data Lake Storage Gen2 och Blob Storage.

mounts command (dbutils.fs.mounts)

Visar information om vad som för närvarande är monterat i DBFS.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("mounts").

Varning

Anropa dbutils.fs.refreshMounts() alla andra kluster som körs för att sprida den nya monteringen. Se refreshMounts-kommandot (dbutils.fs.refreshMounts).

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Ytterligare kodexempel finns i Ansluta till Azure Data Lake Storage Gen2 och Blob Storage.

mv-kommando (dbutils.fs.mv)

Flyttar en fil eller katalog, eventuellt mellan filsystem. En flytt är en kopia följt av en borttagning, även för flyttningar i filsystem.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("mv").

Det här exemplet flyttar filen rows.csv från /Volumes/main/default/my-volume/ till /Volumes/main/default/my-volume/my-data/.

Python

dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")

# Out[2]: True

R

dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")

# [1] TRUE

Scala

dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")

// res1: Boolean = true

put command (dbutils.fs.put)

Skriver den angivna strängen till en fil. Strängen är UTF-8-kodad.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("put").

Det här exemplet skriver strängen Hello, Databricks! till en fil med namnet hello.txt i /Volumes/main/default/my-volume/. Om filen finns skrivs den över.

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-kommandot (dbutils.fs.refreshMounts)

Tvingar alla datorer i klustret att uppdatera sin monteringscache så att de får den senaste informationen.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("refreshMounts").

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Exempel på tilläggskod finns i Ansluta till Azure Data Lake Storage Gen2 och Blob Storage.

rm-kommando (dbutils.fs.rm)

Tar bort en fil eller katalog och eventuellt allt dess innehåll. Om en fil anges ignoreras parametern recurse. Om en katalog har angetts uppstår ett fel om rekursen är inaktiverad och katalogen inte är tom.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("rm").

Det här exemplet tar bort katalogen /Volumes/main/default/my-volume/my-data/ inklusive innehållet i katalogen.

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-kommando (dbutils.fs.unmount)

Tar bort en DBFS-monteringspunkt.

Varning

Undvik fel genom att aldrig ändra en monteringspunkt medan andra jobb läser eller skriver till den. När du har modifierat en montering kör dbutils.fs.refreshMounts() du alltid på alla andra kluster som körs för att sprida eventuella monteringsuppdateringar. Se refreshMounts-kommandot (dbutils.fs.refreshMounts).

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("unmount").

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

Ytterligare kodexempel finns i Ansluta till Azure Data Lake Storage Gen2 och Blob Storage.

updateMount-kommando (dbutils.fs.updateMount)

dbutils.fs.mount Liknar kommandot, men uppdaterar en befintlig monteringspunkt i stället för att skapa en ny. Returnerar ett fel om monteringspunkten inte finns.

Om du vill visa hjälp för det här kommandot kör du dbutils.fs.help("updateMount").

Varning

Undvik fel genom att aldrig ändra en monteringspunkt medan andra jobb läser eller skriver till den. När du har modifierat en montering kör dbutils.fs.refreshMounts() du alltid på alla andra kluster som körs för att sprida eventuella monteringsuppdateringar. Se refreshMounts-kommandot (dbutils.fs.refreshMounts).

Det här kommandot är tillgängligt i Databricks Runtime 10.4 LTS och senare.

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

Jobbverktyget (dbutils.jobs)

Underverktyg: taskValues

Kommentar

Det här verktyget är endast tillgängligt för Python.

Med jobbverktyget kan du använda jobbfunktioner. Om du vill visa hjälp för det här verktyget kör du dbutils.jobs.help().

Provides utilities for leveraging jobs features.

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

taskValues subutility (dbutils.jobs.taskValues)

Kommandon: hämta, ange

Kommentar

Den här subutiliteten är endast tillgänglig för Python.

Innehåller kommandon för att utnyttja jobbaktivitetsvärden.

Använd det här underverktyget för att ange och hämta godtyckliga värden under en jobbkörning. Dessa värden kallas för aktivitetsvärden. Du kan komma åt aktivitetsvärden i underordnade aktiviteter i samma jobbkörning. Du kan till exempel kommunicera identifierare eller mått, till exempel information om utvärderingen av en maskininlärningsmodell, mellan olika uppgifter inom en jobbkörning. Varje aktivitet kan ange flera aktivitetsvärden, hämta dem eller båda. Varje aktivitetsvärde har en unik nyckel i samma aktivitet. Den här unika nyckeln kallas för aktivitetsvärdets nyckel. Ett aktivitetsvärde nås med uppgiftsnamnet och aktivitetsvärdets nyckel.

Om du vill visa hjälp för den här underutnyttjandet kör du dbutils.jobs.taskValues.help().

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

Kommentar

Det här kommandot är endast tillgängligt för Python.

På Databricks Runtime 10.4 och tidigare, om get det inte går att hitta uppgiften, genereras en Py4JJavaError i stället för en ValueError.

Hämtar innehållet i det angivna aktivitetsvärdet för den angivna aktiviteten i den aktuella jobbkörningen.

Om du vill visa hjälp för det här kommandot kör du dbutils.jobs.taskValues.help("get").

Till exempel:

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

I exemplet ovan händer följande:

  • taskKey är namnet på aktiviteten som anger aktivitetsvärdet. Om kommandot inte kan hitta den här uppgiften utlöses en ValueError .
  • key är namnet på aktivitetsvärdets nyckel som du anger med kommandot set (dbutils.jobs.taskValues.set). Om kommandot inte kan hitta det här aktivitetsvärdets nyckel utlöses en ValueError (såvida inte default anges).
  • default är ett valfritt värde som returneras om key det inte går att hitta. default kan inte vara None.
  • debugValue är ett valfritt värde som returneras om du försöker hämta aktivitetsvärdet inifrån en notebook-fil som körs utanför ett jobb. Detta kan vara användbart vid felsökning när du vill köra notebook-filen manuellt och returnera ett värde i stället för att höja ett TypeError som standard. debugValue kan inte vara None.

Om du försöker hämta ett aktivitetsvärde inifrån en notebook-fil som körs utanför ett jobb genererar det här kommandot ett TypeError som standard. Men om debugValue argumentet anges i kommandot returneras värdet debugValue för i stället för att höja en TypeError.

set command (dbutils.jobs.taskValues.set)

Kommentar

Det här kommandot är endast tillgängligt för Python.

Anger eller uppdaterar ett aktivitetsvärde. Du kan konfigurera upp till 250 aktivitetsvärden för en jobbkörning.

Om du vill visa hjälp för det här kommandot kör du dbutils.jobs.taskValues.help("set").

Vissa exempel inkluderar:

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

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

I föregående exempel:

  • key är aktivitetsvärdets nyckel. Den här nyckeln måste vara unik för uppgiften. Om två olika aktiviteter var och en anger ett aktivitetsvärde med nyckeln Kär det två olika aktivitetsvärden som har samma nyckel K.
  • value är värdet för det här aktivitetsvärdets nyckel. Det här kommandot måste kunna representera värdet internt i JSON-format. Storleken på JSON-representationen av värdet får inte överstiga 48 KiB.

Om du försöker ange ett aktivitetsvärde inifrån en notebook-fil som körs utanför ett jobb gör det här kommandot ingenting.

Biblioteksverktyget (dbutils.library)

De flesta metoder i undermodulen dbutils.library är inaktuella. Se Biblioteksverktyget (dbutils.library) (äldre).

Du kan behöva starta om Python-processen på Azure Databricks programmatiskt för att säkerställa att lokalt installerade eller uppgraderade bibliotek fungerar korrekt i Python-kerneln för din aktuella SparkSession. Gör detta via kommandot dbutils.library.restartPython. Se Starta om Python-processen i Azure Databricks.

Notebook-verktyget (dbutils.notebook)

Kommandon: avsluta, kör

Med notebook-verktyget kan du länka ihop notebook-filer och agera utifrån deras resultat. Se Kör en Databricks-anteckningsbok från en annan notebook-fil.

Om du vill visa en lista över tillgängliga kommandon kör du 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.

exit command (dbutils.notebook.exit)

Avslutar en notebook-fil med ett värde.

Om du vill visa hjälp för det här kommandot kör du dbutils.notebook.help("exit").

Det här exemplet avslutar notebook-filen med värdet 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

Kommentar

Om körningen har en fråga med strukturerad direktuppspelning som körs i bakgrunden avslutar inte anropet dbutils.notebook.exit() körningen. Körningen fortsätter att köras så länge frågan körs i bakgrunden. Du kan stoppa frågan som körs i bakgrunden genom att klicka på Avbryt i frågans cell eller genom att köra query.stop(). När frågan stoppas kan du avsluta körningen med dbutils.notebook.exit().

kör kommandot (dbutils.notebook.run)

Kör en notebook-fil och returnerar dess slutvärde. Notebook-filen körs som standard i det aktuella klustret.

Kommentar

Den maximala längden på strängvärdet som returneras från run kommandot är 5 MB. Se Hämta utdata för en enda körning (GET /jobs/runs/get-output).

Om du vill visa hjälp för det här kommandot kör du dbutils.notebook.help("run").

Det här exemplet kör en notebook-fil med namnet My Other Notebook på samma plats som den anropande anteckningsboken. Den anropade notebook-filen slutar med kodraden dbutils.notebook.exit("Exiting from My Other Notebook"). Om den anropade notebook-filen inte har körts inom 60 sekunder genereras ett undantag.

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-verktyget (dbutils.secrets)

Kommandon: get, getBytes, list, listScopes

Med verktyget hemligheter kan du lagra och komma åt känslig information om autentiseringsuppgifter utan att göra dem synliga i notebook-filer. Se Hemlig hantering och Använda hemligheterna i en notebook-fil. Om du vill visa en lista över tillgängliga kommandon kör du 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

get-kommandot (dbutils.secrets.get)

Hämtar strängrepresentationen av ett hemligt värde för det angivna hemlighetsomfånget och nyckeln.

Varning

Administratörer, hemliga skapare och användare som beviljats behörighet kan läsa Azure Databricks-hemligheter. Även om Azure Databricks gör ett försök att redigera hemliga värden som kan visas i notebook-filer, går det inte att hindra sådana användare från att läsa hemligheter. Mer information finns i Hemlig redigering.

Om du vill visa hjälp för det här kommandot kör du dbutils.secrets.help("get").

Det här exemplet hämtar strängrepresentationen av det hemliga värdet för omfånget med namnet my-scope och nyckeln med namnet 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]

getBytes-kommandot (dbutils.secrets.getBytes)

Hämtar byterepresentationen av ett hemligt värde för det angivna omfånget och nyckeln.

Om du vill visa hjälp för det här kommandot kör du dbutils.secrets.help("getBytes").

Det här exemplet hämtar byterepresentationen av det hemliga värdet (i det här exemplet a1!b2@c3#) för omfånget med namnet my-scope och nyckeln med namnet 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)

listkommando (dbutils.secrets.list)

Visar en lista över metadata för hemligheter inom det angivna omfånget.

Om du vill visa hjälp för det här kommandot kör du dbutils.secrets.help("list").

I det här exemplet visas metadata för hemligheter inom omfånget med namnet 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-kommandot (dbutils.secrets.listScopes)

Visar en lista över tillgängliga omfång.

Om du vill visa hjälp för det här kommandot kör du dbutils.secrets.help("listScopes").

I det här exemplet visas tillgängliga omfång.

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

Kommandon: kombinationsruta, listruta, get, getArgument, multiselect, remove, removeAll, text

Med widgetverktyget kan du parametrisera notebook-filer. Se Databricks-widgetar.

Om du vill visa en lista över tillgängliga kommandon kör du dbutils.widgets.help().

combobox(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a combobox input widget with a given name, default value and choices
dropdown(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a dropdown input widget a with given name, default value and choices
get(name: String): String -> Retrieves current value of an input widget
getAll: map -> Retrieves a map of all widget names and their values
getArgument(name: String, optional: String): String -> (DEPRECATED) Equivalent to get
multiselect(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a multiselect input widget with a given name, default value and choices
remove(name: String): void -> Removes an input widget from the notebook
removeAll: void -> Removes all widgets in the notebook
text(name: String, defaultValue: String, label: String): void -> Creates a text input widget with a given name and default value

combobox-kommando (dbutils.widgets.combobox)

Skapar och visar en widget i kombinationsrutan med det angivna programmatiska namnet, standardvärdet, valen och den valfria etiketten.

Om du vill visa hjälp för det här kommandot kör du dbutils.widgets.help("combobox").

Det här exemplet skapar och visar en kombinationsruta med det programmatiska namnet fruits_combobox. Den erbjuder alternativen apple, banana, coconutoch och dragon fruit är inställt på det ursprungliga värdet bananaför . Den här kombinationsrutewidgeten har en tillhörande etikett Fruits. Det här exemplet slutar med att skriva ut det initiala värdet för kombinationsrutans widget, banana.

Python

dbutils.widgets.combobox(
  name='fruits_combobox',
  defaultValue='banana',
  choices=['apple', 'banana', 'coconut', 'dragon fruit'],
  label='Fruits'
)

print(dbutils.widgets.get("fruits_combobox"))

# banana

R

dbutils.widgets.combobox(
  name='fruits_combobox',
  defaultValue='banana',
  choices=list('apple', 'banana', 'coconut', 'dragon fruit'),
  label='Fruits'
)

print(dbutils.widgets.get("fruits_combobox"))

# [1] "banana"

Scala

dbutils.widgets.combobox(
  "fruits_combobox",
  "banana",
  Array("apple", "banana", "coconut", "dragon fruit"),
  "Fruits"
)

print(dbutils.widgets.get("fruits_combobox"))

// banana

SQL

CREATE WIDGET COMBOBOX fruits_combobox DEFAULT "banana" CHOICES SELECT * FROM (VALUES ("apple"), ("banana"), ("coconut"), ("dragon fruit"))

SELECT :fruits_combobox

-- banana

listrutekommando (dbutils.widgets.dropdown)

Skapar och visar en listrutewidget med angivet programmatiskt namn, standardvärde, val och valfri etikett.

Om du vill visa hjälp för det här kommandot kör du dbutils.widgets.help("dropdown").

Det här exemplet skapar och visar en listrutewidget med det programmatiska namnet toys_dropdown. Den erbjuder alternativen alphabet blocks, basketball, capeoch och doll är inställt på det ursprungliga värdet basketballför . Den här listrutewidgeten har en tillhörande etikett Toys. Det här exemplet slutar med att skriva ut det inledande värdet för listrutewidgeten, basketball.

Python

dbutils.widgets.dropdown(
  name='toys_dropdown',
  defaultValue='basketball',
  choices=['alphabet blocks', 'basketball', 'cape', 'doll'],
  label='Toys'
)

print(dbutils.widgets.get("toys_dropdown"))

# basketball

R

dbutils.widgets.dropdown(
  name='toys_dropdown',
  defaultValue='basketball',
  choices=list('alphabet blocks', 'basketball', 'cape', 'doll'),
  label='Toys'
)

print(dbutils.widgets.get("toys_dropdown"))

# [1] "basketball"

Scala

dbutils.widgets.dropdown(
  "toys_dropdown",
  "basketball",
  Array("alphabet blocks", "basketball", "cape", "doll"),
  "Toys"
)

print(dbutils.widgets.get("toys_dropdown"))

// basketball

SQL

CREATE WIDGET DROPDOWN toys_dropdown DEFAULT "basketball" CHOICES SELECT * FROM (VALUES ("alphabet blocks"), ("basketball"), ("cape"), ("doll"))

SELECT :toys_dropdown

-- basketball

hämta kommandot (dbutils.widgets.get)

Hämtar det aktuella värdet för widgeten med det angivna programmatiska namnet. Det här programmatiska namnet kan vara antingen:

  • Namnet på en anpassad widget i notebook-filen, till exempel fruits_combobox eller toys_dropdown.
  • Namnet på en anpassad parameter som skickas till notebook-filen som en del av en notebook-uppgift, till exempel name eller age. Mer information finns i täckningen av parametrar för notebook-uppgifter i jobbgränssnittet eller notebook_params fältet i åtgärden Utlösa en ny jobbkörning (POST /jobs/run-now) i jobb-API:et.

Om du vill visa hjälp för det här kommandot kör du dbutils.widgets.help("get").

Det här exemplet hämtar värdet för widgeten som har det programmatiska namnet fruits_combobox.

Python

dbutils.widgets.get('fruits_combobox')

# banana

R

dbutils.widgets.get('fruits_combobox')

# [1] "banana"

Scala

dbutils.widgets.get("fruits_combobox")

// res6: String = banana

SQL

SELECT :fruits_combobox

-- banana

Det här exemplet hämtar värdet för notebook-aktivitetsparametern som har det programmatiska namnet age. Den här parametern angavs till 35 när den relaterade notebook-uppgiften kördes.

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-kommandot (dbutils.widgets.getAll)

Hämtar en mappning av alla aktuella widgetnamn och värden. Detta kan vara särskilt användbart för att snabbt skicka widgetvärden till en spark.sql() fråga.

Det här kommandot är tillgängligt i Databricks Runtime 13.3 LTS och senare. Den är endast tillgänglig för Python och Scala.

Om du vill visa hjälp för det här kommandot kör du dbutils.widgets.help("getAll").

Det här exemplet hämtar kartan över widgetvärden och skickar den som parameterargument i en Spark SQL-fråga.

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-kommando (dbutils.widgets.getArgument)

Hämtar det aktuella värdet för widgeten med det angivna programmatiska namnet. Om widgeten inte finns kan ett valfritt meddelande returneras.

Kommentar

Det här kommandot är inaktuellt. Använd dbutils.widgets.get i stället.

Om du vill visa hjälp för det här kommandot kör du dbutils.widgets.help("getArgument").

Det här exemplet hämtar värdet för widgeten som har det programmatiska namnet fruits_combobox. Om den här widgeten inte finns returneras meddelandet 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

multiselect-kommando (dbutils.widgets.multiselect)

Skapar och visar en multiselect-widget med angivet programmatiskt namn, standardvärde, val och valfri etikett.

Om du vill visa hjälp för det här kommandot kör du dbutils.widgets.help("multiselect").

Det här exemplet skapar och visar en multiselect-widget med det programmatiska namnet days_multiselect. Den erbjuder alternativen Monday genom Sunday och är inställd på det ursprungliga värdet för Tuesday. Den här multiselect-widgeten har en tillhörande etikett Days of the Week. Det här exemplet slutar med att skriva ut det inledande värdet för multiselect-widgeten, Tuesday.

Python

dbutils.widgets.multiselect(
  name='days_multiselect',
  defaultValue='Tuesday',
  choices=['Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday', 'Sunday'],
  label='Days of the Week'
)

print(dbutils.widgets.get("days_multiselect"))

# Tuesday

R

dbutils.widgets.multiselect(
  name='days_multiselect',
  defaultValue='Tuesday',
  choices=list('Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday', 'Sunday'),
  label='Days of the Week'
)

print(dbutils.widgets.get("days_multiselect"))

# [1] "Tuesday"

Scala

dbutils.widgets.multiselect(
  "days_multiselect",
  "Tuesday",
  Array("Monday", "Tuesday", "Wednesday", "Thursday",
    "Friday", "Saturday", "Sunday"),
  "Days of the Week"
)

print(dbutils.widgets.get("days_multiselect"))

// Tuesday

SQL

CREATE WIDGET MULTISELECT days_multiselect DEFAULT "Tuesday" CHOICES SELECT * FROM (VALUES ("Monday"), ("Tuesday"), ("Wednesday"), ("Thursday"), ("Friday"), ("Saturday"), ("Sunday"))

SELECT :days_multiselect

-- Tuesday

ta bort kommando (dbutils.widgets.remove)

Tar bort widgeten med det angivna programmatiska namnet.

Om du vill visa hjälp för det här kommandot kör du dbutils.widgets.help("remove").

Viktigt!

Om du lägger till ett kommando för att ta bort en widget kan du inte lägga till ett efterföljande kommando för att skapa en widget i samma cell. Du måste skapa widgeten i en annan cell.

Det här exemplet tar bort widgeten med det programmatiska namnet fruits_combobox.

Python

dbutils.widgets.remove('fruits_combobox')

R

dbutils.widgets.remove('fruits_combobox')

Scala

dbutils.widgets.remove("fruits_combobox")

SQL

REMOVE WIDGET fruits_combobox

removeAll-kommandot (dbutils.widgets.removeAll)

Tar bort alla widgetar från notebook-filen.

Om du vill visa hjälp för det här kommandot kör du dbutils.widgets.help("removeAll").

Viktigt!

Om du lägger till ett kommando för att ta bort alla widgetar kan du inte lägga till ett efterföljande kommando för att skapa widgetar i samma cell. Du måste skapa widgetarna i en annan cell.

Det här exemplet tar bort alla widgetar från notebook-filen.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

textkommando (dbutils.widgets.text)

Skapar och visar en textwidget med det angivna programmatiska namnet, standardvärdet och den valfria etiketten.

Om du vill visa hjälp för det här kommandot kör du dbutils.widgets.help("text").

Det här exemplet skapar och visar en textwidget med det programmatiska namnet your_name_text. Det är inställt på det ursprungliga värdet för Enter your name. Den här textwidgeten har en tillhörande etikett Your name. Det här exemplet slutar med att skriva ut det inledande värdet för textwidgeten, Enter your name.

Python

dbutils.widgets.text(
  name='your_name_text',
  defaultValue='Enter your name',
  label='Your name'
)

print(dbutils.widgets.get("your_name_text"))

# Enter your name

R

dbutils.widgets.text(
  name='your_name_text',
  defaultValue='Enter your name',
  label='Your name'
)

print(dbutils.widgets.get("your_name_text"))

# [1] "Enter your name"

Scala

dbutils.widgets.text(
  "your_name_text",
  "Enter your name",
  "Your name"
)

print(dbutils.widgets.get("your_name_text"))

// Enter your name

SQL

CREATE WIDGET TEXT your_name_text DEFAULT "Enter your name"

SELECT :your_name_text

-- Enter your name

Api-bibliotek för Databricks Utilities

Viktigt!

Databricks Utilities API-biblioteket (dbutils-api) är inaktuellt. Även om det här biblioteket fortfarande är tillgängligt planerar Databricks inget nytt funktionsarbete för dbutils-api biblioteket.

Databricks rekommenderar att du använder något av följande bibliotek i stället:

För att påskynda programutvecklingen kan det vara bra att kompilera, skapa och testa program innan du distribuerar dem som produktionsjobb. För att du ska kunna kompilera mot Databricks Utilities tillhandahåller dbutils-api Databricks biblioteket. Du kan ladda ned dbutils-api biblioteket från DBUtils API-webbsidan på webbplatsen för Maven-lagringsplatsen eller inkludera biblioteket genom att lägga till ett beroende i byggfilen:

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

Ersätt TARGET med önskat mål (till exempel 2.12) och VERSION med önskad version (till exempel 0.0.5). En lista över tillgängliga mål och versioner finns på webbplatsen för DBUtils API på webbplatsen för Maven-lagringsplatsen.

När du har skapat programmet mot det här biblioteket kan du distribuera programmet.

Viktigt!

Med dbutils-api biblioteket kan du kompilera ett program lokalt som använder dbutils, men inte köra det. Om du vill köra programmet måste du distribuera det i Azure Databricks.

Begränsningar

Att anropa dbutils inuti utförare kan ge oväntade resultat eller potentiellt resultera i fel.

Om du behöver köra filsystemåtgärder på utförare med hjälp av dbutilsfinns det flera snabbare och mer skalbara alternativ:

Information om köre finns i Översikt över klusterläge på Apache Spark-webbplatsen.