Widgets de Databricks

Artículo
03/11/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 widgets en Scala, Python o R, use el siguiente comando: dbutils.widgets.help()

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.

Para crear un widget, 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 sugerencia de herramientas que describe cómo hacer referencia al widget.

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

Uso de widgets de Databricks en un clúster de proceso

En esta sección se describe cómo usar widgets de Databricks en un cuaderno asociado a un clúster de proceso. Para usar widgets en un cuaderno que está asociado a un almacenamiento de SQL, vea Uso de widgets de Databricks en una instancia de SQL Warehouse.

La API de widgets está diseñada para ser coherente en Scala, Python y R. La API de widgets en SQL es ligeramente diferente, pero tan eficaz como 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 puede tomar el widget. 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.

Para ver la documentación detallada de la API para cada método, use dbutils.widgets.help("<method-name>"). La API de ayuda es idéntica en todos los lenguajes. Por ejemplo:

dbutils.widgets.help("dropdown")

Cree un widget desplegable simple.

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

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

Puede acceder al valor actual del widget con la llamada:

Python

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

SQL

REMOVE WIDGET state

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

Spark SQL accede a los valores del widget como literales de cadena que se pueden usar en las consultas.

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 ${database}
```
Escriba manualmente un nombre de tabla en el widget table.
Obtenga una vista previa del contenido de una tabla sin necesidad de editar el contenido de la consulta:
```
SELECT *
FROM ${database}.${table}
LIMIT 100
```

Nota:

En general, no puede usar widgets para pasar argumentos entre distintos lenguajes dentro de un cuaderno. Puede crear un widget arg1 en una celda Python y usarlo en una celda SQL o Scala si ejecuta una celda a la vez. Sin embargo, esto no funciona si usa Ejecutar todo o ejecuta el cuaderno como un trabajo.

Soluciones alternativas:

En el caso de los cuadernos que no mezclan idiomas, puede crear un cuaderno para cada idioma y pasar los argumentos al ejecutar el cuaderno.
- Puede acceder al widget mediante una llamada spark.sql(). Por ejemplo, en Python: spark.sql("select getArgument('arg1')").take(1)[0][0].

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.

Usar widgets de Databricks en un almacenamiento de SQL

En esta sección se describe cómo usar widgets de Databricks en un cuaderno asociado a un almacenamiento de SQL. Para usar widgets en un cuaderno asociado a un clúster de proceso, vea Uso de widgets de Databricks en un clúster de proceso.

Para hacer referencia a los valores de widget en un almacén de SQL, use la sintaxis :param, no $param. Por ejemplo, si tiene un widget denominado fare_amount, use código similar al siguiente:

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

Use la palabra clave IDENTIFIER para identificar objetos como tablas, vistas, esquemas y columnas. Por ejemplo, si el widget denominado table_name está establecido en samples.nyctaxi.trips:

SELECT * FROM IDENTIFIER(:table_name)

Para obtener más información, vea cláusula IDENTIFIER.

Para obtener más información sobre la sintaxis del marcador de parámetros, vea Marcadores de parámetros.

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 en orden alfabético.
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.

Cuaderno de ejemplo

Puede ver una demostración de cómo funciona la opción Ejecutar comandos a los que se ha accedido en el cuaderno siguiente. El widget year se crea con la configuración 2014 y se usa en la API para dataframes y los comandos SQL.

Al cambiar la configuración del widget year a 2007, el comando DataFrame se vuelve a ejecutar, pero el comando SQL no se vuelve a ejecutar.

En este cuaderno se muestra el uso de widgets en un cuaderno asociado a un clúster, no a SQL Warehouse.

Obtener el cuaderno