本文へ移動
Telemetry
ドキュメントを見る

APIリファレンス更新日: 2026年7月25日3 最小読み取り時間

コーディング エージェントでこのドキュメントを使用してください

Claude Code、Codex、Cursor、または別のコーディング エージェント用の集中プロンプト パックを開き、それをここで説明するワークフローに適応させます。

このページの内容
  1. テーブルパス契約
  2. リストテーブル
  3. 例
  4. テーブルスキーマの取得
  5. 例
  6. テーブルの保持期間を設定する
  7. 例
  8. 明確な保持力
  9. パーティション列を設定する
  10. 例
  11. パーティショニングを無効にする
  12. テーブルの削除
  13. 例
  14. 関連するエンドポイント
  15. よくあるエラー

テーブル

テーブル API を使用すると、テーブルをプログラムで検査および管理できます。

サポートされている操作:

  • リストテーブル. GET https://api.telemetry.sh/tables
  • スキーマを取得します. GET https://api.telemetry.sh/tables/<table>/schema
  • 保存期間を設定します. PATCH https://api.telemetry.sh/tables/<table>/retention
  • パーティション列を設定します. PATCH https://api.telemetry.sh/tables/<table>/partition-columns
  • テーブルを削除します. DELETE https://api.telemetry.sh/tables/<table>

ヘッダー

名前 タイプ 説明
Content-Type 文字列 使用する application/json のために PATCH.
Authorization 文字列 API キー (生のキーまたは Bearer <key>.

スコープのルール:

  • GET /tables と GET /tables/<table>/schema には read または read-and-write が必要です
  • PATCH /tables/<table>/retention、PATCH /tables/<table>/partition-columns、DELETE /tables/<table> には read-and-write が必要です

テーブルパス契約

の <table> パス セグメントは転送前に API によって正規化されます。

  • スペースはアンダースコアに変換されます
  • 文字は小文字です
  • 正規化後は、小文字の ASCII 文字、数字、および _ 許可されています

例:

  • Uber Rides になる uber_rides
  • graphjson_egress 滞在します graphjson_egress
  • my-table 拒否される理由は - 許可されていません

予測可能な動作が必要な場合は、小文字、数字、アンダースコアのみを含む正規のテーブル名を使用してください。

リストテーブル

ゲット https://api.telemetry.sh/tables

サポートされているクエリパラメータ:

フィールド タイプ 必須 正確な契約 デフォルト
page 整数 いいえ 正の整数のページ番号。未満の値 1 拒否されます。 1
pageSize 整数 いいえ 正の整数のページ サイズ。より大きい値 100 に固定されている 100。 API は従来のエイリアスも受け入れます page_size. 50

成功したリクエストが返されます 200 OK:

{
  "status": "success",
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 3,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "tables": [
    "heartbeat",
    "telemetry_user_events",
    "graphjson_egress"
  ]
}

例

curl "https://api.telemetry.sh/tables?page=1&pageSize=25" \
  -H "Authorization: $API_KEY"

テーブルスキーマの取得

ゲット https://api.telemetry.sh/tables/<table>/schema

これは以下を返します:

  • テーブルの解析されたスキーマ オブジェクト
  • 現在の保持ポリシー (存在する場合)
  • パーティションメタデータ (存在する場合)

成功したリクエストが返されます 200 OK:

{
  "status": "success",
  "table": "graphjson_egress",
  "schema": {
    "fields": [
      {
        "name": "timestamp_utc",
        "data_type": {
          "Timestamp": ["Millisecond", "UTC"]
        },
        "nullable": true,
        "dict_id": 0,
        "dict_is_ordered": false,
        "metadata": {}
      }
    ],
    "metadata": {}
  },
  "retention_days": null,
  "partition_columns": null,
  "partition_spec_version": null
}

例

curl https://api.telemetry.sh/tables/graphjson_egress/schema \
  -H "Authorization: $API_KEY"

テーブルの保持期間を設定する

パッチ https://api.telemetry.sh/tables/<table>/retention

本体

フィールド タイプ 必須 正確な契約 例
retentionDays 整数または null いいえ データを保持する正の整数の日数。使用する null 保持をクリアしてデータを無期限に保持します。 API は従来のエイリアスも受け入れます retention_days. 30

注:

  • 未満の値 1 拒否されます。
  • 送ったら {} または {"retentionDays": null}、保持がクリアされます。

成功したリクエストが返されます 200 OK:

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": null,
  "partition_spec_version": null
}

