Dokumentacja narzędzi usługi Databricks (dbutils)

  • Artykuł

Ten artykuł zawiera informacje dotyczące narzędzi usługi Databricks (dbutils). dbutils Narzędzia są dostępne w notesach Python, R i Scala. Za pomocą narzędzi można wykonywać następujące czynności:

  • Wydajna praca z plikami i magazynem obiektów.
  • Praca z wpisami tajnymi.

Instrukcje: wyświetlanie narzędzi, wyświetlanie pomocy poleceń

Narzędzia: dane, fs, jobs, library, notebook, secrets, widgets, Utilities API library

Lista dostępnych narzędzi

Aby wyświetlić listę dostępnych narzędzi wraz z krótkim opisem dla każdego narzędzia, uruchom polecenie dbutils.help() dla języka Python lub języka Scala.

W tym przykładzie wymieniono dostępne polecenia dla narzędzi usługi 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

Wyświetlanie listy dostępnych poleceń dla narzędzia

Aby wyświetlić listę dostępnych poleceń dla narzędzia wraz z krótkim opisem każdego polecenia, uruchom polecenie .help() po nazwie programowej narzędzia.

W tym przykładzie wymieniono dostępne polecenia dla narzędzia Systemu plików usługi Databricks (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

Wyświetlanie pomocy dotyczącej polecenia

Aby wyświetlić pomoc dotyczącą polecenia, uruchom polecenie .help("<command-name>") po nazwie polecenia.

W tym przykładzie zostanie wyświetlona pomoc dotycząca polecenia kopiowania 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

Narzędzie danych (dbutils.data)

Ważne

Ta funkcja jest dostępna w publicznej wersji zapoznawczej.

Uwaga

Dostępne w środowisku Databricks Runtime 9.0 lub nowszym.

Polecenia: summarize

Narzędzie do obsługi danych umożliwia zrozumienie i interpretowanie zestawów danych. Aby wyświetlić listę dostępnych poleceń, uruchom polecenie dbutils.data.help().

dbutils.data provides utilities for understanding and interpreting datasets. This module is currently in preview and may be unstable. For more info about a method, use dbutils.data.help("methodName").

summarize(df: Object, precise: boolean): void -> Summarize a Spark DataFrame and visualize the statistics to get quick insights

summarize — polecenie (dbutils.data.summarize)

Oblicza i wyświetla podsumowanie statystyk ramki danych platformy Apache Spark lub ramki danych pandas. To polecenie jest dostępne dla języków Python, Scala i R.

To polecenie analizuje pełną zawartość ramki danych. Uruchomienie tego polecenia dla bardzo dużych ramek danych może być bardzo kosztowne.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.data.help("summarize").

W środowisku Databricks Runtime 10.4 LTS i nowszym można użyć dodatkowego precise parametru, aby dostosować dokładność obliczonych statystyk.

Uwaga

Ta funkcja jest dostępna w publicznej wersji zapoznawczej.

  • Gdy precise jest ustawiona wartość false (wartość domyślna), niektóre zwrócone statystyki obejmują przybliżenia w celu skrócenia czasu wykonywania.
    • Liczba unikatowych wartości kolumn kategorii może mieć błąd względny ok. 5% dla kolumn o wysokiej kardynalności.
    • Częste liczby wartości mogą mieć błąd do 0,01%, gdy liczba unikatowych wartości jest większa niż 10000.
    • Histogramy i oszacowania percentylu mogą zawierać błąd do 0,01% względem całkowitej liczby wierszy.
  • Gdy precise jest ustawiona wartość true, statystyki są obliczane z wyższą precyzją. Wszystkie statystyki z wyjątkiem histogramów i percentyli dla kolumn liczbowych są teraz dokładne.
    • Histogramy i oszacowania percentylu mogą zawierać błąd do 0,0001% względem całkowitej liczby wierszy.

Etykietka narzędzia w górnej części danych wyjściowych podsumowania danych wskazuje tryb bieżącego uruchomienia.

W tym przykładzie wyświetlane są statystyki podsumowania ramki danych platformy Apache Spark z domyślnie włączonymi przybliżeniami. Aby wyświetlić wyniki, uruchom to polecenie w notesie. Ten przykład jest oparty na przykładowych zestawach danych.

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)

