Referenční příručka nástrojů Databricks`dbutils`

Článek
03/05/2025

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

Poznámka:

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

Užitkové moduly

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

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

Nápověda k příkazu

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

dbutils.notebook.help()

The notebook module.

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

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

dbutils.fs.help("cp")

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

Datový nástroj (dbutils.data)

Důležité

Tato funkce je ve verzi Public Preview.

Poznámka:

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

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

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

Příkaz	Popis
shrnutí	Shrnutí datového rámce Sparku a vizualizace statistik za účelem získání rychlých přehledů

příkaz pro shrnutí (dbutils.data.summarize)

Poznámka:

Tato funkce je ve verzi Public Preview.

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

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

Důležité

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

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

dbutils.data.help("summarize")

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

Pokud je precise nastavena na false (výchozí), některé vrácené statistiky zahrnují aproximace, které zkracují dobu běhu.
- Počet jedinečných hodnot v kategorických sloupcích může mít přibližně 5% relativní chybu u sloupců s vysokou kardinalitou.
- 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 je precise nastavena na hodnotu 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ů.

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

Příklad

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

Python

df = spark.read.format('csv').load(
  '/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
  header=True,
  inferSchema=True
)
dbutils.data.summarize(df)

R

df <- read.df("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv", source = "csv", header="true", inferSchema = "true")
dbutils.data.summarize(df)

Scala

val df = spark.read.format("csv")
  .option("inferSchema", "true")
  .option("header", "true")
  .load("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv")
dbutils.data.summarize(df)

Vizualizace používá notaci SI k stručné vykreslení číselných 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 používá "B" pro 1.0e9 (giga) místo "G".

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

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

Upozornění

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

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

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

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

Spropitné

V poznámkových blocích můžete použít magický příkaz %fs 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.

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

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

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

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

dbutils.fs.help("cp")

Příklad

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

Python

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

# Out[4]: True

R

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

# [1] TRUE

Scala

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

// res3: Boolean = true

head command (dbutils.fs.head)

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

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

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

dbutils.fs.help("head")

Příklad

Tento příklad zobrazí prvních 25 bajtů souboru data.csv umístěného v /Volumes/main/default/my-volume/.

Python

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

# [Truncated to first 25 bytes]
# Out[12]: 'Year,First Name,County,Se'

R

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

# [1] "Year,First Name,County,Se"

Scala

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

// [Truncated to first 25 bytes]
// res4: String =
// "Year,First Name,County,Se"

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

ls(dir: String): Seq

Vypíše obsah adresáře.

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

dbutils.fs.help("ls")

Příklad

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

Python

dbutils.fs.ls("/Volumes/main/default/my-volume/")

# Out[13]: [FileInfo(path='dbfs:/Volumes/main/default/my-volume/data.csv', name='data.csv', size=2258987, modificationTime=1711357839000)]

R

dbutils.fs.ls("/Volumes/main/default/my-volume/")

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

# [[1]]
# [[1]]$path
# [1] "/Volumes/main/default/my-volume/data.csv"

# [[1]]$name
# [1] "data.csv"

# [[1]]$size
# [1] 2258987

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

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

# [[1]]$modificationTime
# [1] "1711357839000"

Scala

dbutils.fs.ls("/tmp")

// res6: Seq[com.databricks.backend.daemon.dbutils.FileInfo] = WrappedArray(FileInfo(/Volumes/main/default/my-volume/data.csv, 2258987, 1711357839000))

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

mkdirs(dir: String): boolean

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

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

dbutils.fs.help("mkdirs")

Příklad

Tento příklad vytvoří adresář my-data v rámci /Volumes/main/default/my-volume/.

Python

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

# Out[15]: True

R

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

# [1] TRUE

Scala

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

// res7: Boolean = true

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

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

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

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

dbutils.fs.help("mount")

Příklad

Python

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

Scala

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

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

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

mounts: Seq

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

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

dbutils.fs.help("mounts")

Příklad

Varování

Zavolejte dbutils.fs.refreshMounts() na všech ostatních spuštěných clusterech, abyste propagovali nové připojení. Viz příkaz refreshMounts (dbutils.fs.refreshMounts).

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

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

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

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

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

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

dbutils.fs.help("mv")

Příklad

Tento příklad přesune soubor rows.csv z /Volumes/main/default/my-volume/ do /Volumes/main/default/my-volume/my-data/.

Python

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

# Out[2]: True

R

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

# [1] TRUE

Scala

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

// res1: Boolean = true

put command (dbutils.fs.put)

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

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

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

dbutils.fs.help("put")

Příklad

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

Python

dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", True)

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

R

dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", TRUE)

# [1] TRUE

Scala

dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", true)

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

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

refreshMounts: boolean

Vynutí, aby všechny počítače v clusteru obnovily cache paměti, aby tak obdržely nejnovější informace.

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

dbutils.fs.help("refreshMounts")

Příklad

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

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

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

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

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

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

dbutils.fs.help("rm")

Příklad

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

Python

dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", True)

# Out[8]: True

R

dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", TRUE)

# [1] TRUE

Scala

dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", true)

// res6: Boolean = true

příkaz pro odpojení (dbutils.fs.unmount)

unmount(mountPoint: String): boolean

Odstraní přípojný bod DBFS.

Varování

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() na všech ostatních spuštěných clusterech, aby se aktualizace připojení rozšířily. Viz příkaz refreshMounts (dbutils.fs.refreshMounts).

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

dbutils.fs.help("unmount")

Příklad

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

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

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

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

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

Varování

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() na všech ostatních spuštěných clusterech, aby se přenesly všechny aktualizace připojení. Viz příkaz refreshMounts (dbutils.fs.refreshMounts).

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

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

dbutils.fs.help("updateMount")

Příklad

Python

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

Scala

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

Nástroje úloh (dbutils.jobs)

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

Poznámka:

Tento nástroj je k dispozici pouze pro Python.

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

Podřízený modul	Popis
taskValues	Poskytuje nástroje k využití hodnot pracovních úkolů.

subutility taskValues (dbutils.jobs.taskValues)

Poznámka:

Tato subutilita je k dispozici pouze pro Python.

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

Tento dílčí nástroj slouží k nastavení a získání libovolných hodnot během spuštění úlohy. Tyto hodnoty se nazývají hodnoty úkolů. Každý úkol může získat hodnoty nastavené nadřazenými úkoly a nastavit hodnoty pro podřízené úkoly, které se mají použít.

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

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

Příkaz	Popis
získej	Získá obsah zadané hodnoty úkolu pro zadaný úkol v aktuálním spuštění úlohy.
nastavit	Nastaví nebo aktualizuje hodnotu úkolu. Pro spuštění úlohy můžete nastavit až 250 hodnot úkolu.

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

Poznámka:

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

V prostředí Databricks Runtime verze 10.4 a starší, pokud get nelze najít úlohu, je vyvolán Py4JJavaError místo ValueError.

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

Získá obsah zadané hodnoty úkolu pro zadaný úkol v aktuální běhu úlohy.

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

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

Příklad

Příklad:

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

V předchozím příkladu:

taskKey je název úkolu, který nastaví hodnotu úkolu. Pokud příkaz nemůže tento úkol najít, ValueError je vyvolán.
key je název klíče hodnoty úkolu, který jste 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 určitou hodnotu místo toho, aby se ve výchozím nastavení vyvolala výjimka TypeError. 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. Pokud debugValue je však argument zadán v příkazu, je vrácena hodnota debugValue namísto vyvolání TypeError.

Příkaz "set" (dbutils.jobs.taskValues.set)

Poznámka:

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

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

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

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

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

Příklad

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

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

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

V předchozích příkladech:

key je klíč hodnoty úkolu. Tento klíč musí být pro úkol jedinečný. To znamená, že pokud dva různé úkoly 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á. Podívejte se na 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 pro poznámkové bloky (dbutils.notebook)

Nástroj poznámkového bloku umožňuje propojovat poznámkové bloky a pracovat s výsledky, které z nich plynou. Viz Orchestrace poznámkových bloků a modularizace kódu v poznámkových blocích.

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

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

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

exit(value: String): void

Ukončí poznámkový sešit s určitou hodnotou.

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

dbutils.notebook.help("exit")

Příklad

Tento příklad ukončí poznámkový blok s hodnotou Exiting from My Other Notebook.

Python

dbutils.notebook.exit("Exiting from My Other Notebook")

# Notebook exited: Exiting from My Other Notebook

R

dbutils.notebook.exit("Exiting from My Other Notebook")

# Notebook exited: Exiting from My Other Notebook

Scala

dbutils.notebook.exit("Exiting from My Other Notebook")

// Notebook exited: Exiting from My Other Notebook

Poznámka:

Pokud má spuštění dotaz se strukturovaným streamováním spuštěným na pozadí, volání dbutils.notebook.exit() neukončí spuštění. Běh bude pokračovat, dokud se dotaz vykonává 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(). Když se dotaz zastaví, můžete ukončit spuštění pomocí dbutils.notebook.exit()příkazu .

příkaz spuštění (dbutils.notebook.run)

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

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

Poznámka:

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

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

dbutils.notebook.help("run")

Příklad

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

Python

dbutils.notebook.run("My Other Notebook", 60)

# Out[14]: 'Exiting from My Other Notebook'

Scala

dbutils.notebook.run("My Other Notebook", 60)

// res2: String = Exiting from My Other Notebook

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

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

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

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

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

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

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

Upozornění

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 části Tajná redakce.

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

dbutils.secrets.help("get")

Příklad

Tento příklad získá řetězcovou reprezentaci hodnoty tajného klíče pro obor pojmenovaný my-scope a klíč s názvem my-key.

Python

dbutils.secrets.get(scope="my-scope", key="my-key")

# Out[14]: '[REDACTED]'

R

dbutils.secrets.get(scope="my-scope", key="my-key")

# [1] "[REDACTED]"

Scala

dbutils.secrets.get(scope="my-scope", key="my-key")

// res0: String = [REDACTED]

getBytes – příkaz (dbutils.secrets.getBytes)

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

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

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

dbutils.secrets.help("getBytes")

Příklad

Tento příklad získá bajtovou reprezentaci tajné hodnoty (v tomto příkladu a1!b2@c3#) pro pojmenovaný obor my-scope a klíč s názvem my-key.

Python

dbutils.secrets.getBytes(scope="my-scope", key="my-key")

# Out[1]: b'a1!b2@c3#'

R

dbutils.secrets.getBytes(scope="my-scope", key="my-key")

# [1] 61 31 21 62 32 40 63 33 23

Scala

dbutils.secrets.getBytes(scope="my-scope", key="my-key")

// res1: Array[Byte] = Array(97, 49, 33, 98, 50, 64, 99, 51, 35)

Příkaz "list" (dbutils.secrets.list)

list(scope: String): Seq

Zobrazí metadata pro tajemství v zadaném oboru.

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

dbutils.secrets.help("list")

Příklad

V tomto příkladu jsou uvedena metadata tajných kódů v oboru s názvem my-scope.

Python

dbutils.secrets.list("my-scope")

# Out[10]: [SecretMetadata(key='my-key')]

R

dbutils.secrets.list("my-scope")

# [[1]]
# [[1]]$key
# [1] "my-key"

Scala

dbutils.secrets.list("my-scope")

// res2: Seq[com.databricks.dbutils_v1.SecretMetadata] = ArrayBuffer(SecretMetadata(my-key))

listScopes – příkaz (dbutils.secrets.listScopes)

listScopes: Seq

Zobrazí seznam dostupných oborů.

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

dbutils.secrets.help("listScopes")

Příklad

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

Python

dbutils.secrets.listScopes()

# Out[14]: [SecretScope(name='my-scope')]

R

dbutils.secrets.listScopes()

# [[1]]
# [[1]]$name
# [1] "my-scope"

Scala

dbutils.secrets.listScopes()

// res3: Seq[com.databricks.dbutils_v1.SecretScope] = ArrayBuffer(SecretScope(my-scope))

Pomocný nástroj Widgets (dbutils.widgets)

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

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

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

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

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

Vytvoří a zobrazí widget kombinovaného pole se zadaným programovým jménem, výchozí hodnotou, možnostmi a volitelným popiskem.

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

dbutils.widgets.help("combobox")

Příklad

Tento příklad vytvoří a zobrazí widget kombinovaného pole s programovým názvem fruits_combobox. Nabízí možnosti apple, banana, coconuta dragon fruit a je nastavena na počáteční hodnotu banana. Tento widget kombobox má příslušný popisek Fruits. Tento příklad končí tiskem počáteční hodnoty widgetu se seznamem , banana.

Python

dbutils.widgets.combobox(
  name='fruits_combobox',
  defaultValue='banana',
  choices=['apple', 'banana', 'coconut', 'dragon fruit'],
  label='Fruits'
)

print(dbutils.widgets.get("fruits_combobox"))

# banana

R

dbutils.widgets.combobox(
  name='fruits_combobox',
  defaultValue='banana',
  choices=list('apple', 'banana', 'coconut', 'dragon fruit'),
  label='Fruits'
)

print(dbutils.widgets.get("fruits_combobox"))

# [1] "banana"

Scala

dbutils.widgets.combobox(
  "fruits_combobox",
  "banana",
  Array("apple", "banana", "coconut", "dragon fruit"),
  "Fruits"
)

print(dbutils.widgets.get("fruits_combobox"))

// banana

SQL

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

SELECT :fruits_combobox

-- banana

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

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

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

dbutils.widgets.help("dropdown")

Příklad

Tento příklad vytvoří a zobrazí rozevírací widget s programovým názvem toys_dropdown. Nabízí možnosti alphabet blocks, basketball, capea doll a je 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

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

get(name: String): String

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

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

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

dbutils.widgets.help("get")

Příklad

Tento příklad získá hodnotu widgetu, který má programový název fruits_combobox.

Python

dbutils.widgets.get('fruits_combobox')

# banana

R

dbutils.widgets.get('fruits_combobox')

# [1] "banana"

Scala

dbutils.widgets.get("fruits_combobox")

// res6: String = banana

SQL

SELECT :fruits_combobox

-- banana

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

Python

dbutils.widgets.get('age')

# 35

R

dbutils.widgets.get('age')

# [1] "35"

Scala

dbutils.widgets.get("age")

// res6: String = 35

SQL

SELECT :age

-- 35

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

getAll: map

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

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

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

dbutils.widgets.help("getAll")

Příklad

Tento příklad získá mapu 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)

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

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

Poznámka:

Tento příkaz je zastaralý. Místo toho použijte dbutils.widgets.get.

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

dbutils.widgets.help("getArgument")

Příklad

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

Python

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

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

R

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

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

Scala

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

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

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

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

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

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

dbutils.widgets.help("multiselect")

Příklad

Tento příklad vytvoří a zobrazí widget s vícenásobným výběrem s programovým názvem days_multiselect. Nabízí možnosti od Monday do 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

příkaz pro odebrání (dbutils.widgets.remove)

remove(name: String): void

Odebere widget se zadaným názvem programu.

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

dbutils.widgets.help("remove")

Důležité

Pokud přidáte příkaz 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.

Příklad

Tento příklad odebere widget s programovým názvem fruits_combobox.

Python

dbutils.widgets.remove('fruits_combobox')

R

dbutils.widgets.remove('fruits_combobox')

Scala

dbutils.widgets.remove("fruits_combobox")

SQL

REMOVE WIDGET fruits_combobox

removeAll – příkaz (dbutils.widgets.removeAll)

removeAll: void

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

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

dbutils.widgets.help("removeAll")

Důležité

Pokud 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.

Příklad

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

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

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

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

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

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

dbutils.widgets.help("text")

Příklad

Tento příklad vytvoří a zobrazí textový widget s programovým názvem your_name_text. Je 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á. Databricks doporučuje místo toho použít jednu z následujících možností:

K urychlení vývoje aplikací může být užitečné zkompilovat, sestavovat a testovat aplikace předtím, než je nasadíte jako produkční úlohy. Aby bylo možné kompilovat proti nástrojům 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í API DBUtils na webu úložiště Maven.

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

Důležité

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

Omezení

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

Pokud potřebujete spouštět operace systému souborů na exekutorech pomocí dbutils, přečtěte si Paralelizovat operace systému souborů.

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

Sdílet prostřednictvím

Referenční příručka nástrojů Databricksdbutils

Užitkové moduly

Nápověda k příkazu

Datový nástroj (dbutils.data)

příkaz pro shrnutí (dbutils.data.summarize)

Příklad

Python

R

Scala

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

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

Příklad

Python

R

Scala

head command (dbutils.fs.head)

Příklad

Python

R

Scala

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

Příklad

Python

R

Scala

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

Příklad

Python

R

Scala

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

Příklad

Python

Scala

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

Příklad

Python

Scala

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

Příklad

Python

R

Scala

put command (dbutils.fs.put)

Příklad

Python

R

Scala

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

Příklad

Python

Scala

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

Příklad

Python

R

Scala

příkaz pro odpojení (dbutils.fs.unmount)

Příklad

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

Příklad

Python

Scala

Nástroje úloh (dbutils.jobs)

subutility taskValues (dbutils.jobs.taskValues)

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

Příklad

Příkaz "set" (dbutils.jobs.taskValues.set)

Příklad

Nástroj knihovny (dbutils.library)

Nástroj pro poznámkové bloky (dbutils.notebook)

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

Příklad

Python

R

Scala

příkaz spuštění (dbutils.notebook.run)

Příklad

Python

Referenční příručka nástrojů Databricks`dbutils`