Databricks 유틸리티(dbutils) 참조

이 문서는 Databricks 유틸리티(dbutils)에 대한 참조입니다. dbutils 유틸리티는 Python, R 및 Scala Notebook에서 사용할 수 있습니다. 유틸리티를 사용하여 다음을 수행할 수 있습니다.

• 파일 및 개체 스토리지를 효율적으로 작업합니다.
• 비밀로 작업합니다.

방법: 유틸리티 나열, 명령 나열, 명령 도움말 표시

유틸리티: data, fs, jobs, library, notebook, secrets, widgets, 유틸리티 API 라이브러리

사용 가능한 유틸리티 나열

각 유틸리티에 대한 간단한 설명과 함께 사용 가능한 유틸리티를 나열하려면 Python 또는 Scala에 대해 dbutils.help()를 실행합니다.

다음 예제에서는 Databricks 유틸리티에 사용 가능한 명령을 나열합니다.

Python

dbutils.help()

Scala

dbutils.help()

This module provides various utilities for users to interact with the rest of Databricks.

credentials: DatabricksCredentialUtils -> Utilities for interacting with credentials within notebooks
data: DataUtils -> Utilities for understanding and interacting with datasets (EXPERIMENTAL)
fs: DbfsUtils -> Manipulates the Databricks filesystem (DBFS) from the console
jobs: JobsUtils -> Utilities for leveraging jobs features
library: LibraryUtils -> Utilities for session isolated libraries
meta: MetaUtils -> Methods to hook into the compiler (EXPERIMENTAL)
notebook: NotebookUtils -> Utilities for the control flow of a notebook (EXPERIMENTAL)
preview: Preview -> Utilities under preview category
secrets: SecretUtils -> Provides utilities for leveraging secrets within notebooks
widgets: WidgetsUtils -> Methods to create and get bound value of input widgets inside notebooks

유틸리티에 사용 가능한 명령 나열

각 명령에 대한 간단한 설명과 함께 유틸리티에 사용 가능한 명령을 나열하려면 유틸리티의 프로그래밍 이름 뒤에 .help()를 실행합니다.

다음 예제에서는 DBFS(Databricks 파일 시스템) 유틸리티에 사용 가능한 명령을 나열합니다.

Python

dbutils.fs.help()

R

dbutils.fs.help()

Scala

dbutils.fs.help()

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

fsutils

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

mount

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

명령에 대한 도움말 표시

명령에 대한 도움말을 표시하려면 명령 이름 뒤에 .help("<command-name>")을 실행합니다.

다음 예제에서는 DBFS 복사 명령에 대한 도움말을 표시합니다.

Python

dbutils.fs.help("cp")

R

dbutils.fs.help("cp")

Scala

dbutils.fs.help("cp")

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

데이터 유틸리티(dbutils.data)

명령: summarize

data 유틸리티를 사용하면 데이터 세트를 이해하고 해석할 수 있습니다. 사용 가능한 명령을 나열하려면 dbutils.data.help()를 실행합니다.

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

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

summarize 명령(dbutils.data.summarize)

Apache Spark DataFrame 또는 pandas DataFrame의 요약 통계를 계산하고 표시합니다. 이 명령은 Python, Scala 및 R에서 사용할 수 있습니다.

이 명령은 DataFrame의 전체 콘텐츠를 분석합니다. 매우 큰 DataFrame에 대해 이 명령을 실행하면 비용이 많이 들 수 있습니다.

이 명령에 대한 도움말을 표시하려면 dbutils.data.help("summarize")를 실행합니다.

Databricks Runtime 10.4 LTS 이상에서는 추가 precise 매개 변수를 사용하여 계산된 통계의 전체 자릿수를 조정할 수 있습니다.