Należy pamiętać, że wizualizacja używa notacji SI do zwięzłego renderowania wartości liczbowych mniejszych niż 0,01 lub większych niż 10000. Na przykład wartość 1.25e-15 liczbowa będzie renderowana jako 1.25f. Jeden wyjątek: wizualizacja używa znaku "B" dla 1.0e9 (giga) zamiast "G".

Narzędzie systemu plików (dbutils.fs)

Ostrzeżenie

Implementacja języka Python wszystkich dbutils.fs metod używa snake_case zamiast camelCase formatowania słów kluczowych.

Na przykład: podczas wyświetlania dbutils.fs.help() opcji dla dbutils.fs.mount()języka extraConfigs w języku Python należy użyć słowa kluczowego extra_configs.

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

Narzędzie systemu plików umożliwia dostęp do usługi What is the Databricks File System (DBFS)?, co ułatwia korzystanie z usługi Azure Databricks jako systemu plików. Aby wyświetlić listę dostępnych poleceń, uruchom polecenie dbutils.fs.help().

dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".

fsutils

cp(from: String, to: String, recurse: boolean = false): boolean -> Copies a file or directory, possibly across FileSystems
head(file: String, maxBytes: int = 65536): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
ls(dir: String): Seq -> Lists the contents of a directory
mkdirs(dir: String): boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
mv(from: String, to: String, recurse: boolean = false): boolean -> Moves a file or directory, possibly across FileSystems
put(file: String, contents: String, overwrite: boolean = false): boolean -> Writes the given String out to a file, encoded in UTF-8
rm(dir: String, recurse: boolean = false): boolean -> Removes a file or directory

mount

mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Mounts the given source directory into DBFS at the given mount point
mounts: Seq -> Displays information about what is mounted within DBFS
refreshMounts: boolean -> Forces all machines in this cluster to refresh their mount cache, ensuring they receive the most recent information
unmount(mountPoint: String): boolean -> Deletes a DBFS mount point
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one

cp — polecenie (dbutils.fs.cp)

Kopiuje plik lub katalog, prawdopodobnie w systemach plików.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("cp").

Ten przykład kopiuje plik o nazwie old_file.txt z /FileStore na /tmp/new, zmieniając nazwę skopiowanego pliku na new_file.txt.

Python

dbutils.fs.cp("/FileStore/old_file.txt", "/tmp/new/new_file.txt")

# Out[4]: True

R

dbutils.fs.cp("/FileStore/old_file.txt", "/tmp/new/new_file.txt")

# [1] TRUE

Scala

dbutils.fs.cp("/FileStore/old_file.txt", "/tmp/new/new_file.txt")

// res3: Boolean = true

head command (dbutils.fs.head)

Zwraca maksymalną liczbę bajtów określonego pliku. Bajty są zwracane jako ciąg zakodowany w formacie UTF-8.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("head").

W tym przykładzie jest wyświetlanych pierwszych 25 bajtów pliku my_file.txt znajdującego się w /tmppliku .

Python

dbutils.fs.head("/tmp/my_file.txt", 25)

# [Truncated to first 25 bytes]
# Out[12]: 'Apache Spark is awesome!\n'

R

dbutils.fs.head("/tmp/my_file.txt", 25)

# [1] "Apache Spark is awesome!\n"

Scala

dbutils.fs.head("/tmp/my_file.txt", 25)

// [Truncated to first 25 bytes]
// res4: String =
// "Apache Spark is awesome!
// "

polecenie ls (dbutils.fs.ls)

Wyświetla zawartość katalogu.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("ls").

W tym przykładzie są wyświetlane informacje o zawartości elementu /tmp. Pole modificationTime jest dostępne w środowisku Databricks Runtime 10.4 LTS lub nowszym. W języku R modificationTime jest zwracany jako ciąg.

Python

dbutils.fs.ls("/tmp")

# Out[13]: [FileInfo(path='dbfs:/tmp/my_file.txt', name='my_file.txt', size=40, modificationTime=1622054945000)]

