Comparteix via

Trabajar con parámetros de cuadros de mando

En esta página se explica cómo usar parámetros en paneles de IA/BI. Si en su lugar desea aprender acerca de los filtros de campo, consulte Filtro en campos.

Los parámetros de los cuadros de mando AI/BI le permiten sustituir diferentes valores en las consultas del conjunto de datos en tiempo de ejecución. Esto le permite filtrar datos por criterios como fechas y categorías de productos antes de que los datos se agreguen en una consulta SQL, lo que permite realizar consultas más eficientes y análisis más precisos. Los parámetros pueden utilizarse con widgets de filtrado para que los cuadros de mando sean interactivos o con widgets de visualización para facilitar la reutilización de los conjuntos de datos.

Los autores o editores de cuadros de mando añaden parámetros a los conjuntos de datos y los conectan a uno o varios widgets en el lienzo del cuadro de mando. Para los parámetros estáticos establecidos en los widgets de visualización, los valores son establecidos por los autores o editores. Para los parámetros utilizados en los widgets de filtrado, los espectadores del cuadro de mandos pueden interactuar con los datos seleccionando valores en los widgets de filtrado en tiempo de ejecución. Esta interacción vuelve a ejecutar las consultas asociadas y muestra visualizaciones basadas en los datos filtrados.

Elegir entre filtros de campo y parámetros

Los parámetros modifican directamente la consulta, que puede ser eficaz. Los filtros de campo de conjunto de datos también pueden ofrecer interactividad en el cuadro de mandos, más funciones y mejor rendimiento con conjuntos de datos grandes que los parámetros. Para obtener más información, consulte ¿Debo filtrar por un campo o un parámetro?.

Adición de un parámetro a una consulta

Es necesario tener al menos permisos PUEDE EDITAR en el panel de borrador para agregar un parámetro a un conjunto de datos del panel. Agregue parámetros directamente a las consultas del conjunto de datos en la pestaña Datos.

Gif que muestra un ejemplo de los pasos siguientes.

Para agregar un parámetro a una consulta:

  1. Coloque el cursor donde quiera colocar el parámetro en la consulta.

  2. Haga clic en Agregar parámetro para insertar un nuevo parámetro.

    Esto creará un nuevo parámetro con el nombre predeterminado parameter. Para cambiar el nombre predeterminado, reemplácelo en el editor de consultas. También es posible agregar parámetros escribiendo esta sintaxis en el editor de consultas.

Edición de un parámetro de consulta

Para editar un parámetro:

  1. Haga clic en Icono de engranaje. Junto al nombre del parámetro. Aparece un cuadro de diálogo Detalles del parámetro e incluye las siguientes opciones de configuración:

    • Palabra clave: palabra clave que representa el parámetro de la consulta. Esto solo se puede cambiar actualizando directamente el texto de la consulta.

    • Nombre para mostrar: nombre en el editor de filtros. De manera predeterminada, el título es el mismo que la palabra clave.

    • Tipo: los tipos admitidos incluyen Cadena, Fecha, Fecha y hora y Numérico.

      • El tipo predeterminado es Cadena.
      • El tipo de datos Numérico permite especificar entre Decimal y Entero. El tipo numérico predeterminado es Decimal.

    • Permitir selecciones múltiples: Seleccione la casilla de verificación para permitir a los usuarios elegir múltiples parámetros en tiempo de ejecución.

      Nota

      Esta selección puede requerir un cambio adicional en su consulta. Consulte Permitir selecciones múltiples.

  2. Haga clic en otra parte de la interfaz de usuario para cerrar el cuadro de diálogo.

Establecimiento de un valor de parámetro predeterminado

Para probar la consulta, escriba un valor predeterminado en el campo de texto bajo el nombre del parámetro y ejecute la consulta. Esto aplica el valor del parámetro para que pueda obtener una vista previa de los resultados y confirmar que la consulta se ejecuta según lo previsto. La ejecución de la consulta también guarda el valor predeterminado.

Cuando se usa el parámetro en un widget de filtro, se usa el valor predeterminado de la pestaña Datos a menos que el widget especifique un valor predeterminado diferente. Consulte Utilizar filtros.

