クエリ結果のエクスポート

コンパクトな対話型結果を得るには、同期クエリ 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 キーを取得し、その宛先資格情報を分離します。実稼働レポートを置き換える前に、行数、スキーマ、時間境界、NULL 率を検証します。

全文を見る クエリ API リファレンス, API エラー処理、そして データ保持に関するガイダンス.