• precise가 false(기본값)로 설정되면 일부 반환된 통계에는 런타임을 줄이기 위한 근사값이 포함됩니다.
  • 범주형 열에 대한 고유 값의 수에는 카디널리티가 높은 열에 대한 ~5% 이하의 상대 오차가 있을 수 있습니다.
  • 고유 값의 수가 10,000개보다 크면 자주 발생하는 값의 수에 최대 0.01%의 오차가 있을 수 있습니다.
  • 히스토그램 및 백분위수 추정치에는 총 행 수에 비해 최대 0.01%의 오차가 있을 수 있습니다.
• precise가 true로 설정되면 통계가 더 높은 정밀도로 계산됩니다. 이제 숫자 열에 대한 히스토그램 및 백분위수를 제외한 모든 통계가 정확합니다.
  • 히스토그램 및 백분위수 추정치는 총 행 수에 비해 최대 0.0001%의 오류가 있을 수 있습니다.

데이터 요약 출력 위쪽의 도구 설명은 현재 실행 모드를 나타냅니다.

다음 예제에서는 기본적으로 사용하도록 설정된 근사값과 함께 Apache Spark DataFrame에 대한 요약 통계를 표시합니다. 결과를 보려면 Notebook에서 이 명령을 실행합니다. 이 예제는 샘플 데이터 세트를 기반으로 합니다.

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)

시각화에서는 SI 표기법을 사용하여 0.01보다 작거나 10000보다 큰 숫자 값을 간결하게 렌더링합니다. 예를 들어 1.25e-15 숫자 값은 1.25f로 렌더링됩니다. 한 가지 예외: 시각화에서 1.0e9(기가)에 대해 "G" 대신 "B"를 사용합니다.

파일 시스템 유틸리티(dbutils.fs)

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

파일 시스템 유틸리티를 사용하면 DBFS란?에 액세스할 수 있으므로 Azure Databricks를 파일 시스템으로 더 쉽게 사용할 수 있습니다.

Notebook에서 매직 명령을 사용하여 %fs DBFS에 액세스할 수도 있습니다. 예를 들어 %fs ls /Volumes/main/default/my-volume/ .dbutils.fs.ls("/Volumes/main/default/my-volume/") 매직 명령을 참조 하세요.

사용 가능한 명령을 나열하려면 dbutils.fs.help()를 실행합니다.

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

fsutils

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

mount

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

cp 명령(dbutils.fs.cp)

파일 또는 디렉터리를 파일 시스템 간에 복사합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("cp")를 실행합니다.

이 예제에서는 명명 data.csv /Volumes/main/default/my-volume/ new-data.csv 된 파일을 동일한 볼륨에 복사합니다.

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 명령(dbutils.fs.head)

지정된 파일의 지정된 최대 수 바이트까지 반환합니다. 바이트는 UTF-8로 인코딩된 문자열로 반환됩니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("head")를 실행합니다.

다음 예제에서는 /Volumes/main/default/my-volume/에 있는 data.csv 파일의 처음 25바이트를 표시합니다.

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"

ls 명령(dbutils.fs.ls)

디렉터리의 콘텐츠를 나열합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("ls")를 실행합니다.

다음 예제에서는 /Volumes/main/default/my-volume/의 콘텐츠에 대한 정보를 표시합니다. 이 modificationTime 필드는 Databricks Runtime 10.4 LTS 이상에서 사용할 수 있습니다. R에서 modificationTime은 문자열로 반환됩니다.

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

mkdirs 명령(dbutils.fs.mkdirs)

없는 경우 지정된 디렉터리를 만듭니다. 필요한 부모 디렉터리도 만듭니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("mkdirs")를 실행합니다.

이 예제에서는 .my-data /Volumes/main/default/my-volume/

Python

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

# Out[15]: True

R

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

# [1] TRUE

Scala

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

// res7: Boolean = true

mount 명령(dbutils.fs.mount)

지정된 원본 디렉터리를 DBFS의 지정된 탑재 지점에 탑재합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("mount")를 실행합니다.

Python

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

Scala

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

추가 코드 예제는 Azure Data Lake Storage Gen2 및 Blob Storage에 연결을 참조 하세요.