Los autores del panel deben confirmar que las consultas con parámetros se ejecutan correctamente con los valores predeterminados seleccionados en la pestaña del conjunto de datos. Azure Databricks consulta el esquema del conjunto de datos para rellenar el editor de configuración del widget. En algunos casos, especialmente con consultas con parámetros que usan la IDENTIFIER cláusula , la consulta del conjunto de datos puede no ejecutarse con los valores de parámetro predeterminados, aunque se realice correctamente cuando un usuario selecciona un valor en tiempo de ejecución.

Permitir selecciones múltiples

Las consultas que permiten selecciones múltiples deben incluir una función ARRAY_CONTAINS en la consulta.

El siguiente ejemplo muestra una consulta SQL que permite seleccionar varios valores para insertarlos en la consulta en tiempo de ejecución. La cláusula WHERE utiliza la función ARRAY_CONTAINS. Dicha función toma como argumentos la palabra clave parameter y el nombre de la columna. El parámetro debe establecerse para contener varios valores para que se pueda insertar en la consulta como una matriz. Cuando se ejecuta la consulta, se evalúa cada fila y todas las filas donde l_quantity coincide con al menos un valor de :parameter se incluyen en el conjunto de resultados.

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

Para establecer valores predeterminados:

  1. Escriba una consulta de conjunto de datos que use la función ARRAY_CONTAINS para filtrar filas en función de una lista de valores.

  2. Haga clic en Icono de engranaje. El icono de engranaje situado junto al nombre del parámetro. Seleccione Permitir varias selecciones.

    Nota

    Este paso permite insertar el parámetro en la consulta como una matriz. Si se usa la función ARRAY_CONTAINS sin habilitar varias selecciones, se produce un error.

  3. Escriba un valor en el campo de texto situado bajo el nombre de la pantalla. Puede escribir más de un valor. Seleccione el valor actual antes de introducir el siguiente.

Los valores por defecto se establecen en el editor. Los valores múltiples se seleccionan y se separan con un espacio.

Aplicar parámetros de rango de fechas

Puede utilizar parámetros para definir un rango y devolver solo resultados dentro de ese rango. Cuando se selecciona uno de los siguientes tipos de parámetros, se crean dos parámetros que se designan mediante los sufijos .min y .max:

  • Intervalo de fechas
  • Intervalo de fecha y hora

El siguiente ejemplo muestra una consulta SQL que crea un parámetro de intervalo de fechas denominado date_param.

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

Para crear un parámetro de intervalo de fechas

  1. Haga clic en Añadir parámetro.

  2. Haga clic en Icono de engranaje. Junto al nombre del parámetro. Introduzca Palabra clave y Nombre de visualización. No incluya los sufijos .min o .max.

  3. Elija Rango de fechas o Rango de fechas y horas como Tipo.

  4. Inserte una cláusula WHERE que defina el rango en su consulta. Para definir el intervalo, utilice una cláusula BETWEEN con valores .min y .max. Por ejemplo:

     WHERE date_col BETWEEN :date_param.min AND :date_param.max

  5. Introduzca valores de fecha predeterminados y ejecute la consulta para probarla. Utilice el icono del calendario para elegir opciones preestablecidas como la última semana o el último mes.

Parámetros basados en consultas

Los parámetros basados en consultas permiten a los autores definir una lista dinámica o estática de valores entre los que los espectadores pueden elegir al establecer parámetros a medida que exploran los datos de un panel. Se definen mediante la combinación de un filtro de campo y un filtro de parámetros en un único widget de filtro.

Para crear un parámetro basado en consultas, el creador del panel realizará los pasos siguientes:

  1. Crear un conjunto de datos cuyo conjunto de resultados esté limitado a una lista de posibles valores de parámetro.
  2. Crear una consulta de conjunto de datos que use un parámetro.
  3. Configurar un widget de filtro en el lienzo que filtre por un campo y use un parámetro.
    • Las configuraciones de Campos deben establecerse para usar el campo con la lista deseada de valores de parámetro aptos.
    • La configuración Parámetros debe establecerse para seleccionar un valor de parámetro.

Consulte Uso de parámetros basados en consultas para ver un tutorial paso a paso que muestra cómo agregar un parámetro y una visualización basados en consultas.

Nota

Si un conjunto de datos usado en parámetros basados en consultas también se usa en otras visualizaciones de un panel, la selección de filtro de un visor modifica todas las consultas conectadas. Para evitar esto, los autores deberán crear un conjunto de datos dedicado para los parámetros basados en consultas que no se usen en ninguna otra visualización del panel.

Creación de una lista de parámetros dinámicos

Para crear un conjunto de datos dinámico que rellene la lista desplegable que usan los visores para seleccionar valores de parámetro, escriba una consulta SQL que devuelva un único campo e incluya todos los valores de ese campo. Cualquier nuevo valor en ese campo se añade automáticamente como selección de parámetros. Una consulta SQL de ejemplo sería la siguiente:

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Creación de una lista desplegable de parámetros dinámicos

Creación de una lista de parámetros estáticos

Puede crear un conjunto de datos estático que solo incluya valores que usted haya codificado en su conjunto de datos. Una consulta de ejemplo sería la siguiente:

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

Eliminación de un parámetro de consulta

Para quitar un parámetro, elimínelo de la consulta.

Parámetros de widgets estáticos

Los parámetros de widgets estáticos se configuran directamente en un widget de visualización, lo que permite a los autores parametrizar individualmente los widgets de visualización que comparten el mismo conjunto de datos. Esto permite que el mismo conjunto de datos presente diferentes vistas en el lienzo.

El ejemplo de esta sección se basa en un conjunto de datos que consulta la tabla samples.nyctaxi.trips. La consulta proporcionada devuelve la distancia de cada viaje y clasifica el día de recogida como Weekday o Weekend. El parámetro de consulta filtra los resultados en función de si la recogida se produjo un día laborable o un fin de semana.

El texto de la consulta se proporciona en el siguiente bloque de código, pero las instrucciones de esta sección se limitan a configurar las visualizaciones asociadas con los parámetros estáticos del widget. Para obtener instrucciones sobre cómo configurar un conjunto de datos con parámetros, consulte Añadir un parámetro a una consulta.


  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

Para añadir un parámetro de widget estático a una visualización:

  1. Agregue un widget de visualización al lienzo del panel de borrador.

  2. Con el nuevo widget seleccionado, elija el conjunto de datos parametrizado en el desplegable Conjunto de datos del panel de configuración.

  3. Haga clic en Mostrar filtros. Para los conjuntos de datos que incluyen parámetros, aparece una sección Parámetros en el panel de configuración.

    un panel de configuración de visualización que muestra la opción de elegir un parámetro.

  4. Haga clic en el signo más a la derecha del encabezado Parámetros y elija un parámetro del menú desplegable.

  5. Por defecto, el valor del parámetro refleja lo que se establece en la consulta en la pestaña Datos. Puede mantenerlo o elegir un nuevo valor para sustituirlo en el conjunto de datos. Desplácese fuera del campo de texto para mostrar la visualización con el nuevo parámetro aplicado.

  6. Revise su panel.

    La siguiente imagen muestra dos widgets de visualización. Cada uno está configurado como un histograma con un parámetro de widget estático. El gráfico de la izquierda muestra la distribución de las distancias de los viajes que comienzan en días laborables, mientras que el gráfico de la derecha muestra los mismos datos para los fines de semana. Ambas visualizaciones se basan en el mismo conjunto de datos.

    Dos histogramas, configurados para utilizar parámetros estáticos a nivel de widget, como se ha descrito.

Comparar datos utilizando una condición de filtro

Puede agregar una condición de filtro que le permita comparar agregaciones en una parte de los datos con las agregaciones aplicadas a todo el conjunto de datos.

El siguiente ejemplo amplía la consulta anterior para incluir una condición de filtro en la que el valor del parámetro especificado es All, que no aparece en los datos. La primera parte de la condición de filtrado funciona igual que en el ejemplo anterior, filtrando los resultados en los que day_type es Weekday o Weekend. La segunda parte de la condición de filtrado comprueba si el propio parámetro tiene un valor determinado, en este caso All, que no aparece en los datos. Cuando se establece el valor predeterminado para ese parámetro en el editor de conjuntos de datos, se omite efectivamente el filtro cuando ni Weekday ni Weekend se pasan como valores.


WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

Puede utilizar este conjunto de datos para configurar tres widgets de visualización, con el day_type_param ajustado a All, Weekday y Weekend respectivamente. A continuación, los visualizadores del cuadro de mandos pueden comparar cada conjunto de datos filtrado por tipo de día con el conjunto de datos completo.

El siguiente GIF muestra cómo se pueden crear rápidamente tres gráficos a partir del conjunto de datos creado con esta consulta.

  1. El primer gráfico está configurado para mostrar el conjunto de datos Distancias de viaje por tipo de día con un valor de parámetro establecido en Día de la semana.
  2. Clone el gráfico para mantener todas las configuraciones aplicadas.
  3. Para mostrar los datos de los viajes realizados durante el fin de semana, ajuste el parámetro estático a Fin de semana.
  4. Clone el nuevo gráfico para mantener todas las configuraciones aplicadas anteriormente.
  5. Ajuste el parámetro en el nuevo gráfico a Todos para mostrar el recuento total de viajes por distancia para los viajes realizados en fin de semana y entre semana.

Un gif como el descrito en el texto anterior.

Mostrar parámetros en el panel

Añadir un filtro al lienzo del cuadro de mando permite a los espectadores seleccionar y modificar los valores de los parámetros para explorar y analizar los datos de forma interactiva. Si no expone el parámetro en el cuadro de mandos, los espectadores solo verán los resultados de la consulta que utilicen el valor predeterminado del parámetro que haya establecido en la consulta.

Para agregar un parámetro al panel:

  1. Haga clic en Icono de filtroAgregar un filtro (campo/parámetro).
  2. Haga clic en Icono Agregar campo, junto a Parámetros, en el panel de configuración.
  3. Haga clic en el nombre del parámetro que quiera que el visor use con este widget.

Trabajar con widgets de filtro y parámetros estáticos

Los parámetros son valores fijos que se sustituyen en una consulta en tiempo de ejecución. Si dos o más referencias al mismo parámetro se establecen con valores diferentes cuando se actualiza el cuadro de mandos, los widgets de visualización muestran un error que indica qué parámetro tiene valores contradictorios. Esto puede ocurrir cuando varios widgets de filtro utilizan el mismo parámetro o cuando un parámetro estático entra en conflicto con un widget de filtro que permite la selección del visor.

Podría utilizar un patrón como el del siguiente ejemplo para establecer valores de reserva para diferentes parámetros en la misma consulta.


CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

En este ejemplo, :static_param hace referencia a un parámetro estático, que debe establecerse en "All" tanto en el widget de visualización como en el editor de conjuntos de datos. El parámetro :dash_param es un valor dinámico controlado por un widget de filtro en el lienzo del cuadro de mandos. Esta instrucción comprueba si se ha proporcionado un valor como parámetro estático. Si no se establece ninguno, vuelve a un valor de parámetro del cuadro de mandos seleccionado por el usuario.

Incluir parámetros en la dirección URL

La configuración de parámetros se almacena en la dirección URL, lo que permite a los usuarios marcarlo para mantener el estado del panel, incluidos los filtros y parámetros preestablezcan, o compartirlos con otros usuarios para aplicar los mismos filtros y parámetros de forma coherente.

Parámetros del cuadro de mandos frente a parámetros de consulta Mustache

Los parámetros del panel usan la misma sintaxis que los marcadores de parámetros con nombre. Consulta Marcadores de parámetros con nombre. Los cuadros de mandos no admiten parámetros de estilo Mustache.

Ejemplos de sintaxis

Los usos comunes de los parámetros incluyen la inserción de fechas, números, texto, objetos de base de datos y valores de cadenas JSON. Para obtener ejemplos que muestran cómo usar parámetros en estos casos, vea ejemplos de sintaxis de parámetros con nombre .

Importante

Permitir a los visualizadores acceder a los datos a través de selecciones de parámetros como nombres de tablas o catálogos podría dar lugar a la exposición accidental de información confidencial. Si va a publicar un panel con estas opciones, Azure Databricks recomienda no insertar credenciales en el panel publicado.

  • Last updated on