Compartir vía

Widgets de Databricks

  • Artículo

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

Tipos de widgets de Databricks

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.

Widget en el encabezado

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.

cuadro de diálogo crear widget

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.

información sobre herramientas del widget

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

menú de kebab 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.

Interacción con widgets

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.

Usar valores de widget en Spark SQL y SQL Warehouse

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:

  1. 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()])

  2. Cree un widget de texto para especificar manualmente un nombre de tabla:

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

  3. 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.

  4. Escriba manualmente un nombre de tabla en el widget table.

  5. Cree un widget de texto para especificar un valor de filtro:

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

  6. 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

Usar valores de widget en Databricks Runtime 15.1 y versiones posteriores

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.

  1. 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"

  1. 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.

Configuración de las opciones de widget

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.

  1. Haga clic en el icono Icono de engranaje en el extremo derecho del panel del widget.

  2. En el cuadro de diálogo emergente de configuración del panel del widget, elija el comportamiento de ejecución del widget.

    Configuración de las opciones de 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.

  3. Para anclar los widgets a la parte superior del cuaderno o colocar los widgets encima de la primera celda, haga clic en Icono de anclaje. La configuración se guarda por cada usuario. Vuelva a hacer clic en el icono de la huella digital para restablecer el comportamiento predeterminado.

  4. Si tiene el permiso PUEDE ADMINISTRAR para cuadernos, puede configurar el diseño del widget haciendo clic en Icono de edición. Se puede personalizar el orden y el tamaño de cada widget. Para guardar o descartar los cambios, haga clic en Iconos para aceptar y cancelar.

    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.

  5. Para restablecer el diseño del widget al orden y tamaño predeterminados, haga clic en Icono de engranaje 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

En el cuaderno siguiente se muestra cómo funciona la configuración Ejecutar comandos accedidos. El widget year se crea con la configuración 2014 y se usa en los comandos DATAFrame API y SQL.

Widgets

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.

Cuaderno de demostración del widget

Obtener el cuaderno

Widgets de Databricks en paneles

Al crear un panel desde un cuaderno con widgets de entrada, todos los widgets se muestran en la parte superior. En el modo de presentación, cada vez que actualice el valor de un widget, puede hacer clic en el botón Actualizar para volver a ejecutar el cuaderno y actualizar el panel con nuevos valores.

Panel con widgets

Uso de widgets de Databricks con %run

Si ejecuta un cuaderno que contiene widgets, el cuaderno especificado se ejecuta con los valores predeterminados del widget.

Si el cuaderno está asociado a un clúster (no a SQL warehouse), también puede pasar valores a widgets. Por ejemplo:

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

En este ejemplo, se ejecuta el cuaderno especificado y se pasa 10 al widget X y 1 al widget Y.

Limitaciones

  • Los límites siguientes se aplican a los widgets:

    • Se pueden crear un máximo de 512 widgets en un cuaderno.
    • Un nombre de widget está limitado a 1024 caracteres.
    • Una etiqueta de widget está limitada a 2048 caracteres.
    • Un máximo de 2048 caracteres puede ser entrada en un widget de texto.
    • Puede haber un máximo de 1024 opciones para un widget de selección múltiple, cuadro combinado o widget desplegable.

  • Hay un problema conocido por el que un estado del widget puede no borrarse correctamente después de presionar Ejecutar todo, incluso después de borrar o quitar el widget en el código. Si esto sucede, verá una discrepancia entre el objeto visual del widget y los estados impresos. Volver a ejecutar las celdas individualmente puede esquivar este problema. Para evitar este problema por completo, Databricks recomienda usar ipywidgets.

  • No debe tener acceso al estado del widget directamente en contextos asincrónicos como subprocesos, subprocesos o Structured Streaming (foreachBatch), ya que el estado del widget puede cambiar mientras se ejecuta el código asincrónico. Si necesita acceder al estado del widget en un contexto asincrónico, páselo como argumento. Por ejemplo, si tiene el código siguiente que usa subprocesos:

    import threading

def thread_func():
  # Unsafe access in a thread
  value = dbutils.widgets.get('my_widget')
  print(value)

thread = threading.Thread(target=thread_func)
thread.start()
thread.join()

    A continuación, debe escribirlo de esta manera en su lugar:

    # Access widget values outside the asynchronous context and pass them to the function
value = dbutils.widgets.get('my_widget')

def thread_func(val):
  # Use the passed value safely inside the thread
  print(val)

thread = threading.Thread(target=thread_func, args=(value,))
thread.start()
thread.join()

  • En general, los widgets no pueden pasar argumentos entre distintos idiomas 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. Algunas soluciones alternativas son:

    • 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].