위젯

입력 위젯을 사용하면 Notebook 및 대시보드에 매개 변수를 추가할 수 있습니다. 위젯 API는 다양한 유형의 입력 위젯을 만들고, 제거하고, 제한된 값을 가져오는 호출로 구성됩니다.

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

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

다음 명령을 사용하여 Scala, Python, R의 위젯 API 설명서를 확인할 수 있습니다.

dbutils.widgets.help()

위젯 유형

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

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

위젯 드롭다운 및 텍스트 상자는 Notebook 도구 모음 바로 다음에 나타납니다.

Widget dropdown

위젯 API

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

dbutils.widgets.dropdown("X123", "1", [str(x) for x in range(1, 10)])

dbutils.widgets.dropdown("1", "1", [str(x) for x in range(1, 10)], "hello this is a widget")

dbutils.widgets.dropdown("x123123", "1", [str(x) for x in range(1, 10)], "hello this is a widget")

dbutils.widgets.dropdown("x1232133123", "1", [str(x) for x in range(1, 10)], "hello this is a widget 2")

위젯 예제

간단한 드롭다운 위젯을 만듭니다.

dbutils.widgets.dropdown("X", "1", [str(x) for x in range(1, 10)])

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

Interact with widget

다음 호출을 사용하여 위젯의 현재 값에 액세스할 수 있습니다.

dbutils.widgets.get("X")

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

dbutils.widgets.remove("X")

dbutils.widgets.removeAll()

중요

위젯을 제거하는 명령을 추가하면 위젯을 동일한 셀에 만드는 후속 명령을 추가할 수 없습니다. 위젯을 만들려면 다른 셀을 사용해야 합니다.

Scala, Python, R의 위젯

각 메서드에 대한 자세한 API 설명서를 보려면 dbutils.widgets.help("<method-name>")을 사용합니다. 도움말 API는 모든 언어에서 동일합니다. 예를 들면 다음과 같습니다.

dbutils.widgets.help("dropdown")

드롭다운 위젯은 고유한 식별 이름, 기본값, 기본 선택 항목 목록과 선택적 레이블을 전달하여 만들 수 있습니다. 드롭다운 위젯을 만들면 Notebook 상단에 드롭다운 입력 위젯이 나타납니다. 이러한 입력 위젯은 Notebook 수준 엔터티입니다.

이미 존재하는 위젯을 만들려고 시도하면 기존 위젯의 구성이 새 옵션으로 덮어쓰기됩니다.

SQL 위젯

SQL에서 위젯을 만드는 API는 약간 다르지만 다른 언어의 API만큼 강력합니다. 다음은 텍스트 입력 위젯을 만드는 예제입니다.

CREATE WIDGET TEXT y DEFAULT "10"

SQL 드롭다운 위젯에서 선택 가능한 값을 지정하려면 하위 쿼리를 작성하면 됩니다. 하위 쿼리의 결과 테이블의 첫 번째 열이 값을 결정합니다.

다음 셀은 테이블에 대한 하위 쿼리에서 드롭다운 위젯을 만듭니다.

CREATE WIDGET DROPDOWN cuts DEFAULT "Good" CHOICES SELECT DISTINCT cut FROM diamonds

드롭다운 위젯을 만들 때 지정된 기본값은 선택 가능한 값 중 하나여야 하며 문자열 리터럴로 지정해야 합니다. SQL 입력 위젯의 현재 선택된 값에 액세스하려면 쿼리에서 특수 UDF 함수를 사용하면 됩니다. 이 함수는 getArgument()입니다. 예를 들면 다음과 같습니다.

SELECT COUNT(*) AS numChoices, getArgument("cuts") AS cuts FROM diamonds WHERE cut = getArgument("cuts")

참고

getArgument는 스칼라 UDF로 구현되며, 테이블 ACL을 사용하도록 설정된 높은 동시성 클러스터에서는 지원되지 않습니다. 이러한 클러스터에서는 다음 예제에 나와 있는 $<parameter> 구문을 사용하세요.

$<parameter> 구문을 사용하여 SQL 입력 위젯의 현재 값에 액세스할 수도 있습니다.

SELECT * FROM diamonds WHERE cut LIKE '%$cuts%'

SQL 명령을 사용하여 위젯을 제거할 수 있습니다.

REMOVE WIDGET cuts

중요

일반적으로, 위젯을 사용하여 하나의 Notebook 내에서 다른 언어 간에 인수를 전달할 수 없습니다. 셀을 하나씩 실행하는 경우 Python 셀에서 위젯 arg1을 만들고 SQL 또는 Scala 셀에서 위젯을 사용할 수 있습니다. 단, 모두 실행을 사용하여 모든 명령을 실행하거나 Notebook을 작업으로 실행하는 경우에는 작동하지 않습니다. 이 제한 사항을 해결하려면 각 언어에 대해 Notebook을 만들고 Notebook을 실행할 때 인수를 전달할 것을 권장합니다.

SQL의 레거시 입력 위젯

참고

2022년 1월 15일부터 레거시 SQL 위젯의 렌더링에 대한 Databricks의 지원이 종료됩니다. 위젯이 계속해서 UI에서 렌더링되도록 하려면 코드가 SQL 위젯을 사용하도록 업데이트하세요. 지원이 종료된 후에도 코드에서 $<parameter>를 사용하여 %run을 통해 Notebook으로 전달된 매개 변수를 가져올 수 있습니다.

$<parameter> 구문을 사용하여 SQL 쿼리로 위젯을 만드는 기존 방법은 전과 동일하게 작동합니다. 다음은 예제입니다.

SELECT * FROM diamonds WHERE cut LIKE '%$cuts%'

참고

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

위젯 설정 구성

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

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

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

    Widget settings

    • Notebook 실행: 새 값이 선택될 때마다 Notebook 전체가 다시 실행됩니다.

    • 액세스된 명령 실행: 새 값이 선택될 때마다 해당 위젯에 대해 값을 검색하는 셀만 다시 실행됩니다. 위젯을 만들 때 이 옵션이 기본값으로 설정됩니다.

      참고

      이 구성에서는 SQL 셀이 다시 실행되지 않습니다.

    • 아무 작업도 안 함: 새 값이 선택될 때마다 아무것도 다시 실행되지 않습니다.

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

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

    참고

    위젯 레이아웃은 Notebook에 저장됩니다.

    위젯 레이아웃이 구성된 경우 새 위젯이 알파벳순으로 추가됩니다.

  5. 위젯 레이아웃을 기본 순서와 크기로 재설정하려면 gear icon 아이콘을 클릭하여 위젯 패널 설정 대화 상자를 열고 레이아웃 다시 설정을 클릭합니다.

    참고

    위젯 레이아웃은 removeAll() 명령을 사용하여 재설정할 수 없습니다.

Notebook

다음 Notebook에서 액세스된 명령 실행 설정이 작동하는 방식에 대한 데모를 볼 수 있습니다. year 위젯이 2014 설정으로 만들어지고 DataFrame API 및 SQL 명령에서 사용됩니다.

Widgets

year 위젯의 설정을 2007로 변경하면 DataFrame 명령은 다시 실행되지만 SQL 명령은 다시 실행되지 않습니다.

위젯 데모 Notebook

Notebook 가져오기

대시보드의 위젯

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

Dashboard with widgets

%run을 통해 위젯 사용

위젯을 포함하는 Notebook을 실행하면 지정된 Notebook이 위젯의 기본값으로 실행됩니다. 위젯에 값을 전달할 수도 있습니다. 예를 들면 다음과 같습니다.

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

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