Referencja narzędzi Databricks (dbutils)

Ten artykuł zawiera odniesienia do narzędzi usługi Databricks (dbutils). Narzędzia udostępniają polecenia, które umożliwiają pracę ze środowiskiem usługi Databricks z notesów. Można na przykład zarządzać plikami i magazynem obiektów oraz pracować z danymi poufnymi. dbutils są dostępne w notatnikach Python, R i Scala.

moduły użytkowe

W poniższej tabeli wymieniono moduły Databricks Utilities, które można pobrać przy użyciu dbutils.help().

Moduł	Opis
dane	Narzędzia do zrozumienia zestawów danych i interakcji z nimi (EKSPERYMENTALNE)
fs	Narzędzia do uzyskiwania dostępu do systemu plików usługi Databricks (DBFS)
prace	Narzędzia do korzystania z funkcji zadań
biblioteki	Przestarzałe. Narzędzia do zarządzania bibliotekami o sesyjnym zakresie
notatnik	Narzędzia do zarządzania przepływem sterowania w notatnikach (EKSPERYMENTALNE)
tajemnice	Narzędzia do korzystania z wpisów tajnych w notesach
widżety	Narzędzia do sparametryzowania notesów.
api	Narzędzia do zarządzania kompilacjami aplikacji

Pomoc dotycząca poleceń

Aby wyświetlić listę poleceń dla modułu narzędziowego wraz z krótkim opisem każdego polecenia, dołącz .help() po nazwie modułu narzędziowego. W poniższym przykładzie wymieniono dostępne polecenia dla narzędzia notesu:

dbutils.notebook.help()

The notebook module.

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

Aby uzyskać pomoc dotyczącą polecenia, uruchom polecenie dbutils.<utility-name>.help("<command-name>"). Poniższy przykład przedstawia pomoc dotyczącą polecenia kopiowania narzędzi systemu plików, dbutils.fs.cp:

dbutils.fs.help("cp")

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

Narzędzie danych (dbutils.data)

Narzędzie do obsługi danych umożliwia zrozumienie zestawów danych i interakcję z nimi.

W poniższej tabeli wymieniono dostępne polecenia dla tego narzędzia, które można pobrać przy użyciu dbutils.data.help().

Polecenie	Opis
podsumuj	Podsumowanie ramki danych platformy Spark i wizualizowanie statystyk w celu uzyskania szybkich szczegółowych informacji

summarize — polecenie (dbutils.data.summarize)

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

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.

Aby wyświetlić pełną 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.

• Jeśli precise jest ustawiona na 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ć wartość ok. 5% względnego błędu dla kolumn o wysokiej kardynalności.
  • Licznik częstych wartości może mieć błąd wynoszący do 0,01%, gdy liczba unikalnych wartości przekracza 10000.
  • Histogramy i oszacowania percentylu mogą zawierać błąd do 0,01% względem całkowitej liczby wierszy.
• Gdy precise jest ustawiona na wartość true, statystyki są obliczane z wyższą dokładnością. 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.

Przykład

W tym przykładzie wyświetlane są statystyki podsumowujące dla DataFrame 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)

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)

Narzędzie systemu plików umożliwia dostęp do Co to jest DBFS?, co ułatwia korzystanie z usługi Azure Databricks jako systemu plików.

W poniższej tabeli wymieniono dostępne polecenia dla tego narzędzia, które można pobrać przy użyciu dbutils.fs.help().

