Sdílet prostřednictvím

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

  • Článek

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

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)

Všimněte si, že 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: při dbutils.fs.help() zobrazení možnosti extraConfigs pro dbutils.fs.mount(), v Pythonu byste 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 také použít %fs příkaz magic pro přístup k DBFS. Například %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.

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ů daného 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ě celý jeho obsah. Pokud je zadaný soubor, parametr recurse je ignorován. Pokud je zadaný adresář, dojde k chybě, pokud je zakázána oprava 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 adresář /Volumes/main/default/my-volume/my-data/ včetně obsahu adresáře.

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)

Příkazy: get, set

Poznámka:

Tato subutilita je k dispozici pouze pro Python.

Poskytuje příkazy pro využití hodnot úkolů úloh.

Pomocí tohoto dílčího nástroje můžete nastavit a získat libovolné hodnoty během spuštění úlohy. Tyto hodnoty se nazývají hodnoty úkolů. Ke hodnotám úkolů v podřízených úkolech můžete přistupovat ve stejném spuštění úlohy. Můžete například komunikovat identifikátory nebo metriky, jako jsou například informace o vyhodnocení modelu strojového učení, mezi různými úlohami v rámci spuštění úlohy. Každý úkol může nastavit více hodnot úkolů, získat je nebo obojí. 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.

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ý nastavil hodnotu úkolu. Pokud příkaz nemůže tento úkol najít, ValueError je vyvolán.
  • keyje 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 (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 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í vyvolali TypeError nějakou hodnotu. debugValue nemůže být None.

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íčem K, 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)

Příkazy: exit, run

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 používání 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, coconuta 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, capea 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 .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 najdete v pokrytí parametrů pro úlohy poznámkového bloku v uživatelském rozhraní pro vytvoření úlohy nebo notebook_params pole v operaci Aktivovat spuštění nové úlohy (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_multiselectprogramu . 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 místně zkompilovat aplikaci, která ji používá dbutils, ale 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, je k dispozici několik rychlejších a škálovatelných alternativ:

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