다음을 통해 공유

Databricks 위젯

  • 아티클

입력 위젯을 사용하면 Notebook 및 대시보드에 매개 변수를 추가할 수 있습니다. Databricks UI 또는 위젯 API를 사용하여 위젯을 추가할 수 있습니다. 위젯을 추가하거나 편집하려면, CAN EDIT에 대한 Notebook 권한이 있어야 합니다.

Databricks Runtime 11.3 LTS 이상을 실행하는 경우 Databricks Notebook의 ipywidgets를 사용할 수도 있습니다.

Databricks 위젯은 다음과 같은 경우에 가장 적합합니다.

  • 여러 매개 변수를 사용하여 다시 실행되는 Notebook 또는 대시보드 만들기.
  • 여러 매개 변수를 갖는 단일 쿼리의 결과를 빠르게 살펴보기.

Scala, Python 또는 R에서 위젯 API에 대한 설명서를 보려면 다음 명령을 dbutils.widgets.help()사용합니다. 위젯 유틸리티(dbutils.widgets) 설명서를 참조 할 수도 있습니다.

Databricks 위젯 형식

위젯에는 다음과 같은 4가지 유형이 있습니다.

  • text: 텍스트 상자에 값을 입력합니다.
  • dropdown: 제공된 값 목록에서 값을 선택합니다.
  • combobox: 텍스트와 드롭다운의 조합입니다. 제공된 목록에서 값을 선택하거나 텍스트 상자에 값을 입력합니다.
  • multiselect: 제공된 값 목록에서 하나 이상의 값을 선택합니다.

위젯 드롭다운 및 텍스트 상자는 Notebook 도구 모음 바로 다음에 나타납니다. 위젯은 문자열 값만 허용합니다.

머리글의 위젯

위젯 만들기

이 섹션에서는 UI를 사용하거나 SQL 매직 또는 Python, Scala 및 R용 위젯 API를 사용하여 프로그래밍 방식으로 위젯을 만드는 방법을 보여 줍니다.

UI를 사용하여 위젯 만들기

Notebook UI를 사용하여 위젯을 만듭니다. SQL 웨어하우스에 연결된 경우 위젯을 만들 수 있는 유일한 방법입니다.

편집 > 위젯 추가를 선택합니다. 위젯 추가 대화 상자에서, 위젯 이름, 선택적 레이블, 형식, 매개 변수 형식, 가능한 값 및 선택적 기본값을 입력합니다. 대화 상자 에서 매개 변수 이름은 코드의 위젯을 참조하는 데 사용하는 이름입니다. 위젯 레이블은 UI의 위젯 위에 표시되는 선택적 이름입니다.

위젯 대화 상자 만들기

위젯을 만든 후에 위젯 이름에 마우스룰 놓으면 위젯을 참조하는 방법을 설명하는 도구 설명을 표시할 수 있습니다.

위젯 도구 설명

케밥 메뉴를 사용하여 위젯을 편집하거나 제거할 수 있습니다:

위젯 케밥 메뉴

SQL, Python, R 및 Scala를 사용하여 위젯 만들기

컴퓨팅 클러스터에 연결된 Notebook에서 프로그래밍 방식으로 위젯을 만듭니다.

위젯 API는 Scala, Python, R에서 일관성을 갖도록 설계되었습니다. SQL의 위젯 API는 약간 다르지만 다른 언어와 동일합니다. 위젯은 Databricks 유틸리티(dbutils) 참고 인터페이스를 통해 관리합니다.

  • 모든 위젯 형식의 첫 번째 인수는 name입니다. 위젯에 액세스하는 데 사용하는 이름입니다.
  • 두 번째 인수는 defaultValue로, 위젯의 기본 설정입니다.
  • 세 번째 인수는 (text을 제외한) 모든 위젯 형식은 choices로, 위젯이 사용할 수 있는 값의 목록입니다. 이 인수는 text 형식 위젯에 사용되지 않습니다.
  • 마지막 인수는 위젯 텍스트 상자 또는 드롭다운에 표시되는 레이블의 선택적 값인 label입니다.

Python

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

Scala

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

R

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

SQL

CREATE WIDGET DROPDOWN state DEFAULT "CA" CHOICES SELECT * FROM (VALUES ("CA"), ("IL"), ("MI"), ("NY"), ("OR"), ("VA"))

위젯 패널에서 위젯과 상호 작용합니다.

위젯과 상호 작용

위젯의 현재 값에 액세스하거나 모든 위젯의 매핑을 가져올 수 있습니다:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

마지막으로, Notebook에서 하나의 위젯 또는 모든 위젯을 제거할 수 있습니다.

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

위젯을 제거하면, 동일한 셀에 위젯을 만들 수 없습니다. 위젯을 만들려면 다른 셀을 사용해야 합니다.

Spark SQL 및 SQL Warehouse에서 위젯 값 사용

Spark SQL 및 SQL Warehouse는 매개 변수 표식을 사용하여 위젯 값에 액세스합니다. 매개 변수 표식은 제공된 값을 SQL 문과 명확하게 구분하여 SQL 삽입 공격으로부터 코드를 보호합니다.

위젯에 대한 매개 변수 표식은 Databricks Runtime 15.2 이상에서 사용할 수 있습니다. 이전 버전의 Databricks Runtime은 BR 15.1 이하의 이전 구문을 사용해야 합니다.