mounts 명령(dbutils.fs.mounts)

현재 DBFS 내에 탑재된 항목에 대한 정보를 표시합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("mounts")를 실행합니다.

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

추가 코드 예제는 Azure Data Lake Storage Gen2 및 Blob Storage에 연결을 참조 하세요.

mv 명령(dbutils.fs.mv)

파일 또는 디렉터리를 파일 시스템 간에 이동합니다. 이동은 파일 시스템 내의 이동에 대해서도 복사 후 삭제입니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("mv")를 실행합니다.

다음 예제에서는 rows.csv 파일을 /Volumes/main/default/my-volume/에서 /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 명령(dbutils.fs.put)

지정된 문자열을 파일에 씁니다. 문자열은 UTF-8로 인코딩됩니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("put")를 실행합니다.

다음 예제에서는 Hello, Databricks! 문자열을 /Volumes/main/default/my-volume/의 hello.txt라는 파일에 씁니다. 파일이 있으면 덮어씁니다.

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

refreshMounts 명령(dbutils.fs.refreshMounts)

클러스터의 모든 컴퓨터에서 탑재 캐시를 새로 고쳐 최신 정보를 받도록 합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("refreshMounts")를 실행합니다.

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

추가 코드 예제는 Azure Data Lake Storage Gen2 및 Blob Storage에 연결을 참조 하세요.

rm 명령(dbutils.fs.rm)

파일 또는 디렉터리를 제거하고 필요에 따라 모든 내용을 제거합니다. 파일을 지정하면 재귀 매개 변수가 무시됩니다. 디렉터리를 지정하면 재귀가 비활성화되고 디렉터리가 비어 있지 않으면 오류가 발생합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("rm")를 실행합니다.

다음은 디렉터리의 내용을 포함하여 디렉터리를 /Volumes/main/default/my-volume/my-data/ 제거하는 예제입니다.

Python

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

# Out[8]: True

R

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

# [1] TRUE

Scala

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

// res6: Boolean = true

unmount 명령(dbutils.fs.unmount)

DBFS 탑재 지점을 삭제합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("unmount")를 실행합니다.

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

추가 코드 예제는 Azure Data Lake Storage Gen2 및 Blob Storage에 연결을 참조 하세요.

updateMount 명령(dbutils.fs.updateMount)

dbutils.fs.mount 명령과 비슷하지만, 새 탑재 지점을 만드는 대신 기존 탑재 지점을 업데이트합니다. 탑재 지점이 없으면 오류를 반환합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.fs.help("updateMount")를 실행합니다.

이 명령은 Databricks Runtime 10.4 LTS 이상에서 사용할 수 있습니다.

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

작업 유틸리티(dbutils.jobs)

하위 작업: taskValues

작업 유틸리티를 사용하면 작업 기능을 활용할 수 있습니다. 이 유틸리티에 대한 도움말을 표시하려면 dbutils.jobs.help()를 실행합니다.

Provides utilities for leveraging jobs features.

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

taskValues 하위 유틸리티(dbutils.jobs.taskValues)

명령: get, set

작업 태스크 값을 활용하기 위한 명령을 제공합니다.

이 하위 유틸리티를 사용하여 작업 실행 중에 임의의 값을 설정하고 가져옵니다. 이러한 값을 태스크 값이라고 합니다. 동일한 작업 실행에서 다운스트림 작업의 태스크 값에 액세스할 수 있습니다. 예를 들어 작업 실행 내의 여러 태스크 간에 기계 학습 모델의 평가에 대한 정보와 같은 식별자 또는 메트릭을 커뮤니케이션할 수 있습니다. 각 태스크는 여러 작업 값을 설정하거나, 가져오거나 둘 다 수행할 수 있습니다. 각 태스크 값은 동일한 태스크 내에 고유한 키가 있습니다. 이 고유한 키를 태스크 값의 키라고 합니다. 태스크 이름 및 태스크 값의 키를 사용하여 태스크 값에 액세스합니다.