Polecenie	Opis
cp	Kopiuje plik lub katalog, być może między różnymi systemami plików
głowa	Zwraca do pierwszych bajtów "maxBytes" danego pliku jako ciąg zakodowany w formacie UTF-8
ls	Wyświetla zawartość katalogu
mkdirs	Tworzy dany katalog, jeśli nie istnieje, tworząc również niezbędne katalogi nadrzędne
mocowanie	Montuje dany katalog źródłowy w systemie plików DBFS w danym punkcie montowania.
mocowania	Wyświetla informacje o tym, co jest instalowane w systemie plików DBFS
mv	Przenosi plik lub katalog, prawdopodobnie pomiędzy różnymi systemami plików
umieścić	Zapisuje podany ciąg w pliku zakodowanym w formacie UTF-8
refreshMounts	Wymusza odświeżenie pamięci podręcznej instalacji przez wszystkie maszyny w tym klastrze, zapewniając, że otrzymają najnowsze informacje
rm	Usuwa plik lub katalog
odmontować	Usuwa punkt instalacji systemu plików DBFS
updateMount	Podobnie jak w przypadku instalacji(), ale aktualizuje istniejący punkt instalacji zamiast tworzyć nowy

polecenie cp (dbutils.fs.cp)

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

Kopiuje plik lub katalog, możliwie na różnych systemach plików.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("cp")

Przykład

Ten przykład kopiuje plik o nazwie data.csv z /Volumes/main/default/my-volume/ do new-data.csv w tym samym woluminie.

Python

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

# Out[4]: True

R

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

# [1] TRUE

Scala

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

// res3: Boolean = true

head command (dbutils.fs.head)

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

Zwraca do określonej maksymalnej liczby bajtów w danym pliku. Bajty są zwracane jako ciąg zakodowany w formacie UTF-8.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("head")

Przykład

W tym przykładzie wyświetlane są pierwsze 25 bajtów pliku data.csv znajdującego się w /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"

polecenie ls (dbutils.fs.ls)

ls(dir: String): Seq

Wyświetla zawartość katalogu.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("ls")

Przykład

