Referencia de DataFusion SQL para Telemetry

Telemetry consulta tablas de eventos estructuradas con Apache DataFusion SQL. Las recetas públicas de Telemetry actualmente se planifican y ejecutan con Apache DataFusion 45.2.0 antes de su publicación. Esta referencia describe los patrones ejercidos por ese conjunto de pruebas anclado.

Los nombres y tipos de campos aún provienen de su contrato de evento. Adapte cada ejemplo a la tabla, unidades, estados, reglas de identidad y semántica de tiempo que su aplicación realmente utiliza.

Comience con una lectura limitada

Las consultas operativas normalmente deben comenzar con un filtro de hora UTC y devolver solo los campos necesarios para la pregunta:

SELECT
  route_template,
  status_code,
  latency_ms,
  timestamp_utc
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC
LIMIT 100;

timestamp_utc es la marca de tiempo de la consulta administrada por el servidor. Un campo timestamp proporcionado por el origen se normaliza durante la ingesta y no debe reemplazar la columna de consulta generada en las recetas.

Utilice un LIMIT mientras inspecciona filas sin procesar. Para una exportación completa, utilice Consulta asincrónica API en lugar de eliminar todas las salvaguardas de una consulta interactiva.

Crear grupos de tiempo completos

date_trunc crea una veta estable para una tendencia:

SELECT
  date_trunc('hour', timestamp_utc) AS hour,
  COUNT(*) AS requests
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY date_trunc('hour', timestamp_utc)
ORDER BY hour;

Es posible que la hora o el día más nuevos todavía se estén llenando. Excluya ese depósito de una alerta cuando un volumen parcial haga que el resultado sea engañoso. Utilice la misma zona horaria, tamaño de segmento y regla de integridad en cada comparación.

Recuentos condicionales y tasas seguras

Las expresiones condicionales CASE calculan varios resultados de las mismas filas agrupadas:

SELECT
  route_template,
  COUNT(*) AS requests,
  SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
  100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS error_rate_pct
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template
HAVING COUNT(*) >= 20
ORDER BY error_rate_pct DESC;

NULLIF protege la división desde un denominador cero. Multiplicar por 100.0 evita que la aritmética porcentual se convierta en una división de enteros. Un mínimo de HAVING evita que una falla en un grupo silencioso supere a una ruta ocupada con un impacto significativo.

Percentiles y distribuciones

Utilice approx_percentile_cont(latency_ms, 0.95) para obtener una estimación p95 eficiente:

SELECT
  route_template,
  approx_percentile_cont(latency_ms, 0.50) AS p50_ms,
  approx_percentile_cont(latency_ms, 0.95) AS p95_ms,
  approx_percentile_cont(latency_ms, 0.99) AS p99_ms
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template;

Compare p50 con p95 o p99. Un aumento similar en toda la distribución sugiere un flujo de trabajo generalmente más lento; un cambio de cola mayor apunta a un subconjunto de operaciones inusualmente lentas. Los percentiles son estimaciones, así que evite presentar una precisión decimal insignificante.

Para obtener un resultado similar a un histograma, utilice CASE para asignar un valor numérico a depósitos explícitos. Mantenga las etiquetas de los depósitos y las columnas de pedido separadas para que "1000+" no se clasifique antes que "250–499".

Los CTE hacen que las definiciones sean revisables

Las expresiones de tabla comunes separan una definición empresarial de la agregación final:

WITH account_activity AS (
  SELECT
    account_id,
    MIN(CASE WHEN event_name = 'signup_completed' THEN timestamp_utc END)
      AS signed_up_at,
    MIN(CASE WHEN event_name = 'activation_completed' THEN timestamp_utc END)
      AS activated_at
  FROM product_events
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
  GROUP BY account_id
)
SELECT
  COUNT(*) AS signed_up_accounts,
  SUM(CASE WHEN activated_at IS NOT NULL THEN 1 ELSE 0 END)
    AS activated_accounts
FROM account_activity
WHERE signed_up_at IS NOT NULL;

Inspeccionar un CTE intermedio seleccionándolo temporalmente. Esta suele ser la forma más rápida de detectar identidades duplicadas, valores nulos inesperados o una definición de hito que incluye filas incorrectas.