이 하위 유틸리티에 대한 도움말을 표시하려면 dbutils.jobs.taskValues.help()를 실행합니다.

get 명령(dbutils.jobs.taskValues.get)

현재 작업 실행에서 지정한 태스크에 대해 지정된 태스크 값의 내용을 가져옵니다.

이 명령에 대한 도움말을 표시하려면 dbutils.jobs.taskValues.help("get")를 실행합니다.

예시:

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

앞의 예에서:

• taskKey 는 작업 값을 설정하는 작업의 이름입니다. 명령에서 이 태스크를 찾을 수 없으면 ValueError가 발생합니다.
• key는 set 명령(dbutils.jobs.taskValues.set)을 사용하여 설정한 태스크 값의 키 이름입니다. 명령에서 이 태스크 값의 키를 찾을 수 없는 경우 ValueError가 발생합니다(default를 지정하지 않은 경우).
• default는 key를 찾을 수 없는 경우에 반환되는 선택적 값입니다. default는 None일 수 없습니다.
• debugValue는 작업 외부에서 실행되는 Notebook 내에서 태스크 값을 가져오는 경우 반환되는 선택적 값입니다. 이는 디버깅 중에 Notebook을 수동으로 실행하고 기본적으로 TypeError를 발생시키는 대신 일부 값을 반환하려는 경우에 유용할 수 있습니다. debugValue는 None일 수 없습니다.

작업 외부에서 실행되는 Notebook 내에서 태스크 값을 얻으려고 하면 이 명령은 기본적으로 TypeError를 표시합니다. 그러나 명령에서 debugValue 인수를 지정하면 TypeError가 발생하는 대신 debugValue 값이 반환됩니다.

set 명령(dbutils.jobs.taskValues.set)

태스크 값을 설정하거나 업데이트합니다. 작업 실행에 대해 최대 250개의 태스크 값을 설정할 수 있습니다.

이 명령에 대한 도움말을 표시하려면 dbutils.jobs.taskValues.help("set")를 실행합니다.

일부 사례:

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

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

앞의 예에서

• key 는 작업 값의 키입니다. 이 키는 작업에 고유해야 합니다. 즉, 서로 다른 두 작업이 각각 키를 K사용하여 작업 값을 설정하는 경우 키가 같은 K두 개의 서로 다른 작업 값입니다.
• value는 이 작업 값의 키에 대한 값입니다. 이 명령은 내부적으로 값을 JSON 형식으로 표현할 수 있어야 합니다. 값의 JSON 표현 크기는 48KiB를 초과할 수 없습니다.

작업 외부에서 실행되는 Notebook 내에서 태스크 값을 설정하려고 하면 이 명령은 아무 작업도 수행하지 않습니다.

라이브러리 유틸리티(dbutils.library)

하위 모듈의 dbutils.library 대부분의 메서드는 더 이상 사용되지 않습니다. 라이브러리 유틸리티(dbutils.library)(레거시)를 참조하세요.

로컬로 설치되거나 업그레이드된 라이브러리가 현재 SparkSession의 Python 커널에서 올바르게 작동하도록 하려면 Azure Databricks에서 Python 프로세스를 프로그래밍 방식으로 다시 시작해야 할 수 있습니다. 이렇게 하려면 dbutils.library.restartPython 명령을 실행합니다. Azure Databricks에서 Python 프로세스 다시 시작을 참조 하세요.

Notebook 유틸리티(dbutils.notebook)

명령: exit, run

notebook 유틸리티를 사용하면 Notebook을 함께 연결하고 결과에 따라 작업을 수행할 수 있습니다. 다른 Notebook에서 Databricks Notebook 실행을 참조하세요.

사용 가능한 명령을 나열하려면 dbutils.notebook.help()를 실행합니다.

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

exit 명령(dbutils.notebook.exit)

값이 있는 Notebook을 종료합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.notebook.help("exit")를 실행합니다.

