Referenční informace k nástrojůmdbutils
Databricks
Tento článek je referencí pro nástroje Databricks (dbutils
). dbutils
Nástroje jsou k dispozici v poznámkových blocích Python, R a Scala. Tyto nástroje můžete použít k:
- Efektivně pracovat se soubory a úložištěm objektů
- Práce s tajnými kódy
Poznámka:
dbutils
podporuje pouze výpočetní prostředí, která používají DBFS.
Postupy: Výpis nástrojů, příkazů seznamu, nápověda k příkazu zobrazení
Nástroje: data, fs, úlohy, knihovna, poznámkový blok, tajné kódy, widgety, knihovna rozhraní API nástrojů
Seznam dostupných nástrojů
Pokud chcete zobrazit seznam dostupných nástrojů spolu s krátkým popisem jednotlivých nástrojů, spusťte dbutils.help()
pro Python nebo Scala.
Tento příklad obsahuje seznam dostupných příkazů pro nástroje Databricks.
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
Výpis dostupných příkazů pro nástroj
Seznam dostupných příkazů pro nástroj spolu s krátkým popisem každého příkazu spusťte .help()
za programovým názvem nástroje.
V tomto příkladu jsou uvedeny dostupné příkazy pro nástroj Databricks File System (DBFS).
Python
dbutils.fs.help()
R
dbutils.fs.help()
Scala
dbutils.fs.help()
dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".
fsutils
cp(from: String, to: String, recurse: boolean = false): boolean -> Copies a file or directory, possibly across FileSystems
head(file: String, maxBytes: int = 65536): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
ls(dir: String): Seq -> Lists the contents of a directory
mkdirs(dir: String): boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
mv(from: String, to: String, recurse: boolean = false): boolean -> Moves a file or directory, possibly across FileSystems
put(file: String, contents: String, overwrite: boolean = false): boolean -> Writes the given String out to a file, encoded in UTF-8
rm(dir: String, recurse: boolean = false): boolean -> Removes a file or directory
mount
mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Mounts the given source directory into DBFS at the given mount point
mounts: Seq -> Displays information about what is mounted within DBFS
refreshMounts: boolean -> Forces all machines in this cluster to refresh their mount cache, ensuring they receive the most recent information
unmount(mountPoint: String): boolean -> Deletes a DBFS mount point
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one
Zobrazení nápovědy k příkazu
Nápovědu k příkazu zobrazíte spuštěním .help("<command-name>")
za názvem příkazu.
Tento příklad zobrazí nápovědu pro příkaz kopírování DBFS.
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
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.
Příkazy: sumarizovat
Datový nástroj umožňuje pochopit a interpretovat datové sady. Seznam dostupných příkazů zobrazíte spuštěním dbutils.data.help()
příkazu .
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 command (dbutils.data.summarize)
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.
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é.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.data.help("summarize")
příkaz .
V Databricks Runtime 10.4 LTS a vyšší můžete pomocí dalšího precise
parametru upravit přesnost vypočítaných statistik.
Poznámka:
Tato funkce je ve verzi Public Preview.
- Pokud
precise
je nastavena na false (výchozí), některé vrácené statistiky zahrnují aproximace, které zkracují dobu běhu.- Počet jedinečných hodnot pro sloupce kategorií může mít pro sloupce s vysokou kardinalitou přibližně 5 % relativní chybu.
- Počet častých hodnot může mít chybu až 0,01 %, pokud je počet jedinečných hodnot větší než 1 0000.
- Histogramy a percentilové odhady můžou mít chybu až 0,01 % vzhledem k celkovému počtu řádků.
- Pokud
precise
je nastavena hodnota true, statistiky se počítají s vyšší přesností. Všechny statistiky s výjimkou histogramů a percentilů pro číselné sloupce 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í.
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á zápis SI k stručné vykreslení číselných hodnot menších než 0,01 nebo větších než 1 0000. Jako příklad se číselná hodnota 1.25e-15
vykreslí jako 1.25f
. Jedna výjimka: Vizualizace místo "G
" používá "B
" pro 1.0e9
(giga).
Nástroj systému souborů (dbutils.fs)
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
.
Příkazy: cp, head, ls, mkdirs, mount, mounts, mv, put, refreshMounts, rm, unmount, updateMount
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ů.
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 duties.fs.ls("/Volumes/main/default/my-volume/")
. Podívejte se na magické příkazy.
Seznam dostupných příkazů zobrazíte spuštěním dbutils.fs.help()
příkazu .
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 command (dbutils.fs.cp)
Zkopíruje soubor nebo adresář, případně napříč systémy souborů.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("cp")
příkaz .
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)
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.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("head")
příkaz .
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)
Vypíše obsah adresáře.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("ls")
příkaz .
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)
Vytvoří daný adresář, pokud neexistuje. Vytvoří také všechny nezbytné nadřazené adresáře.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("mkdirs")
příkaz .
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)
Připojí zadaný zdrojový adresář do systému souborů DBFS v zadaném přípojovém bodu.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("mount")
příkaz .
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)
Zobrazí informace o tom, co je aktuálně připojené v rámci DBFS.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("mounts")
příkaz .
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)
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ů.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("mv")
příkaz .
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)
Zapíše zadaný řetězec do souboru. Řetězec má kódování UTF-8.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("put")
příkaz .
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)
Vynutí, aby všechny počítače v clusteru aktualizovaly mezipaměť připojení a zajistily, že obdrží nejnovější informace.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("refreshMounts")
příkaz .
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)
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ý.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("rm")
příkaz .
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)
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).
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("unmount")
příkaz .
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)
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.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.fs.help("updateMount")
příkaz .
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).
Tento příkaz je k dispozici ve verzi Databricks Runtime 10.4 LTS a vyšší.
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)
Dílčí nástroje: taskValues
Poznámka:
Tento nástroj je k dispozici pouze pro Python.
Nástroj úloh umožňuje využívat funkce úloh. Chcete-li zobrazit nápovědu pro tento nástroj, spusťte dbutils.jobs.help()
.
Provides utilities for leveraging jobs features.
taskValues: TaskValuesUtils -> Provides utilities for leveraging job task values
subutility taskValues (dbutils.jobs.taskValues)
Poznámka:
Tato subutilita je k dispozici pouze pro Python.
Poskytuje příkazy pro využití hodnot úkolů úloh.
Tento dílčí nástroj slouží k nastavení a získání libovolných hodnot během spuštění úlohy. Tyto hodnoty se nazývají hodnoty úkolů. Každý úkol může získat hodnoty nastavené nadřazenými úkoly a nastavit hodnoty pro podřízené úkoly, které se mají použít.
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.
Pokud chcete zobrazit nápovědu pro tuto podutilitu, spusťte dbutils.jobs.taskValues.help()
příkaz .
get command (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
.
Získá obsah zadané hodnoty úkolu pro zadaný úkol v aktuálním spuštění úlohy.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.jobs.taskValues.help("get")
příkaz .
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 nastavili pomocí příkazu set (dbutils.jobs.taskValues.set). Pokud příkaz nemůže najít klíč této hodnoty úkolu,ValueError
je vyvolána (pokuddefault
není zadána).default
je volitelná hodnota, která se vrátí, pokudkey
nelze najít.default
nemůže býtNone
.debugValue
je volitelná hodnota, která se vrátí, pokud se pokusíte získat 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í vyvolaliTypeError
nějakou hodnotu.debugValue
nemůže býtNone
.
Pokud se pokusíte získat hodnotu úkolu z poznámkového bloku, který běží mimo úlohu, tento příkaz ve výchozím nastavení vyvolá TypeError
hodnotu. Pokud debugValue
je však argument zadán v příkazu, je vrácena hodnota debugValue
namísto vyvolání TypeError
.
set – příkaz (dbutils.jobs.taskValues.set)
Poznámka:
Tento příkaz je k dispozici pouze pro Python.
Nastaví nebo aktualizuje hodnotu úkolu. Pro spuštění úlohy můžete nastavit až 250 hodnot úkolu.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.jobs.taskValues.help("set")
příkaz .
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 nastaví hodnotu úkolu s klíčemK
, jedná se o dvě různé hodnoty ú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 nastavit 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 Spuštění poznámkového bloku Databricks z jiného poznámkového bloku.
Seznam dostupných příkazů zobrazíte spuštěním dbutils.notebook.help()
příkazu .
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.
příkaz exit (dbutils.notebook.exit)
Ukončí poznámkový blok s hodnotou.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.notebook.help("exit")
příkaz .
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)
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. Viz Získání výstupu pro jedno spuštění (GET /jobs/runs/get-output
).
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.notebook.help("run")
příkaz .
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)
Příkazy: get, getBytes, list, listScopes
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. Seznam dostupných příkazů zobrazíte spuštěním dbutils.secrets.help()
příkazu .
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 – příkaz (dbutils.secrets.get)
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 Azure Databricks se snaží redakčně upravovat tajné hodnoty, které se můžou zobrazovat v poznámkových blocích, není možné těmto uživatelům zabránit v čtení tajných kódů. Další informace najdete v tématu Redaction tajného kódu.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.secrets.help("get")
příkaz .
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)
Získá bajt reprezentaci tajné hodnoty pro zadaný obor a klíč.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.secrets.help("getBytes")
příkaz .
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)
list command (dbutils.secrets.list)
Vypíše metadata tajných kódů v zadaném oboru.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.secrets.help("list")
příkaz .
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)
Zobrazí seznam dostupných oborů.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.secrets.help("listScopes")
příkaz .
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)
Příkazy: pole se seznamem, rozevírací seznam, get, getArgument, multiselect, remove, removeAll, text
Nástroj widgetů umožňuje parametrizovat poznámkové bloky. Viz widgety Databricks.
Seznam dostupných příkazů zobrazíte spuštěním dbutils.widgets.help()
příkazu .
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
příkaz combobox (dbutils.widgets.combobox)
Vytvoří a zobrazí widget se seznamem se zadaným názvem programu, výchozí hodnotou, volbami a volitelným popiskem.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.widgets.help("combobox")
příkaz .
Tento příklad vytvoří a zobrazí widget pole se seznamem s programovým názvem fruits_combobox
. Nabízí volby apple
, banana
, coconut
a dragon fruit
je nastavena 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 command (dbutils.widgets.dropdown)
Vytvoří a zobrazí rozevírací widget se zadaným názvem programu, výchozí hodnotou, volbami a volitelným popiskem.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.widgets.help("dropdown")
příkaz .
Tento příklad vytvoří a zobrazí rozevírací widget s programovým názvem toys_dropdown
. Nabízí volby alphabet blocks
, basketball
, cape
a doll
je nastavena 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
get command (dbutils.widgets.get)
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
nebotoys_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 najdete v pokrytí parametrů pro úlohy poznámkového bloku v uživatelském rozhraní úloh nebonotebook_params
v poli v operaci Trigger a new job run (POST /jobs/run-now
) v rozhraní API úloh.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.widgets.help("get")
příkaz .
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 nastaven na 35
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)
Získá mapování všech aktuálních názvů a hodnot widgetu. To může být užitečné zejména při rychlém předávání hodnot widgetu spark.sql()
do dotazu.
Tento příkaz je k dispozici ve verzi Databricks Runtime 13.3 LTS a vyšší. Je k dispozici pouze pro Python a Scala.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.widgets.help("getAll")
příkaz .
Tento příklad získá mapu hodnot widgetu 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)
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ý. Místo toho použijte dbutils.widgets.get .
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.widgets.help("getArgument")
příkaz .
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)
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.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.widgets.help("multiselect")
příkaz .
Tento příklad vytvoří a zobrazí widget s vícenásobným výběrem s názvem days_multiselect
programu . Nabízí možnosti Monday
prostřednictvím Sunday
a je nastavena 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
remove command (dbutils.widgets.remove)
Odebere widget se zadaným názvem programu.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.widgets.help("remove")
příkaz .
Důležité
Pokud přidáte příkaz pro odebrání 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.
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)
Odebere všechny widgety z poznámkového bloku.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.widgets.help("removeAll")
příkaz .
Důležité
Pokud přidáte příkaz, který odebere všechny widgety, 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.
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)
Vytvoří a zobrazí textový widget se zadaným názvem programu, výchozí hodnotou a volitelným popiskem.
Chcete-li zobrazit nápovědu pro tento příkaz, spusťte dbutils.widgets.help("text")
příkaz .
Tento příklad vytvoří a zobrazí textový widget s programovým názvem your_name_text
. Je nastavena na počáteční hodnotu 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á. I když je tato knihovna stále dostupná, Databricks neplánuje pro knihovnu dbutils-api
žádnou novou funkci.
Databricks doporučuje místo toho použít jednu z následujících knihoven:
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
). Seznam dostupných cílů a verzí najdete na webové stránce rozhraní DBUtils API 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ř exekutorů může vést k neočekávaným výsledkům nebo může vést k chybám.
Pokud potřebujete spouštět operace systému souborů na exekutorech pomocí dbutils
paralelního výpisu a odstraňování metod pomocí Sparku v postupu, jak v Databricks vypsat a odstranit soubory rychleji.
Informace o exekutorech najdete v tématu Přehled režimu clusteru na webu Apache Spark.