Solución de problemas de consultas SQL

Una consulta SQL puede fallar al ejecutarse, no devolver filas o producir un resultado plausible pero incorrecto. Trátelos como problemas diferentes. Comience con la lectura más pequeña que demuestre la tabla, el esquema y el rango de tiempo, luego restaure la lógica analítica paso a paso.

Telemetry utiliza Apache DataFusion SQL. Es posible que sea necesario reescribir la sintaxis copiada de PostgreSQL, BigQuery, Snowflake, MySQL u otro motor incluso cuando la idea analítica sea sólida.

1. Lea la clase de respuesta.

Para la Consulta síncrona API:

• 400 generalmente significa JSON no válido, SQL faltante, SQL incompatible, falta una tabla o campo o un error de tipo.
• 401 significa que la clave API falta o no es válida
• 403 significa que la clave carece de alcance de lectura
• 429 significa que la solicitud debe esperar y utilizar un retroceso limitado
• Es posible reintentar 5xx un número limitado de veces.

No vuelva a intentar modificar el SQL no válido. Capture el texto de error seguro, el punto final y el ID de solicitud, pero nunca registre la clave simplemente porque falló una consulta.

En consultas asíncronas, distingue queued, running, completed, failed y cancelled. Lee los resultados JSON pequeños directamente en result; descarga los resultados JSON grandes y Parquet desde download_url. Consulta Exportación de resultados.

2. Pruebe la tabla y el rango de tiempo.

Reemplace la consulta original con una muestra acotada:

SELECT *
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC
LIMIT 10;

Si esto no devuelve filas:

1. verificar el nombre de la tabla normalizada
2. ampliar el rango de hora UTC
3. eliminar filtros opcionales
4. inspeccionar filas de muestra recientes y el esquema en la vista de tabla
5. enviar un evento sintético con un identificador único

Si también falta la fila sintética, siga Solución de problemas de ingesta de eventos antes de editar más el SQL.

3. Compare nombres y tipos de campos

No infiera el nombre de una columna del código de la aplicación. Inspeccione el esquema de la tabla, incluidas las rutas de puntos anidadas y los tipos exactos.

Los errores comunes incluyen:

• consultando timestamp en lugar del timestamp_utc generado
• usando duration cuando el contrato de evento almacena duration_ms
• comparar un código de estado entero con una cadena
• tratar un identificador numérico como texto después de que un productor cambió el tipo
• hacer referencia a una ruta anidada sin el formulario de identificador requerido por el esquema almacenado
• agregar un campo que no es numérico

Comience con el campo exacto en un simple SELECT. Luego agregue una comparación, función o agregado. Esto identifica si el problema es la resolución de la columna o la operación aplicada a la columna.

4. Reducir la consulta por capas

Para una consulta con varios CTE, uniones y ventanas:

1. ejecutar el primer CTE por sí solo
2. agregue el siguiente CTE e inspeccione el grano de su fila.
3. Pruebe cada combinación con identificadores y recuentos de filas visibles.
4. agregue agregación después de que las filas unidas sean correctas
5. agregar cálculos de ventana al final

Utilice columnas de diagnóstico temporales como COUNT(*) y COUNT(DISTINCT account_id) para detectar la multiplicación de filas. Retírelos solo después de que se comprenda el grano del resultado.

5. Traducir la sintaxis de dialectos no admitidos

Utilice la sintaxis demostrada en DataFusion SQL Referencia y biblioteca de recetas probada. En particular:

• utilice SUM(CASE WHEN condition THEN 1 ELSE 0 END) para recuentos condicionales
• use approx_percentile_cont(latency_ms, 0.95) para aproximadamente p95
• use date_trunc('hour', timestamp_utc) para períodos de tiempo
• utilizar aritmética de intervalos como now() - INTERVAL '24 hours'
• proteger relaciones con NULLIF(denominator, 0)
• utilice LAG(value) OVER (ORDER BY bucket) para comparaciones de depósitos anteriores

Los nombres de funciones y las firmas son específicos del dialecto. Una función con el mismo propósito en otra base de datos no es evidencia de que DataFusion acepte esa ortografía.

6. Diagnosticar resultados vacíos

Un resultado vacío suele ser una interacción de filtro, no datos faltantes. Elimine los predicados uno a la vez:

SELECT
  environment,
  status,
  COUNT(*) AS events
FROM workflow_events
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY environment, status
ORDER BY events DESC;

Esto expone los valores realmente almacenados. Verifique mayúsculas de minúsculas, espacios en blanco, valores nulos, estados renombrados, límites del entorno y períodos recientes incompletos antes de restaurar un predicado limitado.

Para embudos y cohortes, confirme que cada hito utilice la misma unidad de identidad y que la ventana de observación sea lo suficientemente larga para que se produzcan pasos posteriores.

7. La auditoría se une antes que los totales.

Escribe lo que representa una fila en cada lado. Si ambos lados contienen varias filas por identificador, una unión directa puede multiplicar los ingresos, el recuento de eventos o los usuarios activos.

Agregue previamente cada lado al grano deseado:

WITH requests AS (
  SELECT
    request_id,
    MIN(timestamp_utc) AS requested_at
  FROM request_events
  GROUP BY request_id
),
outcomes AS (
  SELECT
    request_id,
    MAX(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS succeeded
  FROM outcome_events
  GROUP BY request_id
)
SELECT
  COUNT(*) AS requests,
  SUM(COALESCE(outcomes.succeeded, 0)) AS succeeded
FROM requests
LEFT JOIN outcomes ON requests.request_id = outcomes.request_id;

Compare distintos identificadores antes y después de la unión. Incluya filas no coincidentes deliberadamente en lugar de permitir que una combinación interna borre los resultados faltantes.

8. Validar tasas, percentiles y ventanas.

Una tasa requiere tanto numerador como denominador. Devuélvalos junto al porcentaje hasta que el cálculo sea confiable y establezca un volumen mínimo significativo antes de clasificar los grupos.

Un percentil debe utilizar un campo numérico con una unidad documentada. Compare p50 y p95 para comprender si cambió toda la distribución o solo su cola.

Las ventanas rodantes tienen menos observaciones al comienzo de la serie. Es posible que el período de tiempo más reciente esté incompleto. Etiquete o excluya ambas condiciones antes de alertar sobre una línea de base móvil.

9. Demuestre el resultado esperado con accesorios.

Crea un pequeño aparato sintético cuya respuesta se pueda calcular a mano:

• un éxito
• un fracaso permanente
• un fracaso que luego se recupera
• un identificador duplicado
• un campo opcional nulo
• un evento exactamente en un límite de tiempo

Ejecute CTE intermedios y compare las filas finales con la respuesta esperada. La planificación prueba la sintaxis y los tipos; Los accesorios ayudan a probar la interpretación.

Lista de verificación de revisión de consultas

• tabla exacta y esquema inspeccionados
• Se confirma la integridad de la ventana UTC y del depósito
• Los tipos de campo y las unidades coinciden con las operaciones.
• Grano de fila documentado antes de cada unión
• numerador, denominador y volumen mínimo visibles
• Los reintentos, duplicados, eventos tardíos y nulos tienen un comportamiento explícito.
• los casos límite sintéticos coinciden con el resultado esperado
• El resultado guardado incluye una definición, un propietario y una respuesta.

Telemetry publica la versión del motor y comprobaciones automatizadas en el Metodología de prueba SQL. Comience a partir de una receta en Fiabilidad API, trabajos de fondo, análisis de productos o calidad de los datos cuando necesite un patrón compatible conocido.