Parámetros de consulta

  • Artículo

Un parámetro de consulta permite sustituir valores en una consulta en tiempo de ejecución. Cualquier cadena entre llaves dobles {{ }} se trata como un parámetro de consulta. Aparece un widget encima del panel de resultados donde se establece el valor del parámetro. Los parámetros de consulta son más flexibles que los filtros de consulta y solo se deben usar en los casos en los que los filtros de consulta no son suficientes.

Agregar un parámetro de consulta

  1. Escriba Cmd + I. El parámetro se inserta en el símbolo de inserción de texto y aparece el cuadro de diálogo Agregar parámetro.
    • Palabra clave: palabra clave que representa el parámetro de la consulta.
    • Título: título que aparece sobre el widget. De manera predeterminada, el título es el mismo que la palabra clave.
    • Tipo: los tipos admitidos son Texto, Número, Fecha, Fecha y hora, Fecha y hora (con segundos), Lista desplegable y Lista desplegable basada en consulta. El valor predeterminado es texto.
  2. Escriba la palabra clave, invalide opcionalmente el título y seleccione el tipo de parámetro.
  3. Haga clic en Agregar parámetro.
  4. En el widget de parámetro, establezca el valor del parámetro.
  5. Haga clic en Aplicar cambios.
  6. Haga clic en Save(Guardar).

Como alternativa, escriba llaves dobles {{ }} y haga clic en el icono de engranaje cerca del widget de parámetros para editar la configuración.

Para volver a ejecutar la consulta con otro valor de parámetro, escriba el valor en el widget y haga clic en Aplicar cambios.

Edición de un parámetro de consulta

Para editar un parámetro, haga clic en el icono de engranaje situado junto al widget de parámetro. Para evitar que los usuarios que no poseen la consulta cambien el parámetro, haga clic en Mostrar solo resultados. Aparece el cuadro de diálogo del parámetro <Keyword>.

Eliminación de un parámetro de consulta

Para quitar un parámetro de consulta, elimine el parámetro de la consulta. El widget de parámetros desaparece y puede volver a escribir la consulta mediante valores estáticos.

Cambio del orden de los parámetros

Para cambiar el orden en que se muestran los parámetros, puede hacer clic en cada parámetro y arrastrarlo a la posición deseada.

Tipos de parámetros de consulta

Texto

Toma una cadena como entrada. Las barras diagonales inversas, las comillas simples y dobles se escapan, y Azure Databricks agrega comillas a este parámetro. Por ejemplo, una cadena como mr's Li"s se transforma en 'mr\'s Li\"s' Un ejemplo de uso de esto podría ser

SELECT * FROM users WHERE name={{ text_param }}

Number

Toma un número como entrada. Un ejemplo de uso de esto podría ser

SELECT * FROM users WHERE age={{ number_param }}

Para restringir el ámbito de los posibles valores de parámetro al ejecutar una consulta, usa el tipo de parámetro Lista desplegable. Un ejemplo sería SELECT * FROM users WHERE name='{{ dropdown_param }}'. Cuando se selecciona en el panel de configuración de parámetros, aparece un cuadro de texto donde se especifican los valores permitidos, cada valor separado por una nueva línea. Las listas desplegables son parámetros de texto. Para usar fechas o fechas y horas en la lista desplegable, escríbelas en el formato que requiere el origen de datos. No se aplica escape a las cadenas. Puede elegir entre un único valor o una lista desplegable de varios valores.

  • Valor único: se requieren comillas simples alrededor del parámetro.
  • Varios valores: alterne la opción Permitir varios valores. En la lista desplegable Comillas, elija si desea dejar los parámetros como especificados (sin comillas) o ajustar los parámetros con comillas simples o dobles. No es necesario agregar comillas alrededor del parámetro si elige comillas.

Cambie la cláusula WHERE para usar la palabra clave IN en la consulta.

SELECT ...
FROM   ...
WHERE field IN ( {{ Multi Select Parameter }} )

El widget de selección múltiple de parámetros permite pasar varios valores a la base de datos. Si seleccionas la opción Comillas dobles para el parámetro Cotización, la consulta reflejará el siguiente formato: WHERE IN ("value1", "value2", "value3")

Lista desplegable basada en consultas

Toma el resultado de una consulta como entrada. Tiene el mismo comportamiento que el parámetro Lista desplegable. Debe guardar la consulta de lista desplegable de Databricks SQL para usarla como entrada en otra consulta.

  1. Haga clic en Lista desplegable basada en consulta en Tipo en el panel de configuración.
  2. Haga clic en el campo Consulta y seleccione una consulta. Si la consulta de destino devuelve un gran número de registros, el rendimiento se resiente.

Si la consulta de destino devuelve más de una columna, Databricks SQL usa la primera. Si la consulta de destino devuelve columnas name y value, Databricks SQL rellena el widget de selección de parámetros con la columna name, pero ejecuta la consulta con el value asociado.

Por ejemplo, supongamos que la consulta siguiente devuelve los datos de la tabla.

SELECT user_uuid AS 'value', username AS 'name'
FROM users
value name
1001 John Smith
1002 Jane Doe
1003 Bobby Tables

Cuando Azure Databricks ejecuta la consulta, el valor pasado a la base de datos sería 1001, 1002 o 1003.

Fecha y hora

Azure Databricks tiene varias opciones para parametrizar los valores de fecha y marca de tiempo, incluidas las opciones para simplificar la parametrización de intervalos de tiempo. Selecciona entre tres opciones de precisión variable:

Opción Precision Tipo
Date day DATE
Fecha y hora minute TIMESTAMP
Fecha y hora (con segundos) second TIMESTAMP

Al elegir una opción del parámetro Range, se crean dos parámetros designados por los sufijos .start y .end. Todas las opciones pasan parámetros a la consulta como literales de cadena; Azure Databricks requiere que ajuste los valores de fecha y hora entre comillas simples ('). Por ejemplo:

-- Date parameter
SELECT *
FROM usage_logs
WHERE date = '{{ date_param }}'

-- Date and Time Range parameter
SELECT *
FROM usage_logs
WHERE modified_time > '{{ date_range.start }}' and modified_time < '{{ date_range.end }}'

Los parámetros de fecha usan una interfaz de selección de calendario y pueden tener como valor predeterminado la fecha y hora actuales.

Nota:

El parámetro Date Range solo devuelve los resultados correctos para las columnas de tipo DATE. Para las columnas TIMESTAMP, use una de las opciones de Intervalo de fecha y hora.

Valores dinámicos de fecha e intervalo de fechas

Al agregar un parámetro de fecha o intervalo de fechas a la consulta, el widget de selección muestra un icono de rayo azul. Haga clic en él para mostrar valores dinámicos como today, yesterday, this week, last week, last month o last year. Estos valores se actualizan de forma dinámica.

Importante

Las fechas y los intervalos de fechas dinámicos no son compatibles con las consultas programadas.

Uso de parámetros de consulta en paneles

Opcionalmente, las consultas pueden usar parámetros o valores estáticos. Cuando se agrega una visualización basada en una consulta con parámetros a un panel, la visualización se puede configurar para usar una de las siguientes opciones:

  • Parámetro de widget

    Los parámetros de widget son específicos de una única visualización en un panel, aparecen en el panel de visualización y los valores de los parámetros especificados solo se aplican a la consulta subyacente a la visualización.

  • Parámetro de panel

    Los parámetros del panel se pueden aplicar a varias visualizaciones. Al agregar una visualización basada en una consulta con parámetros a un panel, el parámetro se agregará como parámetro de panel de forma predeterminada. Los parámetros del panel se configuran para una o varias visualizaciones en un panel y aparecen en la parte superior del panel. Los valores de parámetro especificados para un parámetro de panel se aplican a las visualizaciones que reutilizan ese parámetro de panel determinado. Un panel puede tener varios parámetros, cada uno de los cuales puede aplicarse a algunas visualizaciones y no a otras.

  • Valor estático

    Los valores estáticos se usan en lugar de un parámetro que responde a los cambios. Los valores estáticos permiten codificar de forma rígida un valor en lugar de un parámetro y harán que el parámetro "desaparezca" del panel o widget donde aparecía anteriormente.

Al agregar una visualización que contiene una consulta parametrizada, puede elegir el título y el origen del parámetro en la consulta de visualización si hace clic en el icono de lápiz adecuado . También puede seleccionar la palabra clave y un valor predeterminado. Consulte Propiedades de parámetro.

Después de agregar una visualización a un tablero, acceda a la interfaz de asignación de parámetros haciendo clic en los puntos suspensivos verticales en la parte superior derecha de un widget de tablero y, luego, haciendo clic en Cambiar la configuración del widget.

Propiedades del parámetro

  • Título: nombre para mostrar que aparece junto al selector de valores en el panel. El valor predeterminado es el parámetro Palabra clave. Para editarlo, haga clic en el icono de lápiz Pencil Icon. Los títulos de los parámetros estáticos del panel no aparecen porque el selector de valores está oculto. Si selecciona Valor estático como Origen del valor, el campo Título aparece atenuado.

  • Palabra clave: literal de cadena de este parámetro en la consulta subyacente. Esto resulta útil para depurar si el panel no devuelve los resultados esperados.

  • Valor predeterminado: valor usado si no se especifica ningún otro. Para cambiar esto desde la pantalla de consulta, ejecute la consulta con el valor de parámetro deseado y haga clic en el botón Guardar.

  • Origen del valor: origen del valor del parámetro. Haga clic en el icono de lápiz Pencil Icon para elegir un origen.

    • Nuevo parámetro de panel: cree un nuevo parámetro de nivel de panel. Esto le permite establecer un valor de parámetro en un solo lugar en el panel y asignarlo a varias visualizaciones.
    • Parámetro de panel existente: asigne el parámetro a un parámetro de panel existente. Debe especificar qué parámetro de panel ya existente.
    • Parámetro de widget: muestra un selector de valores dentro del widget de panel. Esto es útil para parámetros únicos que no se comparten entre widgets.
    • Valor estático: elija un valor estático para el widget, independientemente de los valores usados en otros widgets. Los valores de parámetro asignados estáticamente no muestran un selector de valores en ningún lugar del panel, que es más compacto. Esto le permite aprovechar la flexibilidad de los parámetros de consulta sin abarrotar la interfaz de usuario en un panel si no se espera que determinados parámetros cambien con frecuencia.

    Change parameter mapping

Preguntas más frecuentes

¿Puedo reutilizar el mismo parámetro varias veces en una sola consulta?

Sí. Use el mismo identificador entre llaves. En este ejemplo se usa el parámetro {{org_id}} dos veces.

SELECT {{org_id}}, count(0)
FROM queries
WHERE org_id = {{org_id}}

¿Puedo usar varios parámetros en una sola consulta?

Sí. Use un nombre único para cada parámetro. En este ejemplo se usan dos parámetros: {{org_id}} y {{start_date}}.

SELECT count(0)
FROM queries
WHERE org_id = {{org_id}} AND created_at > '{{start_date}}'