Exportación de resultados de consultas

Utilice la consulta síncrona API para obtener resultados interactivos compactos. Utilice una consulta asincrónica cuando el escaneo o el resultado sea demasiado grande para mantener abierta una solicitud HTTP, o cuando un sistema descendente necesite JSON o Parquet.

Primero, dé forma a la exportación

Exporte solo las columnas y el rango de tiempo que el consumidor necesita. Una consulta explícita y limitada es más fácil de revisar y es menos probable que exponga campos no relacionados:

SELECT
  date_trunc('day', timestamp_utc) AS day,
  feature,
  SUM(estimated_cost_usd) AS cost_usd
FROM llm_requests
WHERE timestamp_utc >= now() - INTERVAL '30 days'
GROUP BY date_trunc('day', timestamp_utc), feature
ORDER BY day, feature;

Prefiera Parquet cuando una herramienta de datos escanee un resultado escrito de gran tamaño. Prefiera JSON cuando un script o flujo de trabajo necesita un resultado más pequeño directamente.

Iniciar una consulta asincrónica

curl -X POST https://api.telemetry.sh/query/async \
  -H "Authorization: Bearer $TELEMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM api_requests WHERE timestamp_utc >= now() - INTERVAL '\''24 hours'\''",
    "format": "parquet"
  }'

La respuesta aceptada contiene un ID de trabajo y una URL de estado. Sondee la URL de estado con la misma clave API con capacidad de lectura hasta que el trabajo se complete o falle terminalmente. Retroceda entre encuestas en lugar de seguir un círculo cerrado.

Cuando esté completo, descargue el resultado de la URL devuelta antes de que caduque. Trate las URL de descarga y los archivos exportados según la sensibilidad de las columnas seleccionadas.

En consultas JSON, los resultados pequeños llegan directamente en result (data y key_order) dentro de la respuesta completada. Solo se necesita una URL de descarga si no hay resultado directo. Consulta ambos formatos en la referencia de la API de consultas.

Hacer que las exportaciones sean reproducibles

Almacene el SQL revisado, el formato de exportación, el cronograma, el propietario y el destino con la automatización. Utilice una ventana de tiempo de cierre fija para los informes programados para que los reintentos no exporten silenciosamente un período diferente.

Para la entrega incremental, defina una marca de agua y una política de superposición. Los eventos que llegan tarde pueden requerir una pequeña ventana de reprocesamiento y deduplicación posterior.

Proteger los sistemas posteriores

No exportes secretos ni contenido privado sin procesar. Asigne a la carga de trabajo de informes una clave read y aísle sus credenciales de destino. Valide el recuento de filas, el esquema, los límites de tiempo y las tasas nulas antes de reemplazar un informe de producción.

Vea los modelos Consultar referencia API, Manejo de errores API y guía de retención de datos completos.