W tym przykładzie są wyświetlane informacje o zawartości elementu /Volumes/main/default/my-volume/. 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("/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))

polecenie mkdirs (dbutils.fs.mkdirs)

mkdirs(dir: String): boolean

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("mkdirs")

Przykład

W tym przykładzie zostanie utworzony katalog my-data w programie /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

polecenie montowania (dbutils.fs.mount)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("mount")

Przykład

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 Nawiązywanie połączenia z usługą Azure Data Lake Storage Gen2 i usługą Blob Storage.

polecenie mounts (dbutils.fs.mounts)

mounts: Seq

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("mounts")

Przykład

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Aby uzyskać dodatkowe przykłady kodu, zobacz Nawiązywanie połączenia z usługą Azure Data Lake Storage Gen2 i usługą Blob Storage.

polecenie mv (dbutils.fs.mv)

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

Przenosi plik lub katalog, być może między różnymi systemami plików. Przeniesienie to kopia, po której następuje usunięcie, nawet podczas przenoszenia wewnątrz systemów plików.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("mv")

Przykład

W tym przykładzie plik rows.csv jest przenoszony 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

polecenie put (dbutils.fs.put)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("put")

Przykład

W tym przykładzie ciąg Hello, Databricks! jest zapisywany do pliku o nazwie hello.txt w /Volumes/main/default/my-volume/. Jeśli plik istnieje, zostanie zastąpiony.

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

polecenie refreshMounts (dbutils.fs.refreshMounts)

refreshMounts: boolean

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("refreshMounts")

Przykład

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Aby zapoznać się z przykładami kodu dodatkowego, zobacz Connect to Azure Data Lake Storage Gen2 and Blob Storage (Łączenie z usługą Azure Data Lake Storage Gen2 i usługą Blob Storage).

polecenie rm (dbutils.fs.rm)

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

Usuwa plik lub katalog i, opcjonalnie, całą jego zawartość. Jeśli określono plik, recurse parametr jest ignorowany. Jeśli zostanie określony katalog, wystąpi błąd, gdy recurse jest wyłączony, a katalog nie jest pusty.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("rm")

Przykład

W tym przykładzie usunięto cały katalog /Volumes/main/default/my-volume/my-data/ wraz z jego zawartością.

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

polecenie unmount (dbutils.fs.unmount)

unmount(mountPoint: String): boolean

Usuwa punkt instalacji systemu plików DBFS.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("unmount")

Przykład

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

Aby uzyskać dodatkowe przykłady kodu, zobacz Nawiązywanie połączenia z usługą Azure Data Lake Storage Gen2 i usługą Blob Storage.

updateMount — polecenie (dbutils.fs.updateMount)

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

Podobnie jak polecenie dbutils.fs.mount, ale aktualizuje istniejący punkt montowania zamiast tworzyć nowy. Zwraca błąd, jeśli punkt instalacji nie istnieje.

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.fs.help("updateMount")

Przykład

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 do zarządzania zadaniami (dbutils.jobs)

Udostępnia ułatwienia do wykorzystywania cech zadań.

W poniższej tabeli wymieniono dostępne moduły dla tego narzędzia, które można pobrać przy użyciu dbutils.jobs.help().

Moduł podrzędny	Opis
taskValues	Udostępnia narzędzia do wykorzystywania wartości zadań roboczych

subnarzędzie taskValues (dbutils.jobs.taskValues)

Udostępnia polecenia do efektywnego wykorzystania wartości zadań.

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ń . Każde zadanie może pobierać wartości ustawione przez zadania nadrzędne i ustawiać wartości do użycia przez zadania podrzędne.

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. Służy to do przekazywania informacji podrzędnych z zadania do zadania w ramach tego samego uruchomienia zadania. Można na przykład przekazać identyfikatory lub metryki, takie jak informacje o ocenie modelu uczenia maszynowego, między różnymi zadaniami w ramach przebiegu zadania.

W poniższej tabeli wymieniono dostępne polecenia dla tego podprogramu, które można uzyskać przy użyciu dbutils.jobs.taskValues.help().

Polecenie	Opis
dostać	Pobiera wartość zadań określonych dla danego zadania w bieżącym przebiegu zadań.
ustawić	Ustawia lub aktualizuje wartość zadania. Dla uruchomienia zadania można skonfigurować maksymalnie 250 wartości zadań.

komenda 'get' (dbutils.jobs.taskValues.get)

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

Pobiera zawartość określonej wartości zadania dla określonego zadania podczas bieżącego wykonywania zadania.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

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

Przykład

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 ustawia wartość zadania. Jeśli polecenie nie może odnaleźć tego zadania, zostanie wywołany wyjątek ValueError.
• key jest nazwą 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ą, jeśli spróbujesz pobrać wartość zadania z notesu uruchomionego poza pracą. 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 notebooka działającego poza kontekstem zadania, to polecenie domyślnie zgłasza błąd TypeError. Jeśli jednak argument debugValue jest określony w poleceniu, wartość debugValue jest zwracana zamiast wyzwalania TypeError.

set polecenie (dbutils.jobs.taskValues.set)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

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

Przykład

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.
• Wartość klucza dla tej wartości zadania to value. 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 w notesie działającym poza zakresem zadania, to polecenie nic nie robi.

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 notatnika (dbutils.notebook)

Narzędzie notesu umożliwia łączenie notesów i wykonywanie działań na ich podstawie. Zobacz orkiestrację notesów oraz modularyzację kodu w notesach.

W poniższej tabeli wymieniono dostępne polecenia dla tego narzędzia, które można pobrać przy użyciu dbutils.notebook.help().

Polecenie	Opis
wyjście	Zamyka notatnik z wartością
uruchom	Uruchamia notebook i zwraca jego wartość wyjścia

polecenie exit (dbutils.notebook.exit)

exit(value: String): void

Kończy działanie notatnika z wartością.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.notebook.help("exit")

Przykład

W tym przykładzie notatnik kończy działanie 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

polecenie uruchomienia (dbutils.notebook.run)

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

Uruchamia notebook i zwraca jego wartość zakończenia. Notatnik uruchomi się domyślnie w bieżącym klastrze.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.notebook.help("run")

Przykład

W tym przykładzie uruchamiany jest notes o nazwie My Other Notebook w tej samej lokalizacji, co notes wywołujący. Wywołany notatnik kończy się wierszem kodu dbutils.notebook.exit("Exiting from My Other Notebook"). Jeśli wywoływany notebook 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 do zarządzania tajemnicami (dbutils.secrets)

Narzędzie do zarządzania tajnymi informacjami umożliwia przechowywanie poufnych danych uwierzytelniających i uzyskiwanie do nich dostępu bez ich ujawniania w notesach. Zobacz Zarządzanie wpisami tajnymi i Krok 3. Używanie wpisów tajnych w notesie.

W poniższej tabeli wymieniono dostępne polecenia dla tego narzędzia, które można pobrać przy użyciu dbutils.secrets.help().

Polecenie	Opis
dostać	Pobiera reprezentację ciągu znakowego wartości tajnej z zakresem i kluczem
getBytes	Pobiera bajtową reprezentację tajnej wartości z zakresem i kluczem
lista	Wyświetla metadane tajemnic w określonym zakresie
listScopes	Wyświetla listę tajnych zakresów

polecenie get (dbutils.secrets.get)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.secrets.help("get")

Przykład

W tym przykładzie uzyskuje się reprezentację ciągu wartości tajnej dla zakresu o nazwie my-scope i klucza o nazwie 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]