대화형으로 Notebook을 실행하는 동안 Spark SQL에서 임의 언어로 정의된 위젯에 액세스할 수 있습니다. 다음 워크플로를 고려하세요.

  1. 현재 카탈로그에 있는 모든 데이터베이스의 드롭다운 위젯을 만듭니다.

    dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])

  2. 수동으로 테이블 이름을 지정하는 텍스트 위젯을 만듭니다.

    dbutils.widgets.text("table", "")

  3. SQL 쿼리를 실행하여 데이터베이스의 모든 테이블을 확인합니다(드롭다운 목록에서 선택됨).

    SHOW TABLES IN IDENTIFIER(:database)

    참고 항목

    SQL IDENTIFIER() 절을 사용하여 문자열을 데이터베이스, 테이블, 뷰, 함수, 열 및 필드에 대한 이름과 같은 개체 식별자로 구문 분석해야 합니다.

  4. table 위젯에 테이블 이름을 수동으로 입력합니다.

  5. 필터 값을 지정하는 텍스트 위젯을 만듭니다:

    dbutils.widgets.text("filter_value", "")

  6. 쿼리 내용을 편집할 필요 없이 테이블 내용을 미리 봅니다.

    SELECT *
FROM IDENTIFIER(:database || '.' || :table)
WHERE col == :filter_value
LIMIT 100

Databricks Runtime 15.1 이하에서 위젯 값 사용

이 섹션에서는 Databricks Runtime 15.1 이하의 Notebook 셀에 Databricks 위젯 값을 %sql에게 전달하는 방법을 설명합니다.

  1. 위젯을 만들어 텍스트 값을 지정합니다.

Python

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

Scala

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

R

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

SQL

 CREATE WIDGET TEXT database DEFAULT ""
 CREATE WIDGET TEXT table DEFAULT ""
 CREATE WIDGET TEXT filter_value DEFAULT "100"

  1. ${param} 구문을 사용하여 위젯 값을 전달합니다.

    SELECT *
FROM ${database}.${table}
WHERE col == ${filter_value}
LIMIT 100

참고 항목

SQL 문자열 리터럴에서 $ 문자를 이스케이프하려면 \$를 사용합니다. 예를 들어 문자열 $1,000을 표현하려면, "\$1,000"를 사용합니다. $ 문자는 SQL 식별자에 대해 이스케이프할 수 없습니다.

위젯 설정 구성합니다

새 값이 선택된 경우의 위젯 동작과 위젯 패널이 항상 Notebook 상단에 고정되는지 여부를 구성하고, Notebook에서 위젯의 레이아웃을 변경할 수 있습니다.

  1. 위젯 패널 오른쪽 끝에 있는 기어 아이콘 아이콘을 클릭합니다.

  2. 팝업되는 위젯 패널 설정 대화 상자에서 위젯의 실행 동작을 선택합니다.

    위젯 설정

    • Notebook 실행: 새 값이 선택될 때마다 Notebook 전체가 다시 실행됩니다.
    • 액세스된 명령 실행: 새 값이 선택될 때마다 해당 위젯에 대해 값을 검색하는 셀만 다시 실행됩니다. 위젯을 만들 때 이 옵션이 기본값으로 설정됩니다. 이 구성에서는 SQL 셀이 다시 실행되지 않습니다.
    • 아무 작업도 안 함: 새 값이 선택될 때마다 아무것도 다시 실행되지 않습니다.

  3. 위젯을 Notebook 상단에 고정하거나 위젯을 첫 번째 셀 위에 놓으려면 고정 아이콘을 클릭합니다. 설정은 사용자 단위로 저장됩니다. 압정 아이콘을 다시 클릭하여 기본 동작으로 다시 설정합니다.

  4. Notebook에 대해 관리할 수 있음 권한을 보유한 경우, 편집 아이콘을 클릭하여 위젯 레이아웃을 구성할 수 있습니다. 각 위젯의 순서와 크기를 사용자 지정할 수 있습니다. 변경 내용을 저장하거나 해제하려면 수락 및 취소 아이콘을 클릭합니다.

    위젯 레이아웃은 Notebook에 저장됩니다. 위젯 레이아웃을 기본 구성에서 변경하면, 새 위젯이 알파벳순으로 추가되지 않습니다.

  5. 위젯 레이아웃을 기본 순서와 크기로 재설정하려면, 기어 아이콘을 클릭하여 위젯 패널 설정 대화 상자를 열고 레이아웃 다시 설정을 클릭합니다. removeAll() 명령은 위젯 레이아웃을 다시 설정하지 않습니다.

대시보드의 Databricks 위젯

입력 위젯이 있는 Notebook에서 대시보드를 만들면, 모든 위젯이 상단에 표시됩니다. 프레젠테이션 모드에서는 위젯의 값을 업데이트할 때마다, 업데이트 단추를 클릭하여 Notebook을 다시 실행하고 대시보드를 새 값으로 업데이트합니다.

위젯이 있는 대시보드

%run에서 Databricks 위젯 사용

위젯을 포함하는 Notebook을 실행하면 지정된 Notebook이 위젯의 기본값으로 실행됩니다.

Notebook이 (SQL 웨어하우스가 아닌) 클러스터에 연결된 경우 위젯에 값을 전달할 수도 있습니다. 예시:

%run /path/to/notebook $X="10" $Y="1"

이 예제에서는 지정된 Notebook을 실행하고 위젯 X에 10을, 위젯 Y에 1을 전달합니다.

제한 사항

자세한 내용은 알려진 제한 사항 Databricks Notebook을 참조하세요.