Uso de parámetros del panel

Los parámetros del panel son una manera de hacer que los paneles sean interactivos, permitiendo a los visores usar selectores de valores únicos y selectores de fechas para introducir valores específicos en consultas de conjuntos de datos en tiempo de ejecución. Por ejemplo, los parámetros pueden filtrar los datos en función de criterios, como fechas y categorías de productos, antes de que se agreguen en una consulta SQL, permitiendo realizar consultas y análisis precisos más eficaces.

Los parámetros se agregan a los conjuntos de datos y se conectan a uno o varios widgets en el lienzo de un panel mediante un creador o editor del panel. Los visores de paneles interactúan con los datos del panel seleccionando valores en widgets de filtro en tiempo de ejecución. Esto vuelve a ejecutar las consultas asociadas y presenta visualizaciones basadas en los datos filtrados.

Los parámetros modifican directamente la consulta, que puede ser eficaz. Los filtros 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 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.

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

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.

Eliminación de un parámetro de consulta

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

Mostrar parámetros en el panel

Agregar un filtro al lienzo del panel permite a los visores seleccionar y modificar valores de parámetros, para que puedan 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 Agregar un filtro (campo/parámetro).
2. Haga clic en , 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.

Incluir parámetros en la dirección URL

La configuración de los parámetros se almacena en la dirección URL, lo que permite a los usuarios marcarla para mantener su estado del panel, incluyendo los filtros y parámetros preestablecidos, o compartirla con otros usuarios para tener una aplicación coherente con los mismos filtros y parámetros.

Ejemplos de sintaxis de parámetros

En los ejemplos siguientes se muestran algunos casos de uso comunes para los parámetros.

Inserción de una fecha

En el ejemplo siguiente se incluye un parámetro Date que limita los resultados de la consulta a los registros después de una fecha específica.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY
  1,
  2

Inserción de un número

En el ejemplo siguiente se incluye un parámetro Numeric que limita los resultados a los registros en los que el campo o_total_price es mayor que el valor del parámetro proporcionado.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

Inserción de un nombre de campo

En el ejemplo siguiente, field_param se usa con la función IDENTIFIER para proporcionar un valor de umbral para la consulta en tiempo de ejecución. El valor del parámetro debe ser un nombre de columna de la tabla utilizada en la consulta.

SELECT
  *
FROM
  samples.tpch.orders
WHERE
  IDENTIFIER(:field_param) < 10000

Inserción de objetos de base de datos

En el ejemplo siguiente se crean tres parámetros: catalog, schema y table. Los visores de paneles pueden usar widgets de filtro en el lienzo para seleccionar valores de parámetro.

SELECT
  *
FROM
  IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

Consulte Cláusula IDENTIFICADOR.

Importante

Permitir que los visores de paneles 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.

Concatenación de varios parámetros

Puede incluir parámetros en otras funciones SQL. Este ejemplo permite al visor seleccionar un título de empleado y un identificador numérico. La consulta usa la función format_string para concatenar las dos cadenas y filtrar por las filas que coinciden. Consulte la Función format_string.

SELECT
  o_orderkey,
  o_clerk
FROM
  samples.tpch.orders
WHERE
  o_clerk LIKE format_string('%s%s', :title, :emp_number)

Parámetros del panel frente a Parámetros de consulta SQL de Databricks

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 SQL de Databricks.