R

dbutils.fs.ls("/tmp")

# For prettier results from dbutils.fs.ls(<dir>), please use `%fs ls <dir>`

# [[1]]
# [[1]]$path
# [1] "dbfs:/tmp/my_file.txt"

# [[1]]$name
# [1] "my_file.txt"

# [[1]]$size
# [1] 40

# [[1]]$isDir
# [1] FALSE

# [[1]]$isFile
# [1] TRUE

# [[1]]$modificationTime
# [1] "1622054945000"

Scala

dbutils.fs.ls("/tmp")

// res6: Seq[com.databricks.backend.daemon.dbutils.FileInfo] = WrappedArray(FileInfo(dbfs:/tmp/my_file.txt, my_file.txt, 40, 1622054945000))

mkdirs — polecenie (dbutils.fs.mkdirs)

Tworzy dany katalog, jeśli nie istnieje. Tworzy również wszelkie niezbędne katalogi nadrzędne.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("mkdirs").

W tym przykładzie zostanie utworzona struktura katalogów /parent/child/grandchild w programie /tmp.

Python

dbutils.fs.mkdirs("/tmp/parent/child/grandchild")

# Out[15]: True

R

dbutils.fs.mkdirs("/tmp/parent/child/grandchild")

# [1] TRUE

Scala

dbutils.fs.mkdirs("/tmp/parent/child/grandchild")

// res7: Boolean = true

mount command (dbutils.fs.mount)

Instaluje określony katalog źródłowy w systemie plików DBFS w określonym punkcie instalacji.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("mount").

Python

dbutils.fs.mount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
  mount_point = "/mnt/<mount-name>",
  extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})

Scala