Polecenie getBytes (dbutils.secrets.getBytes)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.secrets.help("getBytes")

Przykład

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

list(scope: String): Seq

Wyświetla metadane dla sekretów w określonym zakresie.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.secrets.help("list")

Przykład

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)

listScopes: Seq

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.secrets.help("listScopes")

Przykład

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)

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

W poniższej tabeli wymieniono dostępne polecenia dla tego narzędzia, które można pobrać przy użyciu dbutils.widgets.help().

Polecenie	Opis
lista rozwijana	Tworzy widżet wejściowy pola rozwijanego z daną nazwą, wartością domyślną i opcjami.
rozwijana lista	Tworzy widżet wejściowy listy rozwijanej o danej nazwie, wartości domyślnej i opcjach
zdobyć	Pobiera bieżącą wartość widżetu wejściowego
getAll	Pobiera mapę wszystkich nazw widżetów i ich wartości
getArgument	Przestarzałe. Odpowiednik uzyskania
wielokrotny wybór	Tworzy widżet wejściowy wielokrotnego wyboru o podanej nazwie, wartości domyślnej i opcjach
usuń	Usuwa widżet wejściowy z notesu
usuńWszystkie	Usuwa wszystkie widżety w notesie
tekst	Tworzy widżet wprowadzania tekstu o podanej nazwie i wartości domyślnej

combobox — polecenie (dbutils.widgets.combobox)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.widgets.help("combobox")

Przykład

W tym przykładzie tworzony i wyświetlany jest widżet pola kombi o programowej nazwie fruits_combobox. Oferuje on opcje apple, banana, coconuti dragon fruit i jest ustawiona na początkową wartość banana. Ten widżet kombobox ma przypisaną 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

SQL

CREATE WIDGET COMBOBOX fruits_combobox DEFAULT "banana" CHOICES SELECT * FROM (VALUES ("apple"), ("banana"), ("coconut"), ("dragon fruit"))

SELECT :fruits_combobox

-- banana

dropdown — komenda (dbutils.widgets.dropdown)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.widgets.help("dropdown")

Przykład

W tym przykładzie zostanie utworzony i wyświetlony widżet listy rozwijanej o programowej nazwie toys_dropdown. 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ę wydrukiem 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

SQL

CREATE WIDGET DROPDOWN toys_dropdown DEFAULT "basketball" CHOICES SELECT * FROM (VALUES ("alphabet blocks"), ("basketball"), ("cape"), ("doll"))