다음 예제에서는 Exiting from My Other Notebook 값이 있는 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

run 명령(dbutils.notebook.run)

Notebook을 실행하고 해당 종료 값을 반환합니다. Notebook은 기본적으로 현재 클러스터에서 실행됩니다.

이 명령에 대한 도움말을 표시하려면 dbutils.notebook.help("run")를 실행합니다.

다음 예제에서는 호출하는 Notebook과 동일한 위치에서 My Other Notebook이라는 Notebook을 실행합니다. 호출된 Notebook은 dbutils.notebook.exit("Exiting from My Other Notebook") 코드 줄로 끝납니다. 호출된 Notebook이 60초 이내에 실행을 완료하지 않으면 예외가 throw됩니다.

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

비밀 유틸리티(dbutils.secrets)

명령: get, getBytes, list, listScopes

secrets 유틸리티를 사용하면 중요한 자격 증명 정보를 Notebook에 표시하지 않고 저장하고 액세스할 수 있습니다. 비밀 관리 및 Notebook에서 비밀 사용을 참조하세요. 사용 가능한 명령을 나열하려면 dbutils.secrets.help()를 실행합니다.

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

get 명령(dbutils.secrets.get)

지정된 비밀 범위 및 키에 대한 비밀 값의 문자열 표현을 가져옵니다.

이 명령에 대한 도움말을 표시하려면 dbutils.secrets.help("get")를 실행합니다.

다음 예제에서는 my-scope라는 범위와 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 명령(dbutils.secrets.getBytes)

지정된 범위 및 키에 대한 비밀 값의 바이트 표현을 가져옵니다.

이 명령에 대한 도움말을 표시하려면 dbutils.secrets.help("getBytes")를 실행합니다.

