导出查询结果
使用同步查询 API 获得紧凑的交互结果。当扫描或结果太大而无法打开 HTTP 请求时，或者当下游系统需要 JSON 或 Parquet 时，请使用异步查询。
首先塑造出口
仅导出消费者需要的列和时间范围。有界的显式查询更容易审查，并且不太可能暴露不相关的字段：
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;
当数据工具将扫描大型键入结果时，首选 Parquet。当脚本或工作流程直接需要较小的结果时，首选 JSON。
启动异步查询
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"
}'
接受的响应包含作业 ID 和状态 URL。使用相同的可读 API 密钥轮询状态 URL，直到作业完成或最终失败。在民意调查之间退后一步，而不是进行紧密的循环。
完成后，在返回的 URL 过期之前下载结果。根据所选列的敏感度处理下载 URL 和导出的文件。
较小的 JSON 查询结果直接包含在完成响应的 result（data 和 key_order）中。只有没有直接返回结果时才需要下载 URL。两种响应格式请参阅查询 API 参考。
使出口可复制
通过自动化存储审阅的 SQL、导出格式、计划、所有者和目的地。对计划的报告使用固定的关闭时间窗口，这样重试就不会默默地导出不同的时间段。
对于增量交付，定义水印和重叠策略。迟到事件可能需要较小的重新处理窗口和下游重复数据删除。
保护下游系统
请勿导出秘密或原始私人内容。为报告工作负载提供 read 密钥并隔离其目标凭据。在替换生产报告之前验证行计数、架构、时间边界和空值率。