dbutils.fs.mount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net/<directory-name>",
  mountPoint = "/mnt/<mount-name>",
  extraConfigs = Map("<conf-key>" -> dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")))

Aby uzyskać dodatkowe przykłady kodu, zobacz Połączenie do usług Azure Data Lake Storage Gen2 i Blob Storage.

polecenie mounts (dbutils.fs.mounts)

Wyświetla informacje o tym, co jest obecnie zainstalowane w systemie plików DBFS.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("mounts").

Ostrzeżenie

Wywołaj dbutils.fs.refreshMounts() wszystkie inne uruchomione klastry, aby propagować nową instalację. Zobacz polecenie refreshMounts (dbutils.fs.refreshMounts).

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Aby uzyskać dodatkowe przykłady kodu, zobacz Połączenie do usług Azure Data Lake Storage Gen2 i Blob Storage.

mv , polecenie (dbutils.fs.mv)

Przenosi plik lub katalog, prawdopodobnie w systemach plików. Przeniesienie to kopia, po której następuje usunięcie, nawet w przypadku przenoszenia w systemach plików.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("mv").

W tym przykładzie plik my_file.txt jest przenosiny z /FileStore do ./tmp/parent/child/granchild

Python

dbutils.fs.mv("/FileStore/my_file.txt", "/tmp/parent/child/grandchild")

# Out[2]: True

R

dbutils.fs.mv("/FileStore/my_file.txt", "/tmp/parent/child/grandchild")

# [1] TRUE

Scala

dbutils.fs.mv("/FileStore/my_file.txt", "/tmp/parent/child/grandchild")

// res1: Boolean = true

put — polecenie (dbutils.fs.put)

Zapisuje określony ciąg w pliku. Ciąg jest zakodowany w formacie UTF-8.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("put").

W tym przykładzie ciąg Hello, Databricks! jest zapisywany w pliku o nazwie hello_db.txt w /tmppliku . Jeśli plik istnieje, zostanie zastąpiony.

Python

dbutils.fs.put("/tmp/hello_db.txt", "Hello, Databricks!", True)

# Wrote 18 bytes.
# Out[6]: True

R

dbutils.fs.put("/tmp/hello_db.txt", "Hello, Databricks!", TRUE)

# [1] TRUE

Scala

dbutils.fs.put("/tmp/hello_db.txt", "Hello, Databricks!", true)

// Wrote 18 bytes.
// res2: Boolean = true

refreshMounts — polecenie (dbutils.fs.refreshMounts)

Wymusza odświeżenie pamięci podręcznej instalacji przez wszystkie maszyny w klastrze, zapewniając, że otrzymają najnowsze informacje.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("refreshMounts").

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Aby zapoznać się z przykładami kodu dodatkowego, zobacz Połączenie do usług Azure Data Lake Storage Gen2 i Blob Storage.

rm — polecenie (dbutils.fs.rm)

Usuwa plik lub katalog i opcjonalnie całą jego zawartość. Jeśli zostanie określony plik, parametr rekurse zostanie zignorowany. Jeśli zostanie określony katalog, wystąpi błąd, jeśli cykl jest wyłączony, a katalog nie jest pusty.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("rm").

W tym przykładzie usunięto katalog /tmp , w tym zawartość katalogu.

Python

dbutils.fs.rm("/tmp", True)

# Out[8]: True

R

dbutils.fs.rm("/tmp", TRUE)

# [1] TRUE

Scala

dbutils.fs.rm("/tmp", true)

// res6: Boolean = true

unmount — polecenie (dbutils.fs.unmount)

Usuwa punkt instalacji systemu plików DBFS.

Ostrzeżenie

Aby uniknąć błędów, nigdy nie modyfikuj punktu instalacji, podczas gdy inne zadania odczytują lub zapisują w nim. Po zmodyfikowaniu instalacji zawsze uruchamiaj na dbutils.fs.refreshMounts() wszystkich innych uruchomionych klastrach, aby propagować wszystkie aktualizacje instalacji. Zobacz polecenie refreshMounts (dbutils.fs.refreshMounts).

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("unmount").

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

Aby uzyskać dodatkowe przykłady kodu, zobacz Połączenie do usług Azure Data Lake Storage Gen2 i Blob Storage.

updateMount — polecenie (dbutils.fs.updateMount)

Podobnie jak w przypadku dbutils.fs.mount polecenia , ale aktualizuje istniejący punkt instalacji zamiast tworzyć nowe. Zwraca błąd, jeśli punkt instalacji nie istnieje.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.fs.help("updateMount").

Ostrzeżenie

Aby uniknąć błędów, nigdy nie modyfikuj punktu instalacji, podczas gdy inne zadania odczytują lub zapisują w nim. Po zmodyfikowaniu instalacji zawsze uruchamiaj na dbutils.fs.refreshMounts() wszystkich innych uruchomionych klastrach, aby propagować wszystkie aktualizacje instalacji. Zobacz polecenie refreshMounts (dbutils.fs.refreshMounts).

To polecenie jest dostępne w środowisku Databricks Runtime 10.4 LTS i nowszym.

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

Narzędzie zadań (dbutils.jobs)

Podrzędne narzędzia: taskValues

Uwaga

To narzędzie jest dostępne tylko dla języka Python.

Narzędzie zadań umożliwia korzystanie z funkcji zadań. Aby wyświetlić pomoc dotyczącą tego narzędzia, uruchom polecenie dbutils.jobs.help().

Provides utilities for leveraging jobs features.

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

podrzędność taskValues (dbutils.jobs.taskValues)

Polecenia: get, set

Uwaga

To podzadanie jest dostępne tylko dla języka Python.

Udostępnia polecenia służące do korzystania z wartości zadań zadania.

To narzędzie podrzędne służy do ustawiania i pobierania dowolnych wartości podczas uruchamiania zadania. Te wartości są nazywane wartościami zadań. Możesz uzyskać dostęp do wartości zadań podrzędnych w tym samym uruchomieniu zadania. Można na przykład komunikować identyfikatory lub metryki, takie jak informacje o ocenie modelu uczenia maszynowego, między różnymi zadaniami w ramach przebiegu zadania. Każde zadanie może ustawić wiele wartości zadań, pobrać je lub oba te wartości. Każda wartość zadania ma unikatowy klucz w ramach tego samego zadania. Ten unikatowy klucz jest nazywany kluczem wartości zadania. Dostęp do wartości zadania jest uzyskiwany przy użyciu nazwy zadania i klucza wartości zadania.

Aby wyświetlić pomoc dotyczącą tego podzadania, uruchom polecenie dbutils.jobs.taskValues.help().

get command (dbutils.jobs.taskValues.get)

Uwaga

To polecenie jest dostępne tylko dla języka Python.

W środowisku Databricks Runtime 10.4 lub starszym, jeśli get nie można odnaleźć zadania, zostanie zgłoszony błąd Py4JavaError zamiast ValueError.

Pobiera zawartość określonej wartości zadania dla określonego zadania w bieżącym uruchomieniu zadania.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.jobs.taskValues.help("get").

Na przykład:

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

W powyższym przykładzie:

  • taskKey to nazwa zadania, które ustawiło wartość zadania. Jeśli polecenie nie może odnaleźć tego zadania, zostanie zgłoszony element ValueError .
  • key to nazwa klucza wartości zadania ustawionego za pomocą polecenia set (dbutils.jobs.taskValues.set). Jeśli polecenie nie może odnaleźć klucza tej wartości zadania, element ValueError zostanie zgłoszony (chyba że default zostanie określony).
  • default jest opcjonalną wartością zwracaną, jeśli key nie można jej odnaleźć. default nie może być None.
  • debugValue jest opcjonalną wartością zwracaną w przypadku próby pobrania wartości zadania z poziomu notesu uruchomionego poza zadaniem. Może to być przydatne podczas debugowania, gdy chcesz ręcznie uruchomić notes i zwrócić pewną wartość zamiast domyślnie podnieść TypeError . debugValue nie może być None.

Jeśli spróbujesz uzyskać wartość zadania z poziomu notesu uruchomionego poza zadaniem, to polecenie domyślnie TypeError zgłasza wartość . Jeśli debugValue jednak argument jest określony w poleceniu, wartość debugValue jest zwracana zamiast podnosić TypeErrorwartość .

set — polecenie (dbutils.jobs.taskValues.set)

Uwaga

To polecenie jest dostępne tylko dla języka Python.

Ustawia lub aktualizuje wartość zadania. Dla uruchomienia zadania można skonfigurować maksymalnie 250 wartości zadań.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.jobs.taskValues.help("set").

Przykłady obejmują:

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

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

W poprzednich przykładach:

  • key jest kluczem wartości zadania. Ten klucz musi być unikatowy dla zadania. Oznacza to, że jeśli dwa różne zadania ustawiają wartość zadania z kluczem K, są to dwie różne wartości zadań, które mają ten sam klucz K.
  • value jest wartością klucza tej wartości zadania. To polecenie musi być w stanie reprezentować wartość wewnętrznie w formacie JSON. Rozmiar reprezentacji JSON wartości nie może przekraczać 48 KiB.

Jeśli spróbujesz ustawić wartość zadania z poziomu notesu uruchomionego poza zadaniem, to polecenie nie wykonuje żadnych czynności.

Narzędzie biblioteki (dbutils.library)

Większość metod w module podrzędnym dbutils.library jest przestarzała. Zobacz Narzędzie biblioteki (dbutils.library) (starsza wersja).

Może być konieczne programowe ponowne uruchomienie procesu języka Python w usłudze Azure Databricks, aby upewnić się, że lokalnie zainstalowane lub uaktualnione biblioteki działają poprawnie w jądrze języka Python dla bieżącej usługi SparkSession. W tym celu uruchom polecenie dbutils.library.restartPython. Zobacz Ponowne uruchamianie procesu języka Python w usłudze Azure Databricks.

Narzędzie notesu (dbutils.notebook)

Polecenia: zamykanie, uruchamianie

Narzędzie notesu umożliwia łączenie notesów i wykonywanie działań na ich podstawie. Zobacz Uruchamianie notesu usługi Databricks z innego notesu.

Aby wyświetlić listę dostępnych poleceń, uruchom polecenie dbutils.notebook.help().

exit(value: String): void -> This method lets you exit a notebook with a value
run(path: String, timeoutSeconds: int, arguments: Map): String -> This method runs a notebook and returns its exit value.

exit — polecenie (dbutils.notebook.exit)

Zamyka notes z wartością.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.notebook.help("exit").

W tym przykładzie notes kończy się z wartością 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

Uwaga

Jeśli uruchomienie ma zapytanie ze strukturą strumieniową uruchomioną w tle, wywołanie dbutils.notebook.exit() nie kończy przebiegu. Uruchomienie będzie kontynuowane tak długo, jak zapytanie jest wykonywane w tle. Zapytanie uruchomione w tle można zatrzymać, klikając przycisk Anuluj w komórce zapytania lub uruchamiając polecenie query.stop(). Po zatrzymaniu zapytania można zakończyć przebieg za pomocą polecenia dbutils.notebook.exit().

run — polecenie (dbutils.notebook.run)

Uruchamia notes i zwraca jego wartość zakończenia. Notes będzie domyślnie uruchamiany w bieżącym klastrze.

Uwaga

Maksymalna długość wartości ciągu zwróconej z run polecenia wynosi 5 MB. Zobacz Pobieranie danych wyjściowych dla pojedynczego przebiegu (GET /jobs/runs/get-output).

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.notebook.help("run").

W tym przykładzie jest uruchamiany notes o nazwie My Other Notebook w tej samej lokalizacji co notes wywołujący. Nazwany notes kończy się wierszem kodu dbutils.notebook.exit("Exiting from My Other Notebook"). Jeśli wywoływany notes nie zakończy działania w ciągu 60 sekund, zostanie zgłoszony wyjątek.

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

Narzędzie Secrets (dbutils.secrets)

Polecenia: get, getBytes, list, listScopes

Narzędzie wpisy tajne umożliwia przechowywanie poufnych informacji o poświadczeniach i uzyskiwanie do nich dostępu bez ich widoczności w notesach. Zobacz Zarządzanie wpisami tajnymi i Używanie wpisów tajnych w notesie. Aby wyświetlić listę dostępnych poleceń, uruchom polecenie dbutils.secrets.help().

get(scope: String, key: String): String -> Gets the string representation of a secret value with scope and key
getBytes(scope: String, key: String): byte[] -> Gets the bytes representation of a secret value with scope and key
list(scope: String): Seq -> Lists secret metadata for secrets within a scope
listScopes: Seq -> Lists secret scopes

get — polecenie (dbutils.secrets.get)

Pobiera ciąg reprezentujący wartość wpisu tajnego dla określonego zakresu i klucza wpisów tajnych.

Ostrzeżenie

Administracja istratory, twórcy wpisów tajnych i użytkownicy, którym udzielono uprawnień, mogą odczytywać wpisy tajne usługi Azure Databricks. Chociaż usługa Azure Databricks stara się redagować wartości wpisów tajnych, które mogą być wyświetlane w notesach, nie można uniemożliwić takim użytkownikom odczytywania wpisów tajnych. Aby uzyskać więcej informacji, zobacz Ponowne redagowanie wpisów tajnych.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.secrets.help("get").

W tym przykładzie jest pobierana reprezentacja ciągu wartości wpisu tajnego dla zakresu o nazwie i klucza o nazwie my-scopemy-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 — polecenie (dbutils.secrets.getBytes)

Pobiera reprezentację bajtów wartości wpisu tajnego dla określonego zakresu i klucza.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.secrets.help("getBytes").

W tym przykładzie jest pobierana reprezentacja bajtów wartości wpisu tajnego (w tym przykładzie a1!b2@c3#) dla zakresu o nazwie i klucza o nazwie my-scopemy-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 — polecenie (dbutils.secrets.list)

Wyświetla metadane dla wpisów tajnych w określonym zakresie.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.secrets.help("list").

W tym przykładzie wymieniono metadane dla wpisów tajnych w zakresie o nazwie 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 — polecenie (dbutils.secrets.listScopes)

Wyświetla listę dostępnych zakresów.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.secrets.help("listScopes").

W tym przykładzie wymieniono dostępne zakresy.

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

Narzędzie Widgets (dbutils.widgets)

Polecenia: combobox, dropdown, get, getArgument, multiselect, remove, removeAll, text

Narzędzie widgets umożliwia sparametryzowanie notesów. Zobacz Widżety usługi Databricks.

Aby wyświetlić listę dostępnych poleceń, uruchom polecenie dbutils.widgets.help().

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

combobox — polecenie (dbutils.widgets.combobox)

Tworzy i wyświetla widżet pola kombi z określoną nazwą programową, wartością domyślną, opcjami i opcjonalną etykietą.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.widgets.help("combobox").

W tym przykładzie zostanie utworzony i wyświetlony widżet pola kombi o nazwie fruits_comboboxprogramowej . Oferuje on opcje apple, banana, coconuti dragon fruit i jest ustawiona na początkową wartość banana. Ten widżet kombi ma dołączącą etykietę Fruits. Ten przykład kończy się drukowaniem początkowej wartości widżetu kombibox, 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

dropdown — polecenie (dbutils.widgets.dropdown)

Tworzy i wyświetla widżet listy rozwijanej z określoną nazwą programową, wartością domyślną, opcjami i opcjonalną etykietą.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.widgets.help("dropdown").

W tym przykładzie zostanie utworzony i wyświetlony widżet listy rozwijanej o nazwie toys_dropdownprogramowej . Oferuje on opcje alphabet blocks, basketball, capei doll i jest ustawiona na początkową wartość basketball. Ten widżet listy rozwijanej ma etykietę towarzyszącą Toys. Ten przykład kończy się drukowaniem początkowej wartości widżetu listy rozwijanej . 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

get — polecenie (dbutils.widgets.get)

Pobiera bieżącą wartość widżetu z określoną nazwą programową. Ta nazwa programowa może być następująca:

  • Nazwa niestandardowego widżetu w notesie, na przykład fruits_combobox lub toys_dropdown.
  • Nazwa parametru niestandardowego przekazanego do notesu w ramach zadania notesu, na przykład name lub age. Aby uzyskać więcej informacji, zobacz pokrycie parametrów dla zadań notesu w interfejsie użytkownika tworzenia zadania lub notebook_params pole w operacji Wyzwalanie nowego uruchomienia zadania (POST /jobs/run-now) w interfejsie API zadań.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.widgets.help("get").

W tym przykładzie jest pobierana wartość widżetu o nazwie fruits_comboboxprogramowej .

Python

dbutils.widgets.get('fruits_combobox')

# banana

R

dbutils.widgets.get('fruits_combobox')

# [1] "banana"

Scala

dbutils.widgets.get("fruits_combobox")

// res6: String = banana

W tym przykładzie jest pobierana wartość parametru zadania notesu o nazwie ageprogramowej . Ten parametr został ustawiony na 35 czas uruchomienia powiązanego zadania notesu.

Python

dbutils.widgets.get('age')

# 35

R

dbutils.widgets.get('age')

# [1] "35"

Scala

dbutils.widgets.get("age")

// res6: String = 35

getArgument — polecenie (dbutils.widgets.getArgument)

Pobiera bieżącą wartość widżetu z określoną nazwą programową. Jeśli widżet nie istnieje, można zwrócić opcjonalny komunikat.

Uwaga

To polecenie jest przestarzałe. Zamiast tego użyj polecenia dbutils.widgets.get .

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.widgets.help("getArgument").

W tym przykładzie jest pobierana wartość widżetu o nazwie fruits_comboboxprogramowej . Jeśli ten widżet nie istnieje, zostanie zwrócony komunikat Error: Cannot find fruits combobox .

Python

dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')

# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# Out[3]: 'banana'

R

dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')

# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# [1] "banana"

Scala

dbutils.widgets.getArgument("fruits_combobox", "Error: Cannot find fruits combobox")

// command-1234567890123456:1: warning: method getArgument in trait WidgetsUtils is deprecated: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
// dbutils.widgets.getArgument("fruits_combobox", "Error: Cannot find fruits combobox")
//                 ^
// res7: String = banana

polecenie multiselect (dbutils.widgets.multiselect)

Tworzy i wyświetla widżet wielokrotnego wyboru z określoną nazwą programową, wartością domyślną, wyborami i opcjonalną etykietą.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.widgets.help("multiselect").

W tym przykładzie zostanie utworzony i wyświetlony widżet wielokrotnego wyboru o nazwie days_multiselectprogramowej . Oferuje on opcje wyboru Monday za pomocą Sunday parametru i jest ustawiony na początkową wartość Tuesday. Ten widżet wielokrotnego wyboru ma etykietę towarzyszącą Days of the Week. Ten przykład kończy się drukowaniem początkowej wartości widżetu wielokrotnego wyboru. 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

remove — polecenie (dbutils.widgets.remove)

Usuwa widżet z określoną nazwą programową.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.widgets.help("remove").

Ważne

Jeśli dodasz polecenie w celu usunięcia widżetu, nie możesz dodać kolejnego polecenia w celu utworzenia widżetu w tej samej komórce. Widżet należy utworzyć w innej komórce.

W tym przykładzie widżet zostanie usunięty z nazwą fruits_comboboxprogramową .

Python

dbutils.widgets.remove('fruits_combobox')

R

dbutils.widgets.remove('fruits_combobox')

Scala

dbutils.widgets.remove("fruits_combobox")

removeAll — polecenie (dbutils.widgets.removeAll)

Usuwa wszystkie widżety z notesu.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.widgets.help("removeAll").

Ważne

Jeśli dodasz polecenie w celu usunięcia wszystkich widżetów, nie można dodać kolejnego polecenia w celu utworzenia żadnych widżetów w tej samej komórce. Musisz utworzyć widżety w innej komórce.

Ten przykład usuwa wszystkie widżety z notesu.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

text — polecenie (dbutils.widgets.text)

Tworzy i wyświetla widżet tekstowy z określoną nazwą programową, wartością domyślną i opcjonalną etykietą.

Aby wyświetlić pomoc dotyczącą tego polecenia, uruchom polecenie dbutils.widgets.help("text").

W tym przykładzie zostanie utworzony i wyświetlony widżet tekstowy o nazwie your_name_textprogramowej . Jest ona ustawiona na początkową wartość Enter your name. Ten widżet tekstu ma etykietę towarzyszącą Your name. Ten przykład kończy się drukowaniem początkowej wartości widżetu tekstowego . 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

Biblioteka interfejsu API narzędzi usługi Databricks

Ważne

Biblioteka interfejsu API () narzędzi usługi Databricks (dbutils-api) jest przestarzała. Mimo że ta biblioteka jest nadal dostępna, usługa Databricks nie planuje nowej funkcji dla dbutils-api biblioteki.

Usługa Databricks zaleca użycie jednej z następujących bibliotek:

Aby przyspieszyć tworzenie aplikacji, warto kompilować, kompilować i testować aplikacje przed ich wdrożeniem jako zadania produkcyjne. Aby umożliwić kompilowanie na platformie Databricks Utilities, usługa Databricks udostępnia bibliotekę dbutils-api . Bibliotekę dbutils-api można pobrać ze strony internetowej interfejsu API DBUtils w witrynie internetowej repozytorium Maven lub dołączyć bibliotekę, dodając zależność do pliku kompilacji:

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

Zastąp TARGET żądany element docelowy (na przykład 2.12) i VERSION odpowiednią wersją (na przykład 0.0.5). Aby uzyskać listę dostępnych obiektów docelowych i wersji, zobacz stronę internetową interfejsu API DBUtils w witrynie internetowej repozytorium Maven.

Po skompiluj aplikację dla tej biblioteki, możesz wdrożyć aplikację.

Ważne

Biblioteka dbutils-api pozwala lokalnie skompilować aplikację używającą dbutilspolecenia , ale nie uruchamiać jej. Aby uruchomić aplikację, należy ją wdrożyć w usłudze Azure Databricks.

Ograniczenia

Wywołanie dbutils wewnątrz funkcji wykonawczej może spowodować nieoczekiwane wyniki lub potencjalnie spowodować błędy.

Jeśli musisz uruchomić operacje systemu plików na funkcjach wykonawczych przy użyciu programu dbutils, dostępnych jest kilka szybszych i bardziej skalowalnych alternatyw:

Aby uzyskać informacje o funkcjach wykonawczych, zobacz Omówienie trybu klastra w witrynie internetowej platformy Apache Spark.