다음 예제에서는 범위 my-scope 및 키 my-key에 대한 비밀 값(이 예에서는 a1!b2@c3#)의 바이트 표현을 가져옵니다.

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 명령(dbutils.secrets.list)

지정된 범위 내의 비밀에 대한 메타데이터를 나열합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.secrets.help("list")를 실행합니다.

다음 예제에서는 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 명령(dbutils.secrets.listScopes)

사용 가능한 범위를 나열합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.secrets.help("listScopes")를 실행합니다.

다음 예제에서는 사용 가능한 범위를 나열합니다.

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

위젯 유틸리티(dbutils.widgets)

명령: combobox, dropdown, get, getArgument, multiselect, remove, removeAll, text

widgets 유틸리티를 사용하면 Notebook을 매개 변수화할 수 있습니다. Databricks 위젯을 참조하세요.

사용 가능한 명령을 나열하려면 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
getAll: map -> Retrieves a map of all widget names and their values
getArgument(name: String, optional: String): String -> (DEPRECATED) Equivalent to get
multiselect(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a multiselect input widget with a given name, default value and choices
remove(name: String): void -> Removes an input widget from the notebook
removeAll: void -> Removes all widgets in the notebook
text(name: String, defaultValue: String, label: String): void -> Creates a text input widget with a given name and default value

combobox 명령(dbutils.widgets.combobox)

지정된 프로그래밍 이름, 기본값, 선택 항목 및 선택적 레이블을 사용하여 콤보 상자 위젯을 만들고 표시합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.widgets.help("combobox")를 실행합니다.

다음 예제에서는 프로그래밍 이름이 fruits_combobox인 콤보 상자 위젯을 만들고 표시합니다. apple, banana, coconut 및 dragon fruit 선택 항목을 제공하고 초기 값(banana)으로 설정됩니다. 이 콤보 상자 위젯에는 Fruits 레이블이 함께 포함됩니다. 다음 예제에서는 콤보 상자 위젯의 초기 값(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 명령(dbutils.widgets.dropdown)

지정된 프로그래밍 이름, 기본값, 선택 항목 및 선택적 레이블을 사용하여 드롭다운 위젯을 만들고 표시합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.widgets.help("dropdown")를 실행합니다.

다음 예제에서는 프로그래밍 이름이 toys_dropdown인 드롭다운 위젯을 만들고 표시합니다. alphabet blocks, basketball, cape 및 doll 선택 항목을 제공하고 초기 값(basketball)으로 설정됩니다. 이 드롭다운 위젯에는 Toys 레이블이 함께 포함됩니다. 다음 예제에서는 드롭다운 위젯의 초기 값(basketball)을 출력하는 것으로 끝납니다.

Python

dbutils.widgets.dropdown(
  name='toys_dropdown',
  defaultValue='basketball',
  choices=['alphabet blocks', 'basketball', 'cape', 'doll'],
  label='Toys'
)

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

# basketball

R

dbutils.widgets.dropdown(
  name='toys_dropdown',
  defaultValue='basketball',
  choices=list('alphabet blocks', 'basketball', 'cape', 'doll'),
  label='Toys'
)

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

# [1] "basketball"

Scala

dbutils.widgets.dropdown(
  "toys_dropdown",
  "basketball",
  Array("alphabet blocks", "basketball", "cape", "doll"),
  "Toys"
)

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

// basketball

SQL

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

SELECT :toys_dropdown

-- basketball

get 명령(dbutils.widgets.get)

지정된 프로그래밍 이름이 있는 위젯의 현재 값을 가져옵니다. 이 프로그래밍 이름은 다음 중 하나일 수 있습니다.

• Notebook에 있는 사용자 지정 위젯의 이름(예: fruits_combobox 또는 toys_dropdown)
• Notebook 태스크의 일부로 Notebook에 전달된 사용자 지정 매개 변수의 이름(예: name 또는 age). 자세한 내용은 작업 만들기 UI에서 Notebook 태스크 매개 변수의 적용 범위를 참조하거나 작업 API의 새 작업 실행 트리거(POST /jobs/run-now) 작업에서 notebook_params 필드를 참조하세요. I.

이 명령에 대한 도움말을 표시하려면 dbutils.widgets.help("get")를 실행합니다.

다음 예제에서는 프로그래밍 이름이 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

다음 예제에서는 프로그래밍 이름이 age인 Notebook 태스크 매개 변수의 값을 가져옵니다. 이 매개 변수는 관련 Notebook 태스크가 실행될 때 35로 설정되었습니다.

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 명령(dbutils.widgets.getAll)

모든 현재 위젯 이름 및 값의 매핑을 가져옵니다. 위젯 값을 쿼리에 빠르게 전달하는 데 특히 유용할 spark.sql() 수 있습니다.

이 명령은 Databricks Runtime 13.3 LTS 이상에서 사용할 수 있습니다. Python 및 Scala에만 사용할 수 있습니다.

이 명령에 대한 도움말을 표시하려면 dbutils.widgets.help("getAll")를 실행합니다.

이 예제에서는 위젯 값의 맵을 가져오고 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 명령(dbutils.widgets.getArgument)

지정된 프로그래밍 이름이 있는 위젯의 현재 값을 가져옵니다. 위젯이 없으면 선택적 메시지가 반환될 수 있습니다.

이 명령에 대한 도움말을 표시하려면 dbutils.widgets.help("getArgument")를 실행합니다.

다음 예제에서는 프로그래밍 이름이 fruits_combobox인 위젯의 값을 가져옵니다. 이 위젯이 없으면 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

multiselect 명령(dbutils.widgets.multiselect)

지정된 프로그래밍 이름, 기본값, 선택 항목 및 선택적 레이블을 사용하여 다중 선택 위젯을 만들고 표시합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.widgets.help("multiselect")를 실행합니다.

다음 예제에서는 프로그래밍 이름이 days_multiselect인 다중 선택 위젯을 만들고 표시합니다. Monday부터 Sunday까지의 선택 항목을 제공하고 초기 값(Tuesday)으로 설정됩니다. 이 다중 선택 위젯에는 Days of the Week 레이블이 함께 포함됩니다. 다음 예제에서는 다중 선택 위젯의 초기 값(Tuesday)을 출력하는 것으로 끝납니다.

Python

dbutils.widgets.multiselect(
  name='days_multiselect',
  defaultValue='Tuesday',
  choices=['Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday', 'Sunday'],
  label='Days of the Week'
)

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

# Tuesday

R

dbutils.widgets.multiselect(
  name='days_multiselect',
  defaultValue='Tuesday',
  choices=list('Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday', 'Sunday'),
  label='Days of the Week'
)

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

# [1] "Tuesday"

Scala

dbutils.widgets.multiselect(
  "days_multiselect",
  "Tuesday",
  Array("Monday", "Tuesday", "Wednesday", "Thursday",
    "Friday", "Saturday", "Sunday"),
  "Days of the Week"
)

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

// Tuesday

SQL

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

SELECT :days_multiselect

-- Tuesday

remove 명령(dbutils.widgets.remove)

지정된 프로그램 이름이 있는 위젯을 제거합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.widgets.help("remove")를 실행합니다.

다음 예제에서는 프로그래밍 이름이 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 명령(dbutils.widgets.removeAll)

Notebook에서 모든 위젯을 제거합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.widgets.help("removeAll")를 실행합니다.

다음 예제에서는 Notebook에서 모든 위젯을 제거합니다.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

text 명령(dbutils.widgets.text)

지정된 프로그래밍 이름, 기본값 및 선택적 레이블을 사용하여 텍스트 위젯을 만들고 표시합니다.

이 명령에 대한 도움말을 표시하려면 dbutils.widgets.help("text")를 실행합니다.

다음 예제에서는 프로그래밍 이름이 your_name_text인 텍스트 위젯을 만들고 표시합니다. 초기 값(Enter your name)으로 설정됩니다. 이 텍스트 위젯에는 Your name 레이블이 함께 포함됩니다. 다음 예제에서는 텍스트 위젯의 초기 값(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

Databricks 유틸리티 API 라이브러리

애플리케이션 개발을 가속화하려면 먼저 애플리케이션을 컴파일, 빌드 및 테스트한 후에 프로덕션 작업으로 배포하는 것이 도움이 될 수 있습니다. Databricks 유틸리티에 대해 컴파일할 수 있도록 Databricks에서 dbutils-api 라이브러리를 제공합니다. Maven 리포지토리 웹 사이트의 DBUtils API 웹 페이지에서 dbutils-api 라이브러리를 다운로드하거나 종속성을 빌드 파일에 추가하여 라이브러리를 포함할 수 있습니다.

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

TARGET을 원하는 대상(예: 2.12)으로 바꾸고, VERSION을 원하는 버전(예: 0.0.5)으로 바꿉니다. 사용 가능한 대상 및 버전의 목록은 Maven 리포지토리 웹 사이트의 DBUtils API 웹 페이지를 참조하세요.

이 라이브러리에 대해 애플리케이션이 빌드되면 해당 애플리케이션을 배포할 수 있습니다.

제한 사항

실행기 내부에서 dbutils를 호출하면 예기치 않은 결과가 생성되거나 잠재적으로 오류가 발생할 수 있습니다.

dbutils를 사용하여 실행기에서 파일 시스템 작업을 실행해야 하는 경우 더 빠르고 확장성 있는 몇 가지 대안을 사용할 수 있습니다.

• 파일 복사 또는 이동 작업의 경우 파일 시스템 작업 병렬화에서 설명하는 파일 시스템 작업 실행에 대한 더 빠른 옵션을 확인할 수 있습니다.
• 파일 시스템 나열 및 삭제 작업의 경우 Databricks에서 파일을 더 빠르게 나열하고 삭제하는 방법에서 Spark를 활용하는 병렬 나열 및 삭제 메서드를 참조할 수 있습니다.

실행기에 대한 자세한 내용은 Apache Spark 웹 사이트의 클러스터 모드 개요를 참조하세요.