Las uniones necesitan un grano explícito

Antes de unir las tablas de eventos, indique qué representa una fila en cada lado. Una combinación de muchos a muchos puede multiplicar los recuentos y al mismo tiempo devolver un SQL válido.

Agregue previamente una fila por cuenta, solicitud, trabajo, entrega de webhook o período de facturación antes de unirse cuando esa sea la unidad de análisis. Utilice identificadores estables creados para la correlación y nunca se una a una etiqueta de visualización simplemente porque parece única.

Después de una unión, compare:

• recuento de filas antes y después
• recuento de identificadores distintos antes y después
• filas inigualables en ambos lados
• totales contra un encuentro con un resultado conocido

Funciones de ventana

Las funciones de ventana conservan los detalles de la fila o del depósito mientras comparan valores adyacentes:

WITH daily AS (
  SELECT
    date_trunc('day', timestamp_utc) AS day,
    COUNT(*) AS completed_jobs
  FROM job_events
  WHERE status = 'completed'
    AND timestamp_utc >= now() - INTERVAL '30 days'
  GROUP BY date_trunc('day', timestamp_utc)
)
SELECT
  day,
  completed_jobs,
  LAG(completed_jobs) OVER (ORDER BY day) AS previous_day_jobs,
  AVG(completed_jobs) OVER (
    ORDER BY day
    ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
  ) AS rolling_7_bucket_average
FROM daily
ORDER BY day;

LAG expone un valor anterior. Un AVG enmarcado crea una línea de base rodante. Las primeras filas tienen ventanas incompletas; decida si desea mostrarlos, suprimirlos o etiquetarlos antes de crear una alerta.

Campos anidados e identificadores

Telemetry expone JSON anidado a través de rutas de campo punteadas. Si es necesario citar una ruta de acceso con puntos en el esquema de tabla actual, utilice un identificador entre comillas dobles, como "data.tool.name". Lea Consultando JSON anidado e inspeccione el esquema de la tabla antes de copiar una consulta de campos anidados.

Utilice nombres de campo Snake_case y evite palabras reservadas o ambiguas al diseñar nuevos eventos. Si un campo existente requiere citas, cítelo de manera consistente en lugar de crear dos grafías del mismo concepto.

Patrones admitidos y límites fijados

El conjunto de recetas probado ejercita SELECT, CTE, uniones, CASE, agregados comunes, date_trunc, intervalos, percentiles aproximados, LAG, ventanas enmarcadas, NULLIF, COALESCE, ordenamiento, agrupación y límites.

DataFusion no es PostgreSQL, MySQL, BigQuery o Snowflake. Las funciones de apariencia similar pueden tener nombres o firmas diferentes. El planificador fijado utilizado por la auditoría de recetas de Telemetry no acepta todos los modificadores agregados o ayudantes de fecha que se encuentran en esos sistemas. Prefiera la sintaxis demostrada en esta referencia y el Biblioteca de recetas SQL probado, luego ejecute una pequeña consulta antes de adaptar un ejemplo de otro dialecto.

Lista de verificación de revisión de consultas

Antes de guardar una consulta o usarla en una alerta:

1. Confirme la tabla, las columnas, los tipos, las unidades y el rango de tiempo UTC.
2. Defina el actor o identificador del flujo de trabajo y verifique el detalle de la fila.
3. Decida cómo se comportan los reintentos, duplicados, eventos tardíos, nulos y depósitos incompletos.
4. Proteja los ratios con una verificación del denominador y un volumen mínimo significativo.
5. Inspeccione los CTE intermedios y los recuentos de filas unidas.
6. Pruebe casos sintéticos de éxito, fracaso, reintento, duplicación y límites.
7. Registre la definición, el propietario, el umbral y la respuesta esperada junto al resultado.

Cada receta incluye un esquema, SQL copiable, resultados sintéticos deterministas, una visualización, notas de interpretación, casos extremos, sugerencias de panel y guía de alertas. Lea Metodología de prueba SQL, luego comience con Fiabilidad API, análisis de productos, calidad de los datos o infraestructura.