例

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": 30
  }'

明確な保持力

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/retention \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "retentionDays": null
  }'

パーティション列を設定する

パッチ https://api.telemetry.sh/tables/<table>/partition-columns

パーティション列はテーブルの部分を編成するため、クエリがデータを読み取る前に等価フィルターで無関係なデータをスキップできます。順序は重要です。最も多くのクエリで使用されるフィールドを最初に置きます。参照 パーティション列の選択 選択のアドバイスとクエリの例については、

テーブルにはすでにスキーマが必要です。次のようなトップレベルまたはネストされたスカラー フィールドを使用できます。 account_id または request.region。文字列、ブール値、数値フィールドがサポートされています。

本体

フィールド タイプ 必須 正確な契約 例
partitionColumns 文字列の配列または null いいえ 順序付けされたフィールド名。名前は省略され、小文字になります。使用する null, []、または {} パーティショニングを無効にします。 API は、snake_case エイリアスも受け入れます partition_columns. ["account_id", "event"]

フィールドが現在のスキーマに存在しない場合、フィールドがサポートされていないタイプである場合、重複している場合、空である場合、または空のネストされたパス セグメントが含まれている場合、リクエストは拒否されます。

列を変更すると、新しいパーティション仕様が作成されます。新しく取り込まれたデータはそれをすぐに使用しますが、既存の部分はバックグラウンドで書き換えられます。その移行中もクエリは完了したままですが、書き換えが進むにつれてパフォーマンスのメリットが最大限に得られます。

成功したリクエストが返されます 200 OK 効果的な設定を使用すると、次のようになります。

{
  "status": "success",
  "table": "graphjson_egress",
  "retention_days": 30,
  "partition_columns": ["account_id", "event"],
  "partition_spec_version": 2
}

例

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": ["account_id", "event"]
  }'

パーティショニングを無効にする

curl -X PATCH https://api.telemetry.sh/tables/graphjson_egress/partition-columns \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "partitionColumns": null
  }'

テーブルの削除

削除 https://api.telemetry.sh/tables/<table>

これにより、テーブルとそのすべてのデータが完全に削除されます。

成功したリクエストが返されます 200 OK:

{
  "status": "success",
  "deleted_table": {
    "name": "graphjson_egress"
  }
}

例

curl -X DELETE https://api.telemetry.sh/tables/graphjson_egress \
  -H "Authorization: $API_KEY"

Telemetry も引き続きレガシーをサポートします DELETE /delete 行を削除するためのエンドポイント where 条項。テーブル全体のライフサイクル操作が必要な場合は、テーブル API を使用します。

よくあるエラー

  • 400 Bad Request 正規化後にテーブル名に無効な文字が含まれている場合
  • 400 Bad Request もし retentionDays が正の整数ではない、または null
  • 400 Bad Request パーティション列が無効であるか、現在のスキーマでサポートされているフィールドではない場合
  • 403 Forbidden API キーに要求された操作に対する権限がない場合
  • 401 Unauthorized API キーが見つからないか無効な場合
  • 404 Not Found テーブルが存在しない場合

関連機能

分析を形式化する前に、テーブル、フィールド、生の行を検査します。

ページの著者と参考資料

Telemetry 編集チームがこの説明を所有しています。製品チームは動作、例、境界をレビューします。

ドキュメントのレビュー方法