Widgets de Databricks

Artículo
10/29/2024

Los widgets de entrada le permiten agregar parámetros a los cuadernos y paneles. Puede agregar un widget desde la interfaz de usuario de Databricks o mediante la API de widget. Para agregar o editar un complemento, debe tener permiso PUEDE EDITAR en el cuaderno.

Si ejecuta Databricks Runtime 11.3 LTS o superior, también puede usar ipywidgets en cuadernos de Databricks.

Los widgets de Databricks son los más adecuados para:

Creación de un cuaderno o panel que se vuelva a ejecutar con parámetros diferentes.
Explorar rápidamente los resultados de una sola consulta con parámetros diferentes.

Para ver la documentación de la API de widget en Scala, Python o R, use el siguiente comando: dbutils.widgets.help(). También puede consultar la documentación de la utilidad widgets (dbutils.widgets).

Hay 4 tipos de widgets:

text: para escribir un valor en un cuadro de texto.
dropdown: para seleccionar un valor de una lista de valores proporcionados.
combobox: combinación de texto y lista desplegable. Seleccione un valor de una lista proporcionada o escriba uno en el cuadro de texto.
multiselect: para seleccionar uno o varios valores de una lista de valores proporcionados.

Las listas desplegables y los cuadros de texto de widget aparecen inmediatamente después de la barra de herramientas del cuaderno. Los widgets solo aceptan valores de cadena.

Crear widgets

En esta sección se muestra cómo crear widgets mediante la interfaz de usuario o mediante programación mediante magics de SQL o la API de widget para Python, Scala y R.

Crear widgets mediante la interfaz de usuario

Cree un widget mediante la interfaz de usuario del cuaderno. Si está conectado a una instancia de SQL warehouse, esta es la única manera de crear widgets.

Seleccione Editar > Agregar widget. En el cuadro de diálogo Agregar widget, escriba el nombre del widget, la etiqueta opcional, el tipo, el tipo de parámetro, los valores posibles y el valor predeterminado opcional. En el cuadro de diálogo, Nombre de parámetro es el nombre que se usa para hacer referencia al widget en el código. Etiqueta de widget es un nombre opcional que aparece sobre el widget en la interfaz de usuario.

Después de crear un widget, puede mantener el puntero sobre el nombre del widget para mostrar una información sobre herramientas que describe cómo hacer referencia al widget.

Puede utilizar el menú kebab para editar o eliminar el widget:

Crear widgets con SQL, Python, R y Scala

Cree widgets en un cuaderno conectado a un clúster de proceso mediante programación.

La API de widget está diseñada para ser coherente en Scala, Python y R. La API del widget en SQL es ligeramente diferente, pero equivalente a los otros lenguajes. Los widgets se administran mediante la interfaz de referencia de utilidades de Databricks (dbutils).

El primer argumento para todos los tipos de widget es name. Este es el nombre que usa para acceder al widget.
El segundo argumento es defaultValue, la configuración predeterminada del widget.
El tercer argumento para todos los tipos de widget (excepto text) es choices, una lista de valores que el widget puede tomar. Este argumento no se usa para los widgets de tipo text.
El último argumento es label, un valor opcional para la etiqueta que se muestra sobre el cuadro de texto del widget o la lista desplegable.

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

Interactúe con el widget desde el panel del widget.

Puede acceder al valor actual del widget o obtener una asignación de todos los widgets:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Por último, puede quitar un widget o todos los widgets de un cuaderno:

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

Si quita un widget, no puede crear uno en la misma celda. Debe crear el widget en otra celda.

Los valores del widget de acceso de Spark SQL y SQL Warehouse mediante marcadores de parámetros. Los marcadores de parámetro protegen el código frente a ataques por inyección de código SQL separando claramente los valores proporcionados de las instrucciones SQL.

Los marcadores de parámetro para widgets están disponibles en Databricks Runtime 15.2 y versiones posteriores. Las versiones anteriores de Databricks Runtime deben usar la sintaxis antigua para DBR 15.1 y versiones posteriores.

Puede acceder a widgets definidos en cualquier lenguaje desde Spark SQL mientras ejecuta cuadernos de forma interactiva. Considere el siguiente flujo de trabajo:

Cree un widget desplegable de todas las bases de datos del catálogo actual:

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

Cree un widget de texto para especificar manualmente un nombre de tabla:
```
dbutils.widgets.text("table", "")
```
Ejecute una consulta SQL para ver todas las tablas de una base de datos (seleccionada en la lista desplegable):
```
SHOW TABLES IN IDENTIFIER(:database)
```
Nota:

Debe usar la cláusula SQL IDENTIFIER() para analizar cadenas como identificadores de objeto como nombres para bases de datos, tablas, vistas, funciones, columnas y campos.
Escriba manualmente un nombre de tabla en el widget table.
Cree un widget de texto para especificar un valor de filtro:
```
dbutils.widgets.text("filter_value", "")
```
Obtenga una vista previa del contenido de una tabla sin necesidad de editar el contenido de la consulta:
```
SELECT *
FROM IDENTIFIER(:database || '.' || :table)
WHERE col == :filter_value
LIMIT 100
```

En esta sección se describe cómo pasar valores de widgets de Databricks a %sql celdas de cuaderno en Databricks Runtime 15.1 y versiones posteriores.

Cree widgets para especificar valores de texto.

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"

Pase los valores del widget mediante la sintaxis ${param}.

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

Nota:

Para escapar el carácter $ en un literal de cadena de SQL, use \$. Por ejemplo, para expresar la cadena $1,000, use "\$1,000". No se puede escapar el carácter $ para los identificadores de SQL.

Puede configurar el comportamiento de los widgets cuando se selecciona un nuevo valor, indicar si el panel del widget siempre está anclado a la parte superior del cuaderno y cambiar el diseño de los widgets del cuaderno.

Haga clic en el icono en el extremo derecho del panel del widget.
En el cuadro de diálogo emergente de configuración del panel del widget, elija el comportamiento de ejecución del widget.
- Ejecutar cuaderno: cada vez que se selecciona un nuevo valor, se vuelve a ejecutar todo el cuaderno.
- Ejecutar comandos a los que se ha accedido: cada vez que se selecciona un nuevo valor, solo se vuelven a ejecutar las celdas que recuperan los valores de ese widget determinado. Esta es la configuración predeterminada cuando se crea un widget. Las celdas de SQL no se vuelvan a ejecutar en esta configuración.
- No hacer nada: cada vez que se selecciona un nuevo valor, no se vuelve a ejecutar nada.
Para anclar los widgets a la parte superior del cuaderno o colocar los widgets encima de la primera celda, haga clic en . La configuración se guarda por cada usuario. Vuelva a hacer clic en el icono de la huella digital para restablecer el comportamiento predeterminado.
Si tiene el permiso PUEDE ADMINISTRAR para cuadernos, puede configurar el diseño del widget haciendo clic en . Se puede personalizar el orden y el tamaño de cada widget. Para guardar o descartar los cambios, haga clic en .

El diseño del widget se guarda con el cuaderno. Si cambia el diseño del widget de la configuración predeterminada, los nuevos widgets no se agregan alfabéticamente.
Para restablecer el diseño del widget al orden y tamaño predeterminados, haga clic en para abrir el cuadro de diálogo de configuración del panel del widget y, a continuación, haga clic en Restablecer diseño. El comando removeAll() no restablece el diseño del widget.