SELECT :toys_dropdown

-- basketball

polecenie get (dbutils.widgets.get)

get(name: String): String

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 niestandardowego parametru przekazywanego do notesu jako część zadania notesu, na przykład name lub age. Aby uzyskać więcej informacji, zobacz parametry zadań w notesie w interfejsie użytkownika zadań albo pole notebook_params w operacji Wyzwolenie nowego uruchomienia zadania (POST /jobs/run-now) w interfejsie API zadań.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.widgets.help("get")

Przykład

W tym przykładzie jest pobierana wartość widżetu o nazwie programowej 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

W tym przykładzie jest pobierana wartość parametru zadania notatnika o nazwie programowej age. Ten parametr został ustawiony na 35, gdy uruchomiono powiązane zadanie notatnika.

Python

dbutils.widgets.get('age')

# 35

R

dbutils.widgets.get('age')

# [1] "35"

Scala

dbutils.widgets.get("age")

// res6: String = 35

SQL

SELECT :age

-- 35

getAll — polecenie (dbutils.widgets.getAll)

getAll: map

Uzyskuje mapowanie wszystkich aktualnych nazw i wartości widżetów. Może to być szczególnie przydatne, aby szybko przekazywać wartości widżetów do zapytania spark.sql().

To polecenie jest dostępne w środowisku Databricks Runtime 13.3 LTS lub nowszym. Jest on dostępny tylko dla języków Python i Scala.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.widgets.help("getAll")

Przykład

W tym przykładzie jest pobierana mapa wartości widżetu i przekazuje ją jako argumenty parametrów w zapytaniu 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

polecenie getArgument (dbutils.widgets.getArgument)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.widgets.help("getArgument")

Przykład

W tym przykładzie pobiera się wartość widżetu o programowej nazwie fruits_combobox. 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

komenda multiselect (dbutils.widgets.multiselect)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.widgets.help("multiselect")

Przykład

W tym przykładzie zostanie utworzony i wyświetlony widżet wielokrotnego wyboru o programowej nazwie days_multiselect. Oferuje on opcje Monday poprzez Sunday 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

SQL

CREATE WIDGET MULTISELECT days_multiselect DEFAULT "Tuesday" CHOICES SELECT * FROM (VALUES ("Monday"), ("Tuesday"), ("Wednesday"), ("Thursday"), ("Friday"), ("Saturday"), ("Sunday"))

SELECT :days_multiselect

-- Tuesday

usuń polecenie (dbutils.widgets.remove)

remove(name: String): void

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.widgets.help("remove")

Przykład

W tym przykładzie widżet zostanie usunięty o programowej nazwie 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 — polecenie (dbutils.widgets.removeAll)

removeAll: void

Usuwa wszystkie widżety z notesu.

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.widgets.help("removeAll")

Przykład

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)

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

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

Aby wyświetlić pełną pomoc dotyczącą tego polecenia, uruchom polecenie:

dbutils.widgets.help("text")

Przykład

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

SQL

CREATE WIDGET TEXT your_name_text DEFAULT "Enter your name"

SELECT :your_name_text

-- Enter your name

Biblioteka narzędzi Databricks API

Aby przyspieszyć tworzenie aplikacji, warto kompilować, budować i testować aplikacje przed ich wdrożeniem jako zadania produkcyjne. Aby umożliwić kompilowanie z użyciem 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, odwiedź stronę DBUtils API w witrynie Maven Repository.

Po skompilowaniu aplikacji z użyciem tej biblioteki, możesz wdrożyć aplikację.

Ograniczenia

Wywoływanie dbutils wewnątrz funkcji wykonawczych może spowodować nieoczekiwane wyniki lub błędy.

Jeśli musisz uruchomić operacje systemu plików na wykonawcach przy użyciu dbutils, zapoznaj się z tematem Zrównoleglij operacje systemu plików.

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