Referens för Databricks Utilities (`dbutils`)

Artikel
01/21/2025

Den här artikeln innehåller referens för Databricks Utilities (dbutils). Verktygen tillhandahåller kommandon som gör att du kan arbeta med din Databricks-miljö från notebook-filer. Du kan till exempel hantera filer och objektlagring och arbeta med hemligheter. dbutils finns i Notebook-filer för Python, R och Scala.

Kommentar

dbutils stöder endast beräkningsmiljöer som använder DBFS.

-verktygsmoduler

I följande tabell visas modulerna Databricks Utilities som du kan hämta med hjälp av dbutils.help().

Modul	Beskrivning
data	Verktyg för att förstå och interagera med datamängder (EXPERIMENTAL)
fs	Verktyg för åtkomst till Databricks-filsystemet (DBFS)
jobb	Verktyg för att utnyttja jobbfunktioner
bibliotek	Föråldrad. Verktyg för att hantera bibliotek med sessionsomfattning
anteckningsbok	Verktyg för att hantera kontrollflöde för anteckningsböcker (EXPERIMENTAL)
hemligheter	Verktyg för att utnyttja hemligheter i notebook-filer
widgets	Verktyg för parameterisering av notebook-filer.
api	Verktyg för att hantera programversioner

Kommandohjälp för

Om du vill lista kommandon för en verktygsmodul tillsammans med en kort beskrivning av varje kommando lägger du till .help() efter namnet på verktygsmodulen. I följande exempel visas tillgängliga kommandon för notebook-verktyget:

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

Kör dbutils.<utility-name>.help("<command-name>")för att mata ut hjälp för ett kommando. I följande exempel visas hjälp för kopieringskommandot för filsystemverktyg, dbutils.fs.cp:

dbutils.fs.help("cp")

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

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.

Med dataverktyget kan du förstå och interagera med datauppsättningar.

I följande tabell visas de tillgängliga kommandona för det här verktyget, som du kan hämta med hjälp av dbutils.data.help().

Befallning	Beskrivning
sammanfatta	Sammanfatta en Spark DataFrame och visualisera statistiken för att få snabba insikter

summarize-kommandot (dbutils.data.summarize)

Kommentar

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

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

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.

Viktigt!

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 fullständig 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.

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 ~5% relativa fel 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 10000.
- 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.

Exempel

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)

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 (1.0e9) i stället för "G".

Filsystemverktyg (dbutils.fs)

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

Varning

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

Visar till exempel dbutils.fs.help() alternativet extraConfigs för dbutils.fs.mount(). Men i Python använder du nyckelordet extra_configs.

I följande tabell visas de tillgängliga kommandona för det här verktyget, som du kan hämta med hjälp av dbutils.fs.help().

Befallning	Beskrivning
cp	Kopierar en fil eller katalog, eventuellt över FileSystems
huvud	Returnerar upp till de första "maxBytes"-byteen för den angivna filen som en strängkodad i UTF-8
ls	Visar en lista över innehållet i en katalog
mkdirs	Skapar den angivna katalogen om den inte finns och skapar även nödvändiga överordnade kataloger
montera	Monterar den angivna källkatalogen i DBFS vid den angivna monteringspunkten
monterar	Visar information om vad som monteras i DBFS
mv	Flyttar en fil eller katalog, eventuellt över FileSystems
sätta	Skriver ut den angivna strängen till en fil, kodad i UTF-8
refreshMounts	Tvingar alla datorer i det här klustret att uppdatera sin monteringscache så att de får den senaste informationen
rm	Tar bort en fil eller katalog
demontera	Tar bort en DBFS-monteringspunkt
updateMount	Liknar mount(), men uppdaterar en befintlig monteringspunkt i stället för att skapa en ny

Tips

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

cp-kommando (dbutils.fs.cp)

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

Kopierar en fil eller katalog, eventuellt över filsystem.

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("cp")

Exempel

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)

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

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("head")

Exempel

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)

ls(dir: String): Seq

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("ls")

Exempel

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)

mkdirs(dir: String): boolean

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("mkdirs")

Exempel

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)

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

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("mount")

Exempel

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)

mounts: Seq

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("mounts")

Exempel

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)

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

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 fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("mv")

Exempel

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)

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

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("put")

Exempel

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)

refreshMounts: boolean

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("refreshMounts")

Exempel

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)

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

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 när recurse den är inaktiverad och katalogen inte är tom.

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("rm")

Exempel

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

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)

unmount(mountPoint: String): boolean

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 fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("unmount")

Exempel

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)

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

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.

Varning

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.fs.help("updateMount")

Exempel

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)

Tillhandahåller verktyg för att utnyttja jobbfunktioner.

Kommentar

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

I följande tabell visas de tillgängliga modulerna för det här verktyget, som du kan hämta med hjälp av dbutils.jobs.help().

Delmodul	Beskrivning
taskValues	Tillhandahåller verktyg för att utnyttja arbetsuppgiftsvärden

taskValues subutility (dbutils.jobs.taskValues)

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 uppgiftsvärden. Alla aktiviteter kan hämta värden som anges av överordnade aktiviteter och ange värden för underordnade aktiviteter som ska användas.

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. Du kan använda detta för att skicka information nedströms från aktivitet till uppgift inom samma jobbkörning. Du kan till exempel skicka identifierare eller mått, till exempel information om utvärderingen av en maskininlärningsmodell, mellan olika uppgifter inom en jobbkörning.

I följande tabell visas tillgängliga kommandon för den här underutnyttjandet, som du kan hämta med hjälp av dbutils.jobs.taskValues.help().

Befallning	Beskrivning
få	Hämtar innehållet i det angivna aktivitetsvärdet för den angivna aktiviteten i den aktuella jobbkörningen.
sätt	Anger eller uppdaterar ett aktivitetsvärde. Du kan definiera upp till 250 uppgiftsvärden för ett jobbkörningspass.

hämta 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.

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

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

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

Exempel

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å den uppgift 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 taskvärdet inifrån en notebook 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, kommer det här kommandot att som standard generera ett fel av typen TypeError. Men om debugValue argumentet anges i kommandot returneras värdet debugValue för i stället för att höja en TypeError.

ställ in kommando (dbutils.jobs.taskValues.set)

Kommentar

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

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

Anger eller uppdaterar ett aktivitetsvärde. Du kan definiera upp till 250 uppgiftsvärden för ett jobbkörningspass.

Om du vill visa fullständig hjälp för det här kommandot kör du:

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

Exempel

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)

Med notebook-verktyget kan du länka ihop notebook-filer och agera utifrån deras resultat. Se Orchestrate notebooks och modularisera kod i notebooks.

I följande tabell visas de tillgängliga kommandona för det här verktyget, som du kan hämta med hjälp av dbutils.notebook.help().

Befallning	Beskrivning
avsluta	Avslutar en notebook-fil med ett värde
köra	Kör en notebook-fil och returnerar dess slutvärde

exit command (dbutils.notebook.exit)

exit(value: String): void

Avslutar en notebook-fil med ett värde.

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.notebook.help("exit")

Exempel

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)

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

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 fullständig hjälp för det här kommandot kör du:

dbutils.notebook.help("run")

Exempel

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)

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 Steg 3: Använd hemligheterna i en notebook-fil.

I följande tabell visas de tillgängliga kommandona för det här verktyget, som du kan hämta med hjälp av dbutils.secrets.help().

Befallning	Beskrivning
få	Hämtar strängrepresentationen av ett hemligt värde med omfång och nyckel
getBytes	Hämtar byte-representationen av ett hemligt värde med omfattning och nyckel
lista	Visar en lista med hemliga metadata för hemligheter inom ett omfång
listScopes	Lista hemliga åtkomstområden

hämta kommandot (dbutils.secrets.get)

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

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 fullständig hjälp för det här kommandot kör du:

dbutils.secrets.help("get")

Exempel

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)

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

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.secrets.help("getBytes")

Exempel

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)

list(scope: String): Seq

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.secrets.help("list")

Exempel

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)

listScopes: Seq

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.secrets.help("listScopes")

Exempel

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)

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

I följande tabell visas de tillgängliga kommandona för det här verktyget, som du kan hämta med hjälp av dbutils.widgets.help().

Befallning	Beskrivning
kombinationsruta	Skapar en combobox-indatawidget med ett angivet namn, standardvärde och val
rullgardinsmeny	Skapar en rullgardinsmeny för inmatning med ett namn, standardvärde och alternativ
få	Hämtar aktuellt värde för en indatawidget
getAll	Hämtar en karta över alla widgetnamn och deras värden
getArgument	Föråldrad. Ekvivalent att hämta
flerurval	Skapar en multiselect-indatawidget med ett givet namn, standardvärde och val
ta bort	Tar bort en indatawidget från notebooken
ta bort alla	Tar bort alla widgetar i notebook-filen
text	Skapar en textinmatningswidget med ett förnamn och standardvärde

combobox-kommando (dbutils.widgets.combobox)

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

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.widgets.help("combobox")

Exempel

Det här exemplet skapar och visar en kombinationsruta med det programmatiska namnet fruits_combobox. Den erbjuder alternativen apple, banana, coconutoch dragon fruit och är inställt på det ursprungliga värdet för banana. 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

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

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.widgets.help("dropdown")

Exempel

Det här exemplet skapar och visar en listrutewidget med det programmatiska namnet toys_dropdown. Den erbjuder alternativen alphabet blocks, basketball, capeoch doll och är inställt på det ursprungliga värdet för basketball. 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)

get(name: String): String

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 om täckning av parametrar för notebook-uppdrag i jobbgränssnittet eller fältet notebook_params i operationen Initiera en ny körning av jobb (POST /jobs/run-now) i jobb-API:et.

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.widgets.help("get")

Exempel

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

getAll: map

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 fullständig hjälp för det här kommandot kör du:

dbutils.widgets.help("getAll")

Exempel

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)

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

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 fullständig hjälp för det här kommandot kör du:

dbutils.widgets.help("getArgument")

Exempel

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)

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

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.widgets.help("multiselect")

Exempel

Det här exemplet skapar och visar en multiselect-widget med det programmatiska namnet days_multiselect. Den erbjuder alternativen Monday till och med Sunday och är satt till 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 kommandot (dbutils.widgets.remove)

remove(name: String): void

Tar bort widgeten med det angivna programmatiska namnet.

Om du vill visa fullständig 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.

Exempel

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)

removeAll: void

Tar bort alla widgetar från notebook-filen.

Om du vill visa fullständig 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.

Exempel

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)

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

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

Om du vill visa fullständig hjälp för det här kommandot kör du:

dbutils.widgets.help("text")

Exempel

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. Databricks rekommenderar att du använder något av följande 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 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 bara kompilera ett program lokalt som använder dbutils, inte för att köra det. Om du vill köra programmet måste du distribuera det i Azure Databricks.

Begränsningar

Att anropa dbutils i exekveringsmiljöer kan ge oväntade resultat eller fel.

Om du behöver köra filsystemåtgärder på utförare med hjälp av dbutils, hänvisar du till metoderna för parallell listning och borttagning med Spark i Hur du listar och tar bort filer snabbare med Databricks.

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

Dela via

Referens för Databricks Utilities (dbutils)

-verktygsmoduler

Kommandohjälp för

Dataverktyg (dbutils.data)

summarize-kommandot (dbutils.data.summarize)

Exempel

Python

R

Scala

Filsystemverktyg (dbutils.fs)

cp-kommando (dbutils.fs.cp)

Exempel

Python

R

Scala

huvudkommando (dbutils.fs.head)

Exempel

Python

R

Scala

ls-kommandot (dbutils.fs.ls)

Exempel

Python

R

Scala

kommandot mkdirs (dbutils.fs.mkdirs)

Exempel

Python

R

Scala

monteringskommando (dbutils.fs.mount)

Exempel

Python

Scala

mounts command (dbutils.fs.mounts)

Exempel

Python

Scala

mv-kommando (dbutils.fs.mv)

Exempel

Python

R

Scala

put command (dbutils.fs.put)

Exempel

Python

R

Scala

refreshMounts-kommandot (dbutils.fs.refreshMounts)

Exempel

Python

Scala

rm-kommando (dbutils.fs.rm)

Exempel

Python

R

Scala

unmount-kommando (dbutils.fs.unmount)

Exempel

updateMount-kommando (dbutils.fs.updateMount)

Exempel

Python

Scala

Jobbverktyget (dbutils.jobs)

taskValues subutility (dbutils.jobs.taskValues)

hämta kommandot (dbutils.jobs.taskValues.get)

Exempel

ställ in kommando (dbutils.jobs.taskValues.set)

Exempel

Biblioteksverktyget (dbutils.library)

Notebook-verktyget (dbutils.notebook)

exit command (dbutils.notebook.exit)

Exempel

Python

R

Scala

kör kommandot (dbutils.notebook.run)

Exempel

Python

Referens för Databricks Utilities (`dbutils`)