Databricks 위젯

아티클
03/09/2024

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

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

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

다른 매개 변수를 사용하여 다시 실행되는 Notebook 또는 대시보드 빌드
다른 매개 변수를 사용하여 단일 쿼리의 결과를 빠르게 탐색합니다.

Scala, Python 또는 R에서 위젯 API에 대한 설명서를 보려면 dbutils.widgets.help() 명령을 사용합니다.

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

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

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

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

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

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

컴퓨팅 클러스터에서 Databricks 위젯 사용

이 섹션에서는 컴퓨팅 클러스터에 연결된 Notebook에서 Databricks 위젯을 사용하는 방법을 설명합니다. SQL 웨어하우스에 연결된 Notebook에서 위젯을 사용하려면 SQL 웨어하우스에서 Databricks 위젯 사용을 참조하세요.

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

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

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

dbutils.widgets.help("dropdown")

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

Python

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

SQL

SELECT "${state}"

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

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

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

Spark SQL은 쿼리에서 사용할 수 있는 문자열 리터럴로 위젯 값에 액세스합니다.

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

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

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

수동으로 테이블 이름을 지정하는 텍스트 위젯을 만듭니다.
```
dbutils.widgets.text("table", "")
```
SQL 쿼리를 실행하여 데이터베이스의 모든 테이블을 확인합니다(드롭다운 목록에서 선택됨).
```
SHOW TABLES IN ${database}
```
table 위젯에 테이블 이름을 수동으로 입력합니다.
쿼리 내용을 편집할 필요 없이 테이블 내용을 미리 봅니다.
```
SELECT *
FROM ${database}.${table}
LIMIT 100
```

참고 항목

일반적으로, 위젯을 사용하여 하나의 Notebook 내에서 다른 언어 간에 인수를 전달할 수 없습니다. 한 번의 하나의 셀을 실행하는 경우 Python 셀에서 위젯 arg1을 만들고 SQL 또는 Scala 셀에서 위젯을 사용할 수 있습니다. 그러나 모두 실행을 사용하거나 Notebook을 작업으로 실행하는 경우에는 작동하지 않습니다.

해결 방법:

언어를 혼합하지 않는 Notebook의 경우 언어별로 Notebook을 만들고 Notebook을 실행할 때 인수를 전달할 수 있습니다.
- spark.sql() 호출을 사용하여 위젯에 액세스할 수 있습니다. 예를 들어 Python spark.sql("select getArgument('arg1')").take(1)[0][0]의 경우입니다.

참고 항목

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

SQL 웨어하우스에서 Databricks 위젯 사용

이 섹션에서는 SQL 웨어하우스에 연결된 Notebook에서 Databricks 위젯을 사용하는 방법을 설명합니다. 컴퓨팅 클러스터에 연결된 Notebook에서 위젯을 사용하려면 컴퓨팅 클러스터에서 Databricks 위젯 사용을 참조하세요.

SQL 웨어하우스에서 위젯 값을 참조하려면 구문을 :param사용하지 않고 $param사용합니다. 예를 들어 fare_amount이라는 위젯이 있는 경우 다음과 유사한 코드를 사용합니다.

SELECT * FROM samples.nyctaxi.trips WHERE fare_amount < :fare_amount

IDENTIFIER 키워드(keyword) 사용하여 테이블, 뷰, 스키마 및 열과 같은 개체를 식별합니다. 예를 들어 table_name이라는 위젯이 다음으로 samples.nyctaxi.trips설정된 경우

SELECT * FROM IDENTIFIER(:table_name)

자세한 내용은 IDENTIFIER 절을 참조하세요.

매개 변수 표식 구문에 대한 자세한 내용은 매개 변수 표식을 참조 하세요.

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

위젯 패널의 오른쪽 끝에 있는 아이콘을 클릭합니다.
팝업되는 위젯 패널 설정 대화 상자에서 위젯의 실행 동작을 선택합니다.
- Notebook 실행: 새 값이 선택될 때마다 Notebook 전체가 다시 실행됩니다.
- 액세스된 명령 실행: 새 값이 선택될 때마다 해당 위젯에 대해 값을 검색하는 셀만 다시 실행됩니다. 위젯을 만들 때 이 옵션이 기본값으로 설정됩니다. 이 구성에서는 SQL 셀이 다시 실행되지 않습니다.
- 아무 작업도 안 함: 새 값이 선택될 때마다 아무것도 다시 실행되지 않습니다.
위젯을 전자 필기장 위쪽에 고정하거나 위젯을 첫 번째 셀 위에 배치하려면 을 클릭합니다 . 설정은 사용자 단위로 저장됩니다. 압정 아이콘을 다시 클릭하여 기본 동작으로 다시 설정합니다.
Notebook에 대한 CAN MANAGE 권한이 있는 경우 을 클릭하여 위젯 레이아웃을 구성할 수 있습니다. 각 위젯의 순서와 크기를 사용자 지정할 수 있습니다. 변경 내용을 저장하거나 해제하려면 을 클릭합니다 .

위젯 레이아웃은 Notebook에 저장됩니다. 위젯 레이아웃을 기본 구성에서 변경하면 새 위젯이 사전순으로 추가되지 않습니다.
위젯 레이아웃을 기본 순서 및 크기 로 다시 설정하려면 위젯 패널 설정 대화 상자를 열고 레이아웃 다시 설정을 클릭합니다. removeAll() 명령은 위젯 레이아웃을 다시 설정하지 않습니다.

예제 Notebook

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

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

이 Notebook은 SQL 웨어하우스가 아닌 클러스터에 연결된 Notebook에서 위젯을 사용하는 방법을 보여 줍니다.

전자 필기장 가져오기

대시보드의 Databricks 위젯

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

%run에서 Databricks 위젯 사용

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

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

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

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

제한 사항

위젯에는 다음 제한이 적용됩니다.
- Notebook에서 최대 512개의 위젯을 만들 수 있습니다.
- 위젯 이름은 1024자로 제한됩니다.
- 위젯 레이블은 2048자로 제한됩니다.
- 최대 2048자를 텍스트 위젯에 입력할 수 있습니다.
- 다중 선택, 콤보 상자 또는 드롭다운 위젯에 대해 최대 1024개의 선택 항목이 있을 수 있습니다.
코드에서 위젯을 지우거나 제거한 후 모두 실행을 누른 후에도 위젯 상태가 제대로 지워지지 않을 수 있는 알려진 문제가 있습니다. 이 경우 위젯의 시각적 상태와 인쇄된 상태 간에 불일치가 표시됩니다. 셀을 개별적으로 다시 실행하면 이 문제가 무시됩니다. 이 문제를 완전히 방지하려면 Databricks에서 ipywidgets를 사용하는 것이 좋습니다.

Databricks 위젯