Técnicas avanzadas para vistas de métricas

Las técnicas avanzadas para las vistas de métricas permiten expresar lógica de negocios compleja y reutilizar definiciones en la capa semántica. En esta página se explican dos técnicas de este tipo:

• Medidas de ventana: para cálculos de series temporales, como medias móviles, totales acumulados y cambios de un período a otro.
• Capacidad de composición: para crear medidas complejas haciendo referencia a otras medidas en lugar de volver a escribir su lógica.

En esta página se supone que está familiarizado con los conceptos del modelado de vistas métricas básicas. Consulte Vistas de métricas de modelo.

Medidas de Windows

Las medidas de Windows le permiten definir medidas con agregaciones ventana, acumulativas o semiaditivas en sus vistas de métricas. Admiten cálculos como medias móviles, cambios entre períodos y totales acumulados.

Puede agregar una medida de ventana en el editor del Explorador de catálogos o en YAML.

Adición de una medida de ventana en el editor

En la pestaña UI del editor de vistas de métricas, haga clic en + Ventana mientras edita una medida. + Ventana está disponible tanto en el modo Builder como en el modo Personalizado. Las opciones de ventana del editor corresponden a los campos YAML descritos en Definir una medida de ventana.

Para obtener más información sobre cómo crear y editar medidas, consulte Creación de una vista de métricas.

Definición de una medida de ventana

Una medida de ventana incluye los siguientes campos obligatorios:

• order: campo que determina la ordenación de la ventana.

• range: define la extensión de la ventana. Los valores admitidos incluyen current, cumulative, trailing, leading y all. Para obtener una sintaxis completa y descripciones, consulte Valores admitidosrange. Para obtener más información sobre los modificadores inclusive y exclusive de trailing y leading, consulte Incluir o excluir la fila de anclaje.

• semiaditivo: especifica cómo agregar la medida cuando el campo de orden no se incluye en la consulta.GROUP BY Valores posibles: first y last.

Una medida de ventana también admite el siguiente campo opcional:

• offset: desplaza el marco de ventana hacia atrás o hacia delante a lo largo del order campo por un intervalo fijo. Utilícelo para medidas de variación entre períodos, como intermensual o interanual. Para ver la sintaxis, las unidades admitidas y las restricciones, consulte Medidas de ventana.

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. Véase Pasar un tamaño de ventana como parámetro.

Cómo offset desplaza el marco de la ventana

Consulte Disponibilidad de características de la vista de métricas para conocer los requisitos mínimos de versión de proceso y especificación de YAML.

El campo range define la forma de la ventana en relación con la fila de anclaje, y offset desliza ese marco por el intervalo especificado a lo largo de order. La siguiente tabla muestra el marco para cada valor de range con y sin un offset de k, con respecto a la fila de anclaje t:

offset es independiente de semiadditive. La elección entre first y last sigue controlando cómo se contrae la medida cuando order no está en el GROUP BY de la consulta.

Para obtener los mejores resultados, haga coincidir offset con el grano natural de order. Para los datos mensuales, se prefiere offset: -12 month a offset: -365 day porque la aritmética de meses y años respeta los meses de duración variable y los años bisiestos, mientras que la aritmética de day no lo hace.

Incluir o excluir la fila de anclaje

Consulte Disponibilidad de características de la vista de métricas para conocer los requisitos mínimos de versión de proceso y especificación de YAML.

Para los intervalos trailing y leading, la palabra clave opcional inclusive o exclusive controlan si el valor de ventana de la fila de anclaje (por ejemplo, hoy) se incluye en la ventana móvil:

En el ejemplo siguiente se muestra cómo inclusive y exclusive afectan a la ventana móvil para la fecha de anclaje 2025-01-05 con trailing 3 day.

Supongamos que los datos subyacentes tienen una fila al día con los siguientes valores:

Cada modificador selecciona las filas correspondientes a tres días en relación con el punto de referencia y suma sus valores:

leading los intervalos siguen la misma lógica en la dirección opuesta.

Ejemplo de medida de ventana retrasada, móvil o adelantada

En el ejemplo siguiente se calcula un recuento gradual de 7 días de los clientes que han realizado pedidos. Esta métrica realiza un seguimiento de las tendencias de involucración de los clientes a lo largo del tiempo mostrando cuántos clientes distintos realizaron compras en la semana que lleva a cada fecha.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate

measures:
  - name: t7d_customers
    expr: COUNT(DISTINCT o_custkey)
    window:
      - order: date
        range: trailing 7 day
        semiadditive: last

En este ejemplo, se aplica la siguiente configuración:

• order: date especifica que el date campo ordena la ventana.
• range: trailing 7 day define la ventana como los 7 días anteriores a cada fecha, excepto la propia fecha.
• semiadditive: last devuelve el último valor de la ventana de 7 días cuando date no es una columna de agrupación.

CREATE OR REPLACE VIEW catalog.schema.rolling_customers WITH METRICS LANGUAGE YAML AS
$$
  version: 1.1

  source: samples.tpch.orders
  filter: o_orderdate > DATE'1998-01-01'

  fields:
    - name: date
      expr: o_orderdate

  measures:
    - name: t7d_customers
      expr: COUNT(DISTINCT o_custkey)
      window:
        - order: date
          range: trailing 7 day
          semiadditive: last
$$

Ejemplo de medida de ventana de período a período

En el ejemplo siguiente se calcula el crecimiento de las ventas diarias comparando los ingresos actuales (suma de todos los precios de pedido) con los ingresos de ayer. Esta métrica identifica las tendencias de ventas diarias y muestra el cambio porcentual en los ingresos.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
measures:
  - name: previous_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: trailing 1 day
        semiadditive: last
  - name: current_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: current
        semiadditive: last
  - name: day_over_day_growth
    expr: (MEASURE(current_day_sales) - MEASURE(previous_day_sales)) / MEASURE(previous_day_sales) * 100

En este ejemplo, se aplica la siguiente configuración:

• En el ejemplo se usan dos medidas de ventana: una para calcular las ventas totales en el día anterior y otra para el día actual.
• Una tercera medida calcula el cambio porcentual (crecimiento) entre los días actuales y anteriores.

Ejemplo de medida de ventana interanual con offset

El modificador offset es el elemento básico para las medidas de variación entre períodos. Defina una copia desplazada de una medida base y, a continuación, componga las dos para expresar deltas, ratios o tasas de crecimiento directamente en la vista métrica.

En el ejemplo siguiente se calcula el crecimiento de ventas año a año comparando las ventas de cada mes con el mismo mes del año anterior. La medida desplazada usa offset: -12 month para mirar hacia atrás 12 meses a lo largo del campo month.

version: 1.1
source: main.default.monthly_sales

fields:
  - name: month
    expr: month
  - name: category
    expr: category

measures:
  - name: monthly_sales
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last

  - name: monthly_sales_py
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last
        offset: -12 month

  - name: yoy_growth
    expr: MEASURE(monthly_sales) - MEASURE(monthly_sales_py)

  - name: yoy_growth_pct
    expr: (MEASURE(monthly_sales) - MEASURE(monthly_sales_py))
      / NULLIF(MEASURE(monthly_sales_py), 0)

En este ejemplo, se aplica la siguiente configuración:

• monthly_sales es la medida base, sumando las ventas del mes actual.
• monthly_sales_py es la misma medida desplazada 12 meses hacia atrás usando offset: -12 month. Para enero de 2025, devuelve el valor de enero de 2024.
• yoy_growth y yoy_growth_pct componen las dos medidas para expresar el cambio absoluto y porcentual. El uso NULLIF de evita errores de división por cero cuando el valor del año anterior es cero.

Ejemplo de medida total acumulada (en ejecución)

En el ejemplo siguiente se calculan los ingresos acumulados de ventas desde el principio del conjunto de datos hasta cada fecha. Este total en ejecución muestra cuánto ingresos totales se han generado con el tiempo, útiles para realizar un seguimiento del progreso hacia los objetivos de ingresos anuales o analizar patrones de crecimiento a largo plazo.

version: 1.1
source: samples.tpch.orders

filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: customer
    expr: o_custkey

measures:
  - name: running_total_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last

En este ejemplo, se aplica la siguiente configuración:

• order: date ordena cronológicamente la ventana.
• range: cumulative define la ventana como el conjunto de todos los datos desde el inicio del conjunto de datos hasta cada fecha, inclusive.
• semiadditive: last devuelve el valor acumulado más reciente cuando no se incluye date en el GROUP BY de la consulta, en lugar de sumar todos los valores de todas las fechas.

Ejemplo de medida de período hasta la fecha

En el ejemplo siguiente se calculan los ingresos de ventas de año a fecha (YTD). Esta medida muestra los ingresos acumulados generados desde el 1 de enero de cada año hasta la fecha actual, restableciéndose al principio de cada año nuevo.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1997-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)
measures:
  - name: ytd_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last
      - order: year
        range: current
        semiadditive: last

En este ejemplo, se aplica la siguiente configuración:

• En el ejemplo se usan dos especificaciones de ventana: una para la suma acumulativa en el date campo y otra para limitar la suma al current año.
• El year campo restringe la suma acumulativa para que se restablezca al principio de cada año nuevo.
• Los campos month y year forman una jerarquía de fechas en el campo date de pedido: cada uno se define en el campo date por su nombre, no en la columna subyacente o_orderdate, por lo que las consultas pueden agrupar esta medida según ellos. Consulte Agrupar por un campo de jerarquía de fechas.

Ejemplo de medida semiaditiva

En el ejemplo siguiente se calculan los saldos de la cuenta, que no se deben sumar entre fechas (no se puede agregar el saldo del lunes al saldo del martes para obtener el saldo total). En su lugar, al agregar en varios días, la medida devuelve el saldo más reciente. Sin embargo, la medida se puede seguir sumando entre los clientes para mostrar el saldo total de todas las cuentas en un día determinado.

version: 1.1

fields:
  - name: date
    expr: date
  - name: customer
    expr: customer_id

measures:
  - name: semiadditive_balance
    expr: SUM(balance)
    window:
      - order: date
        range: current
        semiadditive: last

En este ejemplo, se aplica la siguiente configuración:

• order: date ordena cronológicamente la ventana.
• range: current restringe la ventana a un solo día, sin agregación entre días.
• semiadditive: last devuelve el saldo más reciente cuando se agregan datos de varios días.

Consultar una medida de ventana

Puede consultar una vista de métricas con una medida de ventana como cualquier otra vista de métrica. Una medida de ventana se calcula a lo largo de su order campo, por lo que una consulta que divide los resultados a lo largo del tiempo debe hacer referencia a ese campo, ya sea directamente o a través de un campo de jerarquía de fechas definido en él. Cuando la consulta no hace referencia al campo order, la semiadditive palabra clave determina el valor devuelto, como se describe en el ejemplo de medida semiaditiva.

En el ejemplo siguiente se agrupa una medida de ventana por state y por una expresión de mes sobre el campo de ordenación date:

SELECT
   state,
   DATE_TRUNC('month', date),
   MEASURE(t7d_customers) as m
FROM my_metric_view
WHERE date >= DATE'2024-06-01'
GROUP BY ALL

Agrupar por un campo de jerarquía de fechas

Una jerarquía de fechas agrega el campo de orden a niveles de granularidad más amplios, como la semana, el mes o el año. Defina cada nivel como un campo sobre el campo de pedido por nombre, no sobre la columna de origen subyacente:

fields:
  - name: date
    expr: o_orderdate
  # Date hierarchy: each level is defined on the order field `date`,
  # not on the underlying o_orderdate column.
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)

La agrupación de una medida de ventana por un nivel de jerarquía devuelve la medida en ese intervalo de agregación. Suponiendo que el ejemplo de período hasta la fecha se crea como ytd_metric_view, tal como se muestra en el ejemplo de medida de período hasta la fecha, la siguiente consulta devuelve el valor acumulado en el año en la última fecha de cada mes:

SELECT month, MEASURE(ytd_sales) AS ytd_sales
FROM ytd_metric_view
GROUP BY month
ORDER BY month;

Capacidad de composición

Las vistas de métricas se pueden componer. Puede crear nuevos campos y medidas que hagan referencia a las existentes en lugar de volver a escribir lógica desde cero. Esto reduce la duplicación y facilita el mantenimiento de definiciones de métricas complejas.

La capacidad de composición funciona en dos niveles: dentro de una sola vista de métricas y entre distintas vistas de métricas cuando una vista de métricas se utiliza como fuente de otra.

La capacidad de composición admite los siguientes patrones de referencia:

• Campos anteriores en campos nuevos.
• Campos y medidas anteriores en nuevas medidas.
• Campos de vistas de métricas que se usan como origen en nuevos campos.
• Campos y medidas de vistas métricas utilizados como origen para nuevas medidas.

Definir medidas con capacidad de composición

En la sección measures, puede hacer referencia a medidas desde la vista de métricas de origen o las medidas definidas anteriormente en la misma vista de métricas. Este enfoque mejora la coherencia, la auditabilidad y el mantenimiento de la capa semántica.

Ejemplo: Valor medio de pedido (AOV)

En el ejemplo siguiente se define el valor medio del pedido (AOV) mediante dos medidas atómicas: total_revenue (suma de precios de pedido) y order_count (número de pedidos). La avg_order_value medida hace referencia a ambas medidas atómicas.

version: 1.1

source: samples.tpch.orders

measures:
  # Total Revenue
  - name: total_revenue
    expr: SUM(o_totalprice)

  # Order Count
  - name: order_count
    expr: COUNT(1)

  # Composed Measure: Average Order Value (AOV)
  - name: avg_order_value
    # Defines AOV as Total Revenue divided by Order Count
    expr: MEASURE(total_revenue) / MEASURE(order_count)

Si la total_revenue definición cambia (por ejemplo, para excluir impuestos), avg_order_value usa automáticamente la definición actualizada.

Composibilidad con lógica condicional

Puede usar la capacidad de composición para crear relaciones complejas, porcentajes condicionales y tasas de crecimiento sin depender de funciones de ventana para cálculos simples de período a período.

Ejemplo: Tasa de suministro

En el ejemplo siguiente se calcula la tasa de cumplimiento: el porcentaje de pedidos con estado 'F' (cumplido). La medida divide los pedidos cumplidos por total de pedidos.

version: 1.1

source: samples.tpch.orders

measures:
  # Total Orders (denominator)
  - name: total_orders
    expr: COUNT(1)

  # Fulfilled Orders (numerator)
  - name: fulfilled_orders
    expr: COUNT(1) FILTER (WHERE o_orderstatus = 'F')

  # Composed Measure: Fulfillment Rate (Ratio)
  - name: fulfillment_rate
    expr: MEASURE(fulfilled_orders) / MEASURE(total_orders)
    format:
      type: percentage

Procedimientos recomendados en cuanto a capacidad de composición

1. Definir primero medidas atómicas: establezca medidas fundamentales (SUM, COUNT, AVG) antes de definir medidas que hagan referencia a ellas.
2. Usar MEASURE() para referencias: use la función MEASURE() al hacer referencia a otra medida en un expr. No repita manualmente la lógica de agregación. Por ejemplo, evite SUM(a) / COUNT(b) si ya existen medidas para ambos valores.
3. Prioridad de legibilidad: componga medidas con fórmulas matemáticas claras. Por ejemplo, MEASURE(gross_profit) / MEASURE(total_revenue) es más claro que una única expresión SQL compleja.
4. Agregar metadatos semánticos: use metadatos semánticos para dar formato a medidas compuestas (por ejemplo, porcentajes o moneda) para herramientas de análisis posteriores. Consulte los metadatos del agente en las vistas de métricas.

Recursos adicionales

• Vistas de métricas del modelo
• Metadatos del agente en vistas de métricas
• Materialización de vistas de métricas
• Referencia de sintaxis de YAML de la vista de métricas