Compartir a través de

Trabajar con parámetros del panel

  • Artículo

En este artículo se explica cómo usar parámetros en paneles de IA/BI. Si desea obtener información sobre los filtros de campo en su lugar, consulte Filtrar en campos.

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

Los autores o editores del tablero agregan parámetros a los conjuntos de datos y los conectan a uno o varios widgets en el lienzo de un panel. Para los parámetros estáticos establecidos en widgets de visualización, los valores los establecen los autores o editores. Para los parámetros usados en widgets de filtro, los visores de paneles pueden interactuar con los datos seleccionando valores en widgets de filtro en tiempo de ejecución. Esta interacción vuelve a ejecutar las consultas asociadas y muestra visualizaciones basadas en los datos filtrados.

Los parámetros modifican directamente la consulta, que puede ser eficaz. Los filtros de campo de conjunto de datos también pueden ofrecer interactividad del panel, más características y un mejor rendimiento con grandes conjuntos de datos que parámetros. Consulte Uso de filtros.

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 varias selecciones: active la casilla para permitir que los usuarios elijan varios parámetros en tiempo de ejecución.

      Nota:

      Esta selección puede requerir un cambio adicional en la consulta. Consulte Permitir varias selecciones.

  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 que su consulta se ejecute, puede establecer un valor predeterminado para el parámetro escribiendo en el campo de texto bajo el nombre del parámetro. Ejecute la consulta para obtener una vista previa de los resultados de la consulta con el valor de parámetro aplicado. La ejecución de la consulta también guarda el valor predeterminado. Al establecer este parámetro mediante un widget de filtro en el lienzo, se usa el valor predeterminado a menos que se especifique un nuevo valor predeterminado en el widget de filtro. Consulte Uso de filtros.

Permitir varias selecciones

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

En el ejemplo siguiente se muestra una consulta SQL que permite seleccionar varios valores para insertarlos en la consulta en tiempo de ejecución. La WHERE cláusula usa la ARRAY_CONTAINS función . Esa función toma la palabra clave parameter y el nombre de columna como argumentos. Cuando se ejecuta la consulta, devuelve todas las filas que contienen los valores de parámetro seleccionados.

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

Para establecer valores predeterminados, es decir, escriba en el campo de texto bajo el nombre para mostrar. Seleccione el valor actual antes de escribir el siguiente.

Los valores predeterminados se establecen en el editor. Se seleccionan varios valores y se separan por un espacio.

Aplicar parámetros de intervalo de fechas

Puede usar parámetros para definir un intervalo y devolver solo los resultados dentro de ese intervalo. Al elegir uno de los siguientes tipos de parámetros, se crean dos parámetros designados por .min y .max sufijos:

  • Intervalo de fechas
  • Intervalo de fecha y hora

En el ejemplo siguiente se 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 Agregar parámetro.

  2. Haga clic en icono de engranaje, junto al nombre del parámetro. Escriba la palabra clave y el nombre para mostrar. No incluya ni .min .max sufijos.

  3. Elija Intervalo de fechas o Intervalo de fecha y hora como tipo.

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

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

  5. Escriba los valores de fecha predeterminados y ejecute la consulta para probarla. Use el icono de calendario para elegir opciones preestablecidas como la semana pasada o el mes pasado.

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.

Nota:

Si también se usase un conjunto de datos en parámetros basados en consultas en otras visualizaciones de un panel, una selección de filtro del visor modificará 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.

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.

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 de ese campo se agrega automáticamente como una 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 de parámetros estáticos

Puede crear un conjunto de datos estático que solo incluya valores que codifique de forma rígida en el 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 widget estáticos

Los parámetros de widget 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 vistas diferentes en el lienzo.

El ejemplo de esta sección se basa en un conjunto de datos que consulta la samples.nyctaxi.trips tabla. 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 en un día de semana o 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 configuradas con parámetros de widget estáticos. Para obtener instrucciones sobre cómo configurar un conjunto de datos con parámetros, consulte Adición de 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 agregar 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 con parámetros en la lista desplegable Conjunto de datos del panel de configuración.

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

    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 situado a la derecha del encabezado Parámetros y elija un parámetro en la lista desplegable.

  5. De manera predeterminada, 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. Revisar su panel.

    En la imagen siguiente se muestran dos widgets de visualización. Cada uno está configurado como histograma con un parámetro de widget estático. El gráfico de la izquierda muestra la distribución de las distancias de viaje para los viajes a partir de los 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 usar parámetros estáticos de nivel de widget, como se describe.

Comparación de datos mediante una condición de filtro

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

En el ejemplo siguiente se extiende la consulta anterior para incluir una condición de filtro donde el valor de parámetro especificado es All, que no aparece en los datos. La primera parte de la condición de filtro funciona igual que en el ejemplo anterior, filtrando los resultados donde day_type es Weekday o Weekend. La segunda parte de la condición de filtro comprueba si el propio parámetro está establecido en 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 pasa el filtro de forma eficaz 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 usar este conjunto de datos para configurar tres widgets de visualización, con el day_type_param establecido en All, Weekday y Weekend respectivamente. A continuación, los visores de paneles pueden comparar cada conjunto de datos filtrado por tipo de día con todo el conjunto de datos.

El siguiente GIF muestra cómo puede 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 laborable.
  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 previamente.
  5. Establezca el parámetro del nuevo gráfico en Todos para mostrar los recuentos totales de viajes por distancia para los viajes de fin de semana y día de semana.

Un gif como se describe en el texto anterior.

Mostrar parámetros en el panel

Agregar un filtro al lienzo del panel permite a los visores seleccionar y modificar valores de parámetro para explorar y analizar los datos de forma interactiva. Si no expone el parámetro en el panel, los visores solo ven los resultados de la consulta que usan el valor de parámetro predeterminado que estableció en la consulta.

Para agregar un parámetro al panel:

  1. Haga clic en Icono de filtro Agregar un filtro (campo/parámetro).
  2. Haga clic en icono de 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 panel, los widgets de visualización muestran un error que indica qué parámetro tiene valores contradictorios. Esto puede ocurrir cuando varios widgets de filtro usan 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.

Puede usar un patrón como el del ejemplo siguiente para establecer valores de reserva para parámetros diferentes 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 "Todo" 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 panel. Esta instrucción comprueba si hay un valor proporcionado como parámetro estático. Si no se establece ninguno, vuelve a un valor de parámetro de panel seleccionado por el visor.

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 panel frente a Parámetros de consulta de Mustache

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

Ejemplos de sintaxis

Entre los usos comunes de los parámetros se 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, consulte Ejemplos de sintaxis de parámetros con nombre

Importante

Permitir que los visores accedan a los datos a través de selecciones de parámetros, como nombres de tabla o catálogo, podría provocar 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.