Nástroje Databricks

Nástroje datacihly (DBUtils) usnadňují provádění výkonných kombinací úloh. Pomocí těchto nástrojů můžete efektivně pracovat s úložištěm objektů, zřetězit a parametrizovat poznámkové bloky a pracovat s tajnými kódy. DBUtils se nepodporují mimo poznámkové bloky.

Všechny dbutils nástroje jsou k dispozici v poznámkových blocích Python, R a Scala.

Nástroje systému souborů

Nástroje systému souborů nástroj zastupují do systému souborů DBFS (datacihly), což usnadňuje používání Azure Databricks jako systému souborů. Další informace získáte, když spustíte:

dbutils.fs.help()
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(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

dbutils.fs.ls – příkaz

Sekvence vrácená ls příkazem obsahuje následující atributy:

Atribut Typ Popis
program řetězec Cesta k souboru nebo adresáři.
name řetězec Název souboru nebo adresáře.
isDir() boolean True, pokud je cesta adresářem.
size Long/Int64 Délka souboru v bajtech nebo nula, pokud je cesta adresářem.

Poznámka

Podrobné informace o jednotlivých příkazech můžete získat například pomocí help : dbutils.fs.help("ls")

Například:

Python

dbutils.fs.ls("/databricks-datasets/adult")
dbutils.fs.head("/databricks-datasets/adult/adult.data")

R

dbutils.fs.ls("/databricks-datasets/")
dbutils.fs.head("/databricks-datasets/Rdatasets/data-001/datasets.csv")

Scala

dbutils.fs.ls("/databricks-datasets/adult")
dbutils.fs.head("/databricks-datasets/adult/adult.data")

Nástroje pracovního postupu poznámkového bloku

Pracovní postupy poznámkového bloku umožňují zřetězit poznámkové bloky a reagovat na jejich výsledky. Viz pracovní postupy poznámkového bloku. Další informace získáte, když spustíte:

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.

Poznámka

Maximální délka řetězcové hodnoty vrácené z hodnoty run je 5 MB. Viz spuštění získat výstup.

Poznámka

Podrobné informace o jednotlivých příkazech můžete získat například pomocí help : dbutils.notebook.help("exit")

Pomůcky widgetů

Widgety umožňují parametrizovat poznámkové bloky. Viz widgety. Další informace získáte, když spustíte:

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

Poznámka

Podrobné informace o jednotlivých příkazech můžete získat například pomocí help : dbutils.widgets.help("combobox")

Nástroje tajných klíčů

Tajné kódy umožňují ukládat důvěrné informace o přihlašovacích údajích a přistupovat k nim, aniž by byly viditelné v poznámkových blocích. Viz Správa tajných klíčů a používání tajných kódů v poznámkovém bloku. Další informace získáte, když spustíte:

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

Poznámka

Podrobné informace o jednotlivých příkazech můžete získat například pomocí help : dbutils.secrets.help("get")

Nástroje knihovny

Nástroje knihovny umožňují nainstalovat knihovny Pythonu a vytvořit prostředí vymezené pro relaci poznámkového bloku. Knihovny jsou k dispozici na ovladači i v prováděcích modulech, takže je můžete na ně odkazovat v UDF. To umožňuje:

  • Závislosti v knihovně poznámkového bloku se uspořádají do samotného poznámkového bloku.
  • Uživatelé poznámkového bloku s různými závislostmi knihoven ke sdílení clusteru bez rušivého vlivu.

Odpojení poznámkového bloku zničí toto prostředí. Můžete ji však znovu vytvořit tak, že znovu spustíte install příkazy rozhraní API knihovny v poznámkovém bloku. Podívejte se na restartPython rozhraní API, jak můžete obnovit stav poznámkového bloku bez ztráty prostředí.

Důležité

Nástroje knihovny nejsou k dispozici na Databricks Runtime ML ani Databricks Runtime pro genomiku. Místo toho se podívejte na knihovny Pythonu s oborem poznámkového bloku.

Pro Databricks Runtime 7,2 a novějších doporučuje datacihly %pip k instalaci knihoven s rozsahem poznámkových bloků použít příkazy Magic. Další informace najdete v tématu Knihovny Pythonu v rámci poznámkových bloků

Nástroje knihovny jsou ve výchozím nastavení povolené. Proto se ve výchozím nastavení prostředí Python pro každý Poznámkový blok izoluje pomocí samostatného spustitelného souboru Pythonu, který se vytvoří při připojení k poznámkovému bloku a zdědí výchozí prostředí Pythonu v clusteru. Knihovny nainstalované prostřednictvím skriptu init do prostředí Azure Databricks Python jsou stále k dispozici. Tuto funkci můžete zakázat nastavením spark.databricks.libraryIsolation.enabled na false .

Toto rozhraní API je kompatibilní s existující instalací knihovny v rámci clusteru prostřednictvím uživatelského rozhraní a REST API. Knihovny nainstalované prostřednictvím tohoto rozhraní API mají vyšší prioritu než knihovny pro celý cluster.

dbutils.library.help()
install(path: String): boolean -> Install the library within the current notebook session
installPyPI(pypiPackage: String, version: String = "", repo: String = "", extras: String = ""): boolean -> Install the PyPI library within the current notebook session
list: List -> List the isolated libraries added for the current notebook session via dbutils
restartPython: void -> Restart python process for the current notebook session

Poznámka

Podrobné informace o jednotlivých příkazech můžete získat například pomocí help : dbutils.library.help("install")

Příklady

  • Nainstalujte knihovnu PyPI do poznámkového bloku. version, repo a extras jsou volitelné. Pomocí extras argumentu zadejte funkci Extras (další požadavky).

    dbutils.library.installPyPI("pypipackage", version="version", repo="repo", extras="extras")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    

    Důležité

    versionKlíče a extras nemůžou být součástí řetězce balíčku PyPI. Příklad: není dbutils.library.installPyPI("azureml-sdk[databricks]==1.19.0") platný. Pomocí version argumentů a extras Určete verzi a informace o dalších verzích následujícím způsobem:

    dbutils.library.installPyPI("azureml-sdk", version="1.19.0", extras="databricks")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    

    Poznámka

    Při nahrazování dbutils.library.installPyPI příkazů pomocí %pip příkazů se překladač Pythonu automaticky restartuje. Instalační příkaz můžete spustit následujícím způsobem:

    %pip install azureml-sdk[databricks]==1.19.0
    
  • Určete požadavky knihovny v jednom poznámkovém bloku a nainstalujte je přes %run jiné.

    • Definujte knihovny, které se mají nainstalovat, do pojmenovaného poznámkového bloku InstallDependencies .

      dbutils.library.installPyPI("torch")
      dbutils.library.installPyPI("scikit-learn", version="1.19.1")
      dbutils.library.installPyPI("azureml-sdk", extras="databricks")
      dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
      
    • Nainstalujte je do poznámkového bloku, který tyto závislosti potřebuje.

      %run /path/to/InstallDependencies    # Install the dependencies in first cell
      
      import torch
      from sklearn.linear_model import LinearRegression
      import azureml
      # do the actual work
      
  • Zobrazí seznam knihoven nainstalovaných v poznámkovém bloku.

    dbutils.library.list()
    

    Poznámka

    Ekvivalent tohoto příkazu %pip :

    %pip freeze
    
  • Resetovat stav poznámkového bloku Pythonu při zachování prostředí Toto rozhraní API je dostupné jenom v poznámkových blocích Pythonu. Dá se použít k těmto akcím:

    • Znovu načíst knihovny Azure Databricks předinstalované s jinou verzí. Například:

      dbutils.library.installPyPI("numpy", version="1.15.4")
      dbutils.library.restartPython()
      
      # Make sure you start using the library in another cell.
      import numpy
      
    • Nainstalujte knihovny, jako je tensorflow, které se musí načíst při spuštění procesu. Například:

      dbutils.library.installPyPI("tensorflow")
      dbutils.library.restartPython()
      
      # Use the library in another cell.
      import tensorflow
      
  • Nainstalujte .egg knihovnu nebo .whl v poznámkovém bloku.

    Důležité

    Datacihly doporučuje, abyste do první buňky poznámkového bloku umístili všechny příkazy pro instalaci knihovny a restartPython na konci této buňky volali. Po spuštění se obnoví stav poznámkového bloku Python restartPython . Poznámkový blok ztratí všechny stavy, včetně jiných proměnných, importovaných knihoven a dalších dočasných stavů. Proto doporučujeme, abyste nainstalovali knihovny a obnovili stav poznámkového bloku v první buňce poznámkového bloku.

    Přijaté zdroje knihovny jsou dbfs ,, abfss adl a wasbs .

    dbutils.library.install("abfss:/path/to/your/library.egg")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    
    dbutils.library.install("abfss:/path/to/your/library.whl")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    

    Poznámka

    Vlastní soubory kolečka můžete přímo instalovat pomocí %pip . V následujícím příkladu předpokládáme, že jste nahráli soubor kolečka knihovny do DBFS:

    %pip install /dbfs/path/to/your/library.whl
    

    PIP nepodporuje soubory vajec a kolo je považováno za standard pro sestavení a binární balení pro Python. Další podrobnosti najdete v části kolečko a vejce . Pokud však chcete použít soubor vaječný způsobem, který je kompatibilní s nástrojem %pip , můžete použít následující řešení:

    # This step is only needed if no %pip commands have been executed yet.
    # It will trigger setting up the isolated notebook environment
    %pip install <any-lib>  # This doesn't need to be a real lib, eg - "%pip install foo" would work
    
    import sys
    # Assuming the preceding step was completed, the following command
    # adds the egg file to the current notebook environment
    sys.path.append("/local/path/to/library.egg")
    

Poznámkový blok DBUtils

Získat poznámkový blok

Knihovna rozhraní API nástrojů datacihly

Poznámka

Tuto knihovnu nemůžete použít ke spuštění testů před nasazením, pokud nasazujete do clusteru se systémem Databricks Runtime 7,0 nebo vyšším, protože není k dispozici žádná verze knihovny, která podporuje Scala 2,12.

Pro urychlení vývoje aplikací může být užitečné kompilovat, sestavovat a testovat aplikace před jejich nasazením jako produkčních úloh. Aby bylo možné kompilovat s nástroji datacihly, poskytují datacihly dbutils-api knihovnu. Můžete stáhnout knihovnu dbutils-API nebo zahrnout knihovnu přidáním závislosti do souboru sestavení:

  • SBT

    libraryDependencies += "com.databricks" % "dbutils-api_2.11" % "0.0.4"
    
  • Maven

    <dependency>
        <groupId>com.databricks</groupId>
        <artifactId>dbutils-api_2.11</artifactId>
        <version>0.0.4</version>
    </dependency>
    
  • Gradle

    compile 'com.databricks:dbutils-api_2.11:0.0.4'
    

Po sestavení aplikace z této knihovny můžete aplikaci nasadit.

Důležité

dbutils-apiKnihovna umožňuje místně kompilovat aplikaci, která používá dbutils , ale ne ji spustit. Chcete-li aplikaci spustit, je nutné ji nasadit v Azure Databricks.

Vyjádřit verzi Scala artefaktu pomocí %%

Pokud vyjádřete verzi artefaktu jako groupID %% artifactID % revision místo groupID % artifactID % revision (rozdíl je dvojnásobek %% za groupID ), SBT do názvu artefaktu přidá Scala verzi vašeho projektu.

Příklad

Předpokládejme, že scalaVersion pro vaše sestavení je 2.9.1 . Verzi artefaktu můžete napsat následujícím % způsobem:

val appDependencies = Seq(
  "org.scala-tools" % "scala-stm_2.9.1" % "0.3"
)

Následující použití %% je identické:

val appDependencies = Seq(
  "org.scala-tools" %% "scala-stm" % "0.3"
)

Ukázkové projekty

Tady je příklad archivu obsahující minimální ukázkové projekty, které ukazují, jak zkompilovat pomocí dbutils-api knihovny pro tři běžné sestavovací nástroje:

  • sbt: sbt package
  • Maven mvn install
  • Gradle gradle build

Tyto příkazy vytvářejí výstupní jar v umístěních:

  • sbt: target/scala-2.11/dbutils-api-example_2.11-0.0.1-SNAPSHOT.jar
  • Maven target/dbutils-api-example-0.0.1-SNAPSHOT.jar
  • Gradle build/examples/dbutils-api-example-0.0.1-SNAPSHOT.jar

Tuto SKLENICi můžete připojit ke clusteru jako knihovnu, restartovat cluster a potom spustit:

example.Test()

Tento příkaz vytvoří pomůcku pro textové zadání pomocí popisku Hello: a počáteční hodnota World.

Všechna ostatní rozhraní API můžete použít dbutils stejným způsobem.

Chcete-li otestovat aplikaci, která používá dbutils objekt mimo datacihly, můžete objekt nastavovat dbutils voláním:

com.databricks.dbutils_v1.DBUtilsHolder.dbutils0.set(
  new com.databricks.dbutils_v1.DBUtilsV1{
    ...
  }
)

Nahraďte svou vlastní DBUtilsV1 instanci, ve které implementujete metody rozhraní, například jako místní systém souborů mockup pro dbutils.fs .