Usa parámetros con vistas métricas

Los parámetros permiten pasar valores a una vista de métricas al consultarlos. Use parámetros para reutilizar una única definición de vista de métrica en distintas entradas, como una tasa de descuento o una ventana de fechas. Haga referencia a un parámetro en cualquier lugar donde una expresión SQL constante sea válida, como en filtros, expresiones de campo y medida, el origen y las combinaciones. También puedes usar un parámetro entero como valor de range o offset de una medida de ventana, para que quien realiza la llamada proporcione el tamaño de la ventana en tiempo de consulta. Pasa un valor como argumento al consultar la vista.

Los parámetros reducen la duplicación. En lugar de mantener una vista de métrica independiente para cada variante, defina la lógica una vez y deje que cada autor de la llamada proporcione sus propios valores. Un parámetro puede incluir un valor por defecto, por lo que los llamantes que no pasen un argumento utilizarán el valor por defecto.

Puede pasar valores de parámetro desde una consulta SQL o desde un panel de AI/BI. En un panel, conecte un parámetro a un widget de filtro para permitir que los visores elijan el valor en tiempo de ejecución. Consulte Uso de una consulta parametrizada en un panel.

Requisitos

  • Para crear una vista de métricas que defina parámetros, se necesitan los privilegios CREATE TABLE y USE SCHEMA en el esquema y el privilegio USE CATALOG en el catálogo principal. Para obtener la lista completa de privilegios necesarios para crear una vista de métrica, consulte Creación de una vista de métricas.
  • Para consultar una vista de métricas que defina parámetros, necesita un almacenamiento de SQL u otro recurso de proceso que ejecute Databricks Runtime 18.2 o superior. Para obtener más requisitos de versión, consulte Disponibilidad de características de la vista métrica.

Limitations

Las siguientes limitaciones se aplican a las vistas de métricas que definen parámetros:

  • No se puede materializar una vista de métrica que defina parámetros.
  • Los valores predeterminados tienen restricciones. Un valor predeterminado se debe convertir al tipo de datos declarado del parámetro y no puede hacer referencia a otro parámetro ni contener una subconsulta. Si establece un valor predeterminado para un parámetro, todos los parámetros siguientes también deben tener un valor predeterminado. Consulte Parámetros.

Definición de parámetros

Puede definir parámetros en el editor de código bajo del Explorador de catálogos o directamente en YAML. Después de crear un parámetro, haga referencia a él por nombre en cualquier lugar donde una expresión SQL constante sea válida, como en filtros, expresiones de campo y medida, el origen y las combinaciones. También puedes hacer referencia a un parámetro de tipo entero como valor de range o offset de una medida de ventana. Consulte Medidas de ventana.

Para definir parámetros en YAML, agregue un bloque de nivel parameters superior a la definición de la vista de métrica. Para obtener la referencia de campo completa y un ejemplo de YAML, consulte Parámetros.

En los pasos siguientes se usa el editor de código bajo del Explorador de catálogos y la samples.tpch.orders tabla, disponible en cada área de trabajo, para crear una vista de métricas con un discount parámetro y dos medidas. Una medida aplica el parámetro y la otra calcula el total sin recuento para poder comparar los dos.

Paso 1: Crear una vista de métricas

Cree una vista de métricas para albergar el parámetro y las medidas.

  1. Haga clic en el icono Datos.Catálogo en la barra lateral del área de trabajo y, a continuación, use la barra de búsqueda para buscar samples.tpch.orders y haga clic en el nombre de la tabla.
  2. Haga clic en Crear>vista métrica.
  3. En el cuadro de diálogo Crear vista de métricas , escriba un nombre y, a continuación, seleccione un catálogo y un esquema para crear la vista de métricas en. Haga clic en Crear.

El editor se abre en la pestaña interfaz de usuario . Para ver un tutorial completo del editor de vistas de métricas, consulte Creación de una vista de métricas.

Paso 2: Agregar un parámetro

Agregue un discount parámetro con un tipo numérico y un valor predeterminado.

  1. En el encabezado del editor, haga clic en Agregar parámetro.

  2. En el cuadro de diálogo Detalles del parámetro:

    1. Escriba discount como Nombre.
    2. Elija Numérico en la lista desplegable Tipo .
    3. Elija Double en la lista desplegable Tipo numérico que aparece.

    El botón Agregar parámetro y el cuadro de diálogo Detalles del parámetro con un parámetro de descuento establecido en Tipo numérico y Tipo numérico doble.

  3. Haga clic fuera del cuadro de diálogo para cerrarlo y, a continuación, escriba 0.15 como valor predeterminado para el descuento.

    Parámetro de descuento con un valor predeterminado de 0,15.

El parámetro aparece en el encabezado del editor después de crearlo. El valor establecido aquí es el valor predeterminado que se aplica cuando una consulta omite el argumento.

Paso 3: Agregar una medida que use el parámetro

Haga referencia al parámetro por nombre en una expresión de medida. Esta medida aplica el descuento a cada total del pedido.

  1. Haga clic en la pestaña Medidas cerca de la parte superior del editor.

  2. Haga clic en + Agregar.

  3. Escriba Discounted Sales como nombre de medida.

  4. Haga clic en Personalizado y escriba la expresión siguiente:

    SUM((1 - discount) * source.o_totalprice)

Paso 4: Agregar otra medida

Agregue una segunda medida para el total sin descuento.

  1. Haga clic en + Agregar.
  2. Escriba Total Sales como nombre de medida.
  3. En Generador, seleccione source.o_totalprice y la agregación Sum para generar SUM(source.o_totalprice).

Paso 5: Guardar la vista de métricas

Haz clic en Guardar. Para consultar la vista de métricas y pasar un valor para el discount parámetro, consulte Consulta de una vista de métricas con parámetros.

Consultar una vista de métricas con parámetros

Para consultar una vista de métrica que define parámetros, llame a la vista de métricas como una función con valores de tabla y pase parámetros como argumentos. Puede pasar argumentos por nombre o por posición, o omitirlos para usar los valores predeterminados.

Pasar argumentos por nombre

Para pasar un argumento mediante su nombre, utilice el operador =>. El siguiente ejemplo pasa un valor discount de 0.15:

SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(discount => 0.15)
GROUP BY product;

Pasar argumentos por posición

Para pasar argumentos por posición, enumere los valores en el orden en que se definen los parámetros. En el ejemplo siguiente se pasa el mismo valor de discount para 0.15:

SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(0.15)
GROUP BY product;

Uso de valores de parámetro predeterminados

Para usar los valores de parámetro predeterminados al llamar a la vista de métricas, omita argumentos. Las siguientes consultas son equivalentes y usan todos los valores predeterminados:

SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view() GROUP BY product;
SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view GROUP BY product;

Ver los parámetros que define una vista de métricas

Para ver los parámetros que define una vista de métrica, vea su definición de YAML, que incluye el parameters bloque . Consulte Ver definición y metadatos de la vista métrica.

Uso de una consulta parametrizada en un panel

Puede usar cualquiera de estas consultas para definir un conjunto de datos en un panel de INTELIGENCIA ARTIFICIAL o BI. Haga referencia a la vista de métricas en un conjunto de datos SQL y pase el parámetro como argumento en la llamada de función con valores de tabla. Para permitir que los visores del panel elijan el valor en tiempo de ejecución, pase un parámetro de panel al argumento y conéctelo a un widget de filtro. Consulte Pasar parámetros a una vista de métricas.

Recursos adicionales

  • Last updated on