Referenční informace k nástrojům`dbutils` Databricks

Článek
01/21/2025

Tento článek obsahuje referenční informace o nástrojích Databricks (dbutils). Nástroje poskytují příkazy, které umožňují pracovat s prostředím Databricks z poznámkových bloků. Můžete například spravovat soubory a úložiště objektů a pracovat s tajnými kódy. dbutils jsou k dispozici v poznámkových blocích pro Python, R a Scala.

Poznámka:

dbutils podporuje pouze výpočetní prostředí, která používají DBFS.

Užitkové moduly

Následující table uvádí moduly Databricks Utilities, které můžete načíst pomocí dbutils.help().

Modul	Popis
datových	Nástroje pro porozumění datovým sadám a interakci s nimi (EXPERIMENTÁLNÍ)
fs	Nástroje pro přístup k systému souborů Databricks (DBFS)
úloh	Nástroje pro využití funkcí úloh
knihovna	Zavrhovaný. Nástroje pro správu knihoven vymezených relacemi
poznámkový blok	Nástroje pro správu řízení toku poznámkových bloků (EXPERIMENTÁLNÍ)
tajemství	Nástroje pro využití tajných kódů v poznámkových blocích
widgety	Nástroje pro parametrizaci poznámkových bloků
API	Nástroje pro správu sestavení aplikací

Nápověda k příkazu

Pokud chcete list příkazy pro modul nástroje spolu s krátkým popisem každého příkazu, připojte .help() za název modulu nástroje. Následující příklad uvádí dostupné příkazy pro nástroj poznámkového bloku:

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

Pokud chcete zobrazit nápovědu k příkazu, spusťte dbutils.<utility-name>.help("<command-name>"). Následující příklad zobrazí nápovědu pro příkaz pro kopírování nástrojů systému souborů 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

Data utility (dbutils.data)

Důležité

Tato funkce je ve verzi Public Preview.

Poznámka:

K dispozici ve službě Databricks Runtime 9.0 a novějších.

Datový nástroj umožňuje porozumět datovým sadám a pracovat s nimi.

Následující table uvádí dostupné příkazy pro tento nástroj, které můžete načíst pomocí dbutils.data.help().

Příkaz	Popis
shrnutí	Shrnutí datového rámce Sparku a vizualizace statistik pro get rychlých přehledů

summarize command (dbutils.data.summarize)

Poznámka:

Tato funkce je ve verzi Public Preview.

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

Vypočítá a zobrazí souhrnné statistiky datového rámce Apache Spark nebo datového rámce pandas. Tento příkaz je k dispozici pro Python, Scala a R.

Důležité

Tento příkaz analyzuje úplný obsah datového rámce. Spuštění tohoto příkazu pro velmi velké datové rámce může být velmi nákladné.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.data.help("summarize")

V Databricks Runtime 10.4 LTS a vyšší můžete pomocí dalšího precise parametru upravit přesnost vypočítaných statistik.

Pokud je preciseset na false (výchozí), některé vrácené statistiky zahrnují aproximace, které snižují dobu běhu.
- Počet jedinečných values pro kategorické columns může mít relativní chybu ~5% pro columnss vysokou kardinalitou.
- Počet častých hodnot může mít chybu až 0,01%, pokud je počet jedinečných values větší než 10 000.
- Histogramy a percentilové odhady můžou mít chybu až 0,01 % vzhledem k celkovému počtu řádků.
Pokud je preciseset true, statistiky se počítají s vyšší přesností. Všechny statistiky s výjimkou histogramů a percentilů pro číselné columns jsou teď přesné.
- Histogramy a percentilové odhady můžou mít chybu až 0,0001 % vzhledem k celkovému počtu řádků.

Popis v horní části souhrnného výstupu dat označuje režim aktuálního spuštění.

Příklad

Tento příklad zobrazuje souhrnné statistiky pro datový rámec Apache Spark s povolenými aproximacemi ve výchozím nastavení. Pokud chcete zobrazit výsledky, spusťte tento příkaz v poznámkovém bloku. Tento příklad je založený na ukázkových datových sadách.

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)

Vizualizace používá notaci SI k stručné vykreslení číselných values menší než 0,01 nebo větší než 1 0000. Jako příklad se číselná hodnota 1.25e-15 vykreslí jako 1.25f. Jedna výjimka: Vizualizace místo "B" používá "1.0e9" pro (G).

Nástroj systému souborů (dbutils.fs)

Nástroj systému souborů umožňuje přístup k systému souborů DBFS?, což usnadňuje použití Azure Databricks jako systému souborů.

Upozorňující

Implementace Pythonu pro všechny dbutils.fs metody se používá snake_case místo camelCase formátování klíčových slov.

Například dbutils.fs.help() zobrazí možnost extraConfigs pro dbutils.fs.mount(). V Pythonu byste však použili klíčové slovo extra_configs.

Následující table uvádí dostupné příkazy pro tento nástroj, které můžete načíst pomocí dbutils.fs.help().

Příkaz	Popis
cp	Zkopíruje soubor nebo adresář, případně přes FileSystems.
hlavy	Vrátí až první bajty maxBytes daného souboru jako řetězec kódovaný v UTF-8.
ls	Vypíše obsah adresáře.
mkdirs	Vytvoří daný adresář, pokud neexistuje, a vytvoří také všechny nezbytné nadřazené adresáře.
přípojné	Připojí daný zdrojový adresář do DBFS v daném přípojném bodu.
držáky	Zobrazí informace o tom, co je připojené v systému souborů DBFS.
mv	Přesune soubor nebo adresář, případně přes FileSystems.
umístit	Zapíše daný řetězec do souboru zakódovaného v UTF-8.
refreshMounts	Vynutí, aby všechny počítače v tomto clusteru refresh jejich mezipaměť připojení a zajistily, že obdrží nejnovější informace.
rm	Odebere soubor nebo adresář.
odpojit	Odstraní přípojný bod DBFS.
aktualizovatMontáž	Podobá se mount(), ale aktualizuje existující bod místo vytvoření nového.

Spropitné

V poznámkových blocích můžete k přístupu k DBFS použít %fs příkaz magic. Například trasa %fs ls /Volumes/main/default/my-volume/ je stejná jako dbutils.fs.ls("/Volumes/main/default/my-volume/"). Podívejte se na magické příkazy.

cp command (dbutils.fs.cp)

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

Zkopíruje soubor nebo adresář, případně napříč systémy souborů.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("cp")

Příklad

Tento příklad zkopíruje soubor pojmenovaný data.csv ze /Volumes/main/default/my-volume/ stejného svazku do new-data.csv stejného svazku.

Python

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

# Out[4]: True

R

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

# [1] TRUE

Scala

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

// res3: Boolean = true

head command (dbutils.fs.head)

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

Vrátí až zadaný maximální počet bajtů v daném souboru. Bajty se vrátí jako řetězec s kódováním UTF-8.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("head")

Příklad

Tento příklad zobrazí prvních 25 bajtů souboru data.csv umístěného v /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"

Příkaz ls (dbutils.fs.ls)

ls(dir: String): Seq

Vypíše obsah adresáře.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("ls")

Příklad

Tento příklad zobrazuje informace o obsahu ./Volumes/main/default/my-volume/ Pole modificationTime je k dispozici v Databricks Runtime 10.4 LTS a vyšší. V jazyce R modificationTime se vrátí jako řetězec.

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

příkaz mkdirs (dbutils.fs.mkdirs)

mkdirs(dir: String): boolean

Vytvoří daný adresář, pokud neexistuje. Vytvoří také všechny nezbytné nadřazené adresáře.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("mkdirs")

Příklad

Tento příklad vytvoří adresář my-data v rámci /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

mount command (dbutils.fs.mount)

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

Připojí zadaný zdrojový adresář do systému souborů DBFS v zadaném přípojovém bodu.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("mount")

Příklad

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

Další příklady kódu najdete v tématu Připojení ke službě Azure Data Lake Storage Gen2 a Blob Storage.

mounts command (dbutils.fs.mounts)

mounts: Seq

Zobrazí informace o tom, co je aktuálně připojené v rámci DBFS.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("mounts")

Příklad

Upozorňující

Voláním dbutils.fs.refreshMounts() všech ostatních spuštěných clusterů rozšíříte nové připojení. Viz příkaz refreshMounts (dbutils.fs.refreshMounts).

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Další příklady kódu najdete v tématu Připojení ke službě Azure Data Lake Storage Gen2 a Blob Storage.

příkaz mv (dbutils.fs.mv)

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

Přesune soubor nebo adresář, případně napříč systémy souborů. Přesunutí je kopie následovaná odstraněním, a to i pro přesuny v rámci systému souborů.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("mv")

Příklad

Tento příklad přesune soubor rows.csv z /Volumes/main/default/my-volume/ do /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

Zapíše zadaný řetězec do souboru. Řetězec má kódování UTF-8.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("put")

Příklad

Tento příklad zapíše řetězec Hello, Databricks! do souboru pojmenovaného hello.txt v /Volumes/main/default/my-volume/. Pokud soubor existuje, přepíše se.

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

příkaz refreshMounts (dbutils.fs.refreshMounts)

refreshMounts: boolean

Vynutí, aby všechny počítače v clusteru refresh jejich mezipaměť připojení, čímž zajistí, že obdrží nejnovější informace.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("refreshMounts")

Příklad

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Příklady doplňkového kódu najdete v tématu Připojení ke službě Azure Data Lake Storage Gen2 a Blob Storage.

příkaz rm (dbutils.fs.rm)

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

Odebere soubor nebo adresář a volitelně i veškerý jeho obsah. Pokud je zadaný soubor, recurse parametr se ignoruje. Pokud je zadaný adresář, dojde k chybě, když recurse je zakázaný a adresář není prázdný.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("rm")

Příklad

Tento příklad odebere celý adresář /Volumes/main/default/my-volume/my-data/ včetně jeho obsahu.

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

unmount(mountPoint: String): boolean

Odstraní přípojný bod DBFS.

Upozorňující

Aby nedocházelo k chybám, nikdy neupravujte přípojný bod, zatímco ostatní úlohy ho čtou nebo zapisují do něj. Po úpravě připojení vždy spusťte dbutils.fs.refreshMounts() všechny ostatní spuštěné clustery, aby se všechny aktualizace připojení rozšířily. Viz příkaz refreshMounts (dbutils.fs.refreshMounts).

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("unmount")

Příklad

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

Další příklady kódu najdete v tématu Připojení ke službě Azure Data Lake Storage Gen2 a Blob Storage.

updateMount – příkaz (dbutils.fs.updateMount)

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

Podobá se dbutils.fs.mount příkazu, ale aktualizuje existující přípojný bod místo vytvoření nového. Vrátí chybu, pokud přípojný bod není k dispozici.

Upozorňující

Tento příkaz je k dispozici ve verzi Databricks Runtime 10.4 LTS a vyšší.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.fs.help("updateMount")

Příklad

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

Nástroj úlohy (dbutils.jobs)

Poskytuje nástroje pro využití funkcí úloh.

Poznámka:

Tento nástroj je k dispozici pouze pro Python.

Následující table uvádí dostupné moduly pro tento nástroj, které můžete načíst pomocí dbutils.jobs.help().

Podřízený modul	Popis
taskValues	Poskytuje nástroje pro využití úlohy values

subutility taskValues (dbutils.jobs.taskValues)

Poznámka:

Tato subutilita je k dispozici pouze pro Python.

Poskytuje příkazy pro využití úlohy values.

Pomocí tohoto dílčího nástroje můžete set a get libovolné values během spuštění úlohy. Tyto values se nazývají úkol values. Každý úkol může být getvaluesset od nadřazených úkolů a setvalues pro využití podřízenými úkoly.

Každá hodnota úkolu má jedinečný klíč ve stejném úkolu. Tento jedinečný klíč se označuje jako klíč hodnoty úkolu. K hodnotě úkolu se přistupuje s názvem úkolu a klíčem hodnoty úkolu. Můžete ho použít k předání informací z úkolu do úkolu v rámci stejného spuštění úlohy. Můžete například předat identifikátory nebo metriky, například informace o vyhodnocení modelu strojového učení, mezi různými úlohami v rámci spuštění úlohy.

Následující table uvádí dostupné příkazy pro tuto subutilitu, které můžete načíst pomocí dbutils.jobs.taskValues.help().

Příkaz	Popis
get	Získá obsah zadané hodnoty úkolu pro zadaný úkol v aktuálním spuštění úlohy.
set	Nastaví nebo aktualizuje hodnotu úkolu. Můžete spustit až 250 úloh pro běh úlohy setvalues.

příkaz get (dbutils.jobs.taskValues.get)

Poznámka:

Tento příkaz je k dispozici pouze pro Python.

V databricks Runtime 10.4 a starší, pokud get nelze najít úlohu, Py4JJavaError je vyvolána místo ValueError.

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

Získá obsah zadané hodnoty úkolu pro zadaný úkol v aktuálním spuštění úlohy.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

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

Příklad

Příklad:

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

V předchozím příkladu:

taskKey je název úkolu, který nastaví hodnotu úkolu. Pokud příkaz nemůže tento úkol najít, ValueError je vyvolán.
key je název klíče hodnoty úkolu, který jste set pomocí příkazu set (dbutils.jobs.taskValues.set). Pokud příkaz nemůže najít klíč této hodnoty úkolu, ValueError je vyvolána (pokud default není zadána).
default je volitelná hodnota, která se vrátí, pokud key nelze najít. default nemůže být None.
debugValue je volitelná hodnota, která se vrátí, pokud se pokusíte get hodnotu úkolu z poznámkového bloku, který běží mimo úlohu. To může být užitečné při ladění, když chcete poznámkový blok spustit ručně a vrátit nějakou hodnotu místo toho, abyste ve výchozím nastavení vyvolali TypeError nějakou hodnotu. debugValue nemůže být None.

Pokud se pokusíte vyvolat get hodnotu úkolu z poznámkového bloku, který běží mimo úlohu, tento příkaz ve výchozím nastavení vyvolá TypeError. Pokud debugValue je však argument zadán v příkazu, je vrácena hodnota debugValue namísto vyvolání TypeError.

příkaz set (dbutils.jobs.taskValues.set)

Poznámka:

Tento příkaz je k dispozici pouze pro Python.

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

Nastaví nebo aktualizuje hodnotu úkolu. Pro spuštění úlohy můžete set až 250 úloh values.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

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

Příklad

Mezi některé příklady patří:

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

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

V předchozích příkladech:

key je klíč hodnoty úkolu. Tento klíč musí být pro úkol jedinečný. To znamená, že pokud dva různé úkoly každý set hodnotu úkolu s klíčem K, jedná se o dva různé values úkolů, které mají stejný klíč K.
value je hodnota klíče této hodnoty úkolu. Tento příkaz musí být schopen interně reprezentovat hodnotu ve formátu JSON. Velikost reprezentace JSON hodnoty nesmí překročit 48 KiB.

Pokud se pokusíte set hodnotu úkolu z poznámkového bloku, který běží mimo úlohu, tento příkaz nedělá nic.

Nástroj knihovny (dbutils.library)

Většina metod v dílčím dbutils.library modulu je zastaralá. Viz Nástroj knihovny (dbutils.library) (starší verze).

Možná budete muset programově restartovat proces Pythonu v Azure Databricks, abyste zajistili, že místně nainstalované nebo upgradované knihovny fungují správně v jádru Pythonu pro vaši aktuální SparkSession. K těmto účelům spusťte příkaz dbutils.library.restartPython. Viz Restartování procesu Pythonu v Azure Databricks.

Nástroj poznámkového bloku (dbutils.notebook)

Nástroj poznámkového bloku umožňuje zřetězovat poznámkové bloky a pracovat s jejich výsledky. Viz Orchestrace poznámkových bloků a modularizace kódu v poznámkových blocích.

Následující table uvádí dostupné příkazy pro tento nástroj, které můžete načíst pomocí dbutils.notebook.help().

Příkaz	Popis
východ	Ukončí poznámkový blok s hodnotou.
spustit	Spustí poznámkový blok a vrátí jeho výstupní hodnotu.

příkaz exit (dbutils.notebook.exit)

exit(value: String): void

Ukončí poznámkový blok s hodnotou.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.notebook.help("exit")

Příklad

Tento příklad ukončí poznámkový blok s hodnotou 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

Poznámka:

Pokud má spuštění dotaz se strukturovaným streamováním spuštěným na pozadí, volání dbutils.notebook.exit() neukončí spuštění. Spuštění se bude i nadále spouštět, dokud se dotaz spouští na pozadí. Dotaz spuštěný na pozadí můžete zastavit kliknutím na tlačítko Storno v buňce dotazu nebo spuštěním query.stop()příkazu . Když se dotaz zastaví, můžete ukončit spuštění pomocí dbutils.notebook.exit()příkazu .

run command (dbutils.notebook.run)

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

Spustí poznámkový blok a vrátí jeho výstupní hodnotu. Poznámkový blok se ve výchozím nastavení spustí v aktuálním clusteru.

Poznámka:

Maximální délka řetězcové hodnoty vrácené příkazem run je 5 MB. Podívejte se na Get výstup pro jedno spuštění (GET /jobs/runs/get-output).

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.notebook.help("run")

Příklad

Tento příklad spustí poznámkový blok pojmenovaný My Other Notebook ve stejném umístění jako volající poznámkový blok. Volaný poznámkový blok končí řádkem kódu dbutils.notebook.exit("Exiting from My Other Notebook"). Pokud se volaný poznámkový blok nedokončí do 60 sekund, vyvolá se výjimka.

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

Nástroj Pro tajné kódy (dbutils.secrets)

Nástroj pro tajné kódy umožňuje ukládat citlivé informace o přihlašovacích údajích a přistupovat k nim bez jejich zobrazení v poznámkových blocích. Viz Správa tajných kódů a krok 3: Použití tajných kódů v poznámkovém bloku.

Následující table uvádí dostupné příkazy pro tento nástroj, které můžete načíst pomocí dbutils.secrets.help().

Příkaz	Popis
get	Získá řetězcové vyjádření tajné hodnoty s oborem a klíčem.
getBytes	Získá bajtovou reprezentaci tajné hodnoty podle rozsahu a klíče.
list	Vypíše tajná metadata pro důvěrné informace v rámci rozsahu.
listScopes	Seznam tajných rozsahů

příkaz get (dbutils.secrets.get)

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

Získá řetězcové vyjádření hodnoty tajného kódu pro zadaný obor tajných kódů a klíč.

Upozorňující

Správci, tvůrci tajných kódů a uživatelé s uděleným oprávněním mohou číst tajné kódy Azure Databricks. Zatímco se Azure Databricks snaží zakrýt tajemství values, které se mohou zobrazit v poznámkových blocích, není možné těmto uživatelům zabránit v čtení tajemství. Další informace najdete v tématu Redaction tajného kódu.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.secrets.help("get")

Příklad

Tento příklad získá řetězcovou reprezentaci hodnoty tajného klíče pro obor pojmenovaný my-scope a klíč s názvem 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 – příkaz (dbutils.secrets.getBytes)

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

Získá bajt reprezentaci tajné hodnoty pro zadaný obor a klíč.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.secrets.help("getBytes")

Příklad

Tento příklad získá bajt reprezentaci tajné hodnoty (v tomto příkladu a1!b2@c3#) pro obor pojmenovaný my-scope a klíč s názvem 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)

příkaz list (dbutils.secrets.list)

list(scope: String): Seq

Vypíše metadata tajných kódů v zadaném oboru.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.secrets.help("list")

Příklad

V tomto příkladu jsou uvedena metadata tajných kódů v oboru s názvem 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 – příkaz (dbutils.secrets.listScopes)

listScopes: Seq

Zobrazí seznam dostupných oborů.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.secrets.help("listScopes")

Příklad

V tomto příkladu jsou uvedeny dostupné obory.

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

Nástroj Widgets (dbutils.widgets)

Nástroj widgetů umožňuje parametrizovat poznámkové bloky. Viz widgety Databricks.

Následující table uvádí dostupné příkazy pro tento nástroj, které můžete načíst pomocí dbutils.widgets.help().

Příkaz	Popis
kombinované pole	Vytvoří vstupní pole se seznamem s daným názvem, výchozí hodnotou a volbami.
rozevírací seznam	Vytvoří vstupní widget rozevíracího seznamu s daným názvem, výchozí hodnotou a volbami.
get	Načte aktuální hodnotu vstupního widgetu.
getAll	Načte mapu všech názvů widgetů a jejich values
getArgument	Zavrhovaný. Ekvivalent get
vícenásobný výběr	Vytvoří widget pro vícenásobný výběr vstupu s daným názvem, výchozí hodnotou a volbami.
remove	Odebere vstupní widget z poznámkového bloku.
odebratVše	Odebere všechny widgety v poznámkovém bloku.
textové	Vytvoří widget pro zadávání textu s daným názvem a výchozí hodnotou.

příkaz combobox (dbutils.widgets.combobox)

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

Vytvoří a zobrazí widget se seznamem se zadaným názvem programu, výchozí hodnotou, volbami a volitelným popiskem.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.widgets.help("combobox")

Příklad

Tento příklad vytvoří a zobrazí widget pole se seznamem s programovým názvem fruits_combobox. Nabízí možnosti apple, banana, coconuta dragon fruit a je set na počáteční hodnotu banana. Tento widget pole se seznamem má doprovodný popisek Fruits. Tento příklad končí tiskem počáteční hodnoty widgetu se seznamem , 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

Vytvoří a zobrazí rozevírací widget se zadaným názvem programu, výchozí hodnotou, volbami a volitelným popiskem.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.widgets.help("dropdown")

Příklad

Tento příklad vytvoří a zobrazí rozevírací widget s programovým názvem toys_dropdown. Nabízí možnosti alphabet blocks, basketball, capea doll a je set na počáteční hodnotu basketball. Tento widget rozevíracího seznamu obsahuje doprovodný popisek Toys. Tento příklad končí tiskem počáteční hodnoty widgetu rozevíracího seznamu, 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

příkaz get (dbutils.widgets.get)

get(name: String): String

Získá aktuální hodnotu widgetu se zadaným názvem programu. Tento programový název může být následující:

Název vlastního widgetu v poznámkovém bloku, například fruits_combobox nebo toys_dropdown.
Název vlastního parametru předaného poznámkovému bloku jako součást úkolu poznámkového bloku, například name .age Další informace o pokrytí parameters pro úkoly poznámkového bloku naleznete v uživatelském rozhraní úloh nebo v poli notebook_params v operaci „Spuštění nové úlohy“ (POST /jobs/run-now) v rozhraní API úloh.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.widgets.help("get")

Příklad

Tento příklad získá hodnotu widgetu, který má programový název 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

Tento příklad získá hodnotu parametru úkolu poznámkového bloku, který má programový název age. Tento parametr byl v rozsahu od set až 35 při spuštění související úlohy poznámkového bloku.

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

příkaz getAll (dbutils.widgets.getAll)

getAll: map

Získá mapování všech aktuálních názvů widgetů a values. To může být užitečné zejména pro rychlé předání widgetu values do dotazu spark.sql().

Tento příkaz je k dispozici ve verzi Databricks Runtime 13.3 LTS a vyšší. Je k dispozici pouze pro Python a Scala.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.widgets.help("getAll")

Příklad

Tento příklad získá mapu widgetu values a předá ji jako argumenty parametrů v dotazu Spark SQL.

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 – příkaz (dbutils.widgets.getArgument)

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

Získá aktuální hodnotu widgetu se zadaným názvem programu. Pokud widget neexistuje, může se vrátit volitelná zpráva.

Poznámka:

Tento příkaz je zastaralý. Použijte dbutils.widgets.get.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.widgets.help("getArgument")

Příklad

Tento příklad získá hodnotu widgetu, který má programový název fruits_combobox. Pokud tento widget neexistuje, Error: Cannot find fruits combobox zpráva se vrátí.

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

příkaz multiselect (dbutils.widgets.multiselect)

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

Vytvoří a zobrazí widget s vícenásobným výběrem se zadaným názvem programu, výchozí hodnotou, volbami a volitelným popiskem.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.widgets.help("multiselect")

Příklad

Tento příklad vytvoří a zobrazí widget s vícenásobným výběrem s názvem days_multiselectprogramu . Nabízí možnosti Monday prostřednictvím Sunday a je set na počáteční hodnotu Tuesday. Tento widget s vícenásobným výběrem má doprovodný popisek Days of the Week. Tento příklad končí tiskem počáteční hodnoty widgetu multiselect, 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

příkaz remove (dbutils.widgets.remove)

remove(name: String): void

Odebere widget se zadaným názvem programu.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.widgets.help("remove")

Důležité

Pokud přidáte příkaz k remove widgetu, nemůžete přidat další příkaz pro vytvoření widgetu ve stejné buňce. Widget musíte vytvořit v jiné buňce.

Příklad

Tento příklad odebere widget s programovým názvem 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 – příkaz (dbutils.widgets.removeAll)

removeAll: void

Odebere všechny widgety z poznámkového bloku.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.widgets.help("removeAll")

Důležité

Pokud do remove všech widgetů přidáte příkaz, nebude možné přidat další příkaz pro vytvoření widgetů ve stejné buňce. Widgety musíte vytvořit v jiné buňce.

Příklad

Tento příklad odebere všechny widgety z poznámkového bloku.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

textový příkaz (dbutils.widgets.text)

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

Vytvoří a zobrazí textový widget se zadaným názvem programu, výchozí hodnotou a volitelným popiskem.

Pokud chcete zobrazit úplnou nápovědu pro tento příkaz, spusťte:

dbutils.widgets.help("text")

Příklad

Tento příklad vytvoří a zobrazí textový widget s programovým názvem your_name_text. Je to set k počáteční hodnotě Enter your name. Tento textový widget má doprovodný popisek Your name. Tento příklad končí tiskem počáteční hodnoty textového widgetu, 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

Knihovna rozhraní API pro nástroje Databricks

Důležité

Knihovna rozhraní Databricks Utilities API (dbutils-api) je zastaralá. Databricks doporučuje místo toho použít jednu z následujících možností:

K urychlení vývoje aplikací může být užitečné zkompilovat, sestavovat a testovat aplikace předtím, než je nasadíte jako produkční úlohy. Aby bylo možné zkompilovat nástroje Databricks, poskytuje Databricks knihovnu dbutils-api . Knihovnu dbutils-api si můžete stáhnout z webové stránky rozhraní DBUtils API na webu úložiště Maven nebo knihovnu zahrnout přidáním závislosti do souboru sestavení:

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'

Nahraďte TARGET požadovaným cílem (například 2.12) a VERSION požadovanou verzí (například 0.0.5). dostupných cílů a verzí najdete na webové stránce rozhraní API DBUtils na webu úložiště Maven.

Jakmile aplikaci sestavíte v této knihovně, můžete ji nasadit.

Důležité

Knihovna dbutils-api umožňuje pouze místně zkompilovat aplikaci, která ji používá dbutils, ne ke spuštění. Pokud chcete aplikaci spustit, musíte ji nasadit v Azure Databricks.

Omezení

Volání dbutils uvnitř vykonávajících procesů může produkovat neočekávané výsledky nebo chyby.

Pokud potřebujete spouštět operace se systémem souborů na executorech pomocí dbutils, podívejte se na metody paralelního výčtu a odstranění pomocí Sparku v Jak list a odstraňovat soubory rychleji v Databricks.

Informace o exekutorech najdete v tématu Přehled režimu clusteru na webu Apache Spark.

Sdílet prostřednictvím

Referenční informace k nástrojůmdbutils Databricks

Užitkové moduly

Nápověda k příkazu

Data utility (dbutils.data)

summarize command (dbutils.data.summarize)

Příklad

Python

R

Scala

Nástroj systému souborů (dbutils.fs)

cp command (dbutils.fs.cp)

Příklad

Python

R

Scala

head command (dbutils.fs.head)

Příklad

Python

R

Scala

Příkaz ls (dbutils.fs.ls)

Příklad

Python

R

Scala

příkaz mkdirs (dbutils.fs.mkdirs)

Příklad

Python

R

Scala

mount command (dbutils.fs.mount)

Příklad

Python

Scala

mounts command (dbutils.fs.mounts)

Příklad

Python

Scala

příkaz mv (dbutils.fs.mv)

Příklad

Python

R

Scala

put command (dbutils.fs.put)

Příklad

Python

R

Scala

příkaz refreshMounts (dbutils.fs.refreshMounts)

Příklad

Python

Scala

příkaz rm (dbutils.fs.rm)

Příklad

Python

R

Scala

unmount command (dbutils.fs.unmount)

Příklad

updateMount – příkaz (dbutils.fs.updateMount)

Příklad

Python

Scala

Nástroj úlohy (dbutils.jobs)

subutility taskValues (dbutils.jobs.taskValues)

příkaz get (dbutils.jobs.taskValues.get)

Příklad

příkaz set (dbutils.jobs.taskValues.set)

Příklad

Nástroj knihovny (dbutils.library)

Nástroj poznámkového bloku (dbutils.notebook)

příkaz exit (dbutils.notebook.exit)

Příklad

Python

R

Scala

run command (dbutils.notebook.run)

Příklad

Python

Referenční informace k nástrojům`dbutils` Databricks