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

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

このページの内容

いつ使用するか
最も役立つ列を最初に配置します
プルーニングを可能にするフィルター
避けるべきもの
ロールアウトのワークフロー
API を通じて構成します

パーティション列の選択

パーティション列では、Telemetry が要求された値を含めることができない部分をスキップできるようにすることで、選択的なクエリを大幅に高速化できます。これらは、大きなテーブル内の 1 つの顧客、サービス、環境、トレース、またはイベントタイプを繰り返し調査するエージェントや自動化されたワークフローに特に役立ちます。

SQL とは異なります PARTITION BY、クエリ結果は変わりません。 Telemetry は、データを書き込むときに構成された値をハッシュし、そのパーティション情報を各部分に記録します。クエリ時に、互換性のあるフィルターが同じ方法でハッシュされるため、データが読み取られる前に無関係な部分を除外できます。

いつ使用するか

これらがすべて当てはまる場合、テーブルをパーティション化します。

テーブルには十分なデータまたは部品があり、それをスキャンするのは重要な作業です
重要なクエリが同じフィールドで繰り返しフィルタリングされる
これらのフィルターは通常、テーブルのごく一部を選択します
フィールドは文字列、ブール値、または数値スカラーです

良い候補者には以下が含まれます： account_id, workspace_id, service, environment, event、および安定した入れ子になったフィールドなど request.region.

インシデントをアカウントごとに調査するエージェントの場合、 account_id 多くの場合、これは強力な最初の列になります。

SELECT timestamp_utc, event, message
FROM app_events
WHERE account_id = 'acct_123'
  AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC

時間述語は依然として時間枠を狭めます。さらに、アカウント述語により、Telemetry はそのウィンドウ内のパーティション化された部分をプルーニングできます。

最も役立つ列を最初に配置します

列の順序によって、先頭と接頭辞の階層が定義されます。与えられる:

{
  "partitionColumns": ["account_id", "event"]
}

Telemetry は、次の条件でフィルタリングするクエリに対してパーティションプルーニングを使用できます。

account_id
account_id そして event

このレイアウトは、次の基準のみでフィルタリングするクエリには使用できません。 event、最初の列が欠落しているためです。重要なクエリの最も広範なセットに対して最初の列を選択し、クエリが通常両方でフィルタリングされる場合にのみ別の列を追加します。

1 つの列から始めます。改善されるクエリパターンを説明できるようになってから 2 番目を追加してください。列リストが長いと、書き込みグループと圧縮グループがますます狭くなり、列が遅くなるとクエリの数が減ります。

プルーニングを可能にするフィルター

Telemetry は現在、リテラル等価、正の値からパーティションプルーニングを導出しています。 IN、そして IS NULL 結合された述語 AND:

WHERE account_id = 'acct_123'

WHERE account_id IN ('acct_123', 'acct_456')

WHERE account_id = 'acct_123'
  AND event IN ('request_failed', 'request_retried')

WHERE account_id IS NULL

範囲述語、否定、およびあいまい OR 式ではパーティションのプルーニングは行われません。たとえば、次のようにパーティション化します。 duration_ms 役に立たない duration_ms > 1000。クエリは依然として正しいです。最適化を行わずに単にスキャンするだけです。

ネストされたスカラーパスも機能します。

{
  "partitionColumns": ["request.region"]
}

SELECT count(*)
FROM app_events
WHERE request.region = 'us-west-2'

リスト、オブジェクト、およびタイムスタンプはパーティション列としてサポートされていません。タイムスタンプフィルタリングにはすでに独自のプルーニングパスがあり、通常はクエリ時間範囲としてより適切に表現されます。

避けるべきもの

すべてのイベントに存在するという理由だけでフィールドを選択することは避けてください。有用なパーティション列は、頻繁な選択的なクエリを反映します。

以下の点には注意してください。

ほとんどすべてのクエリが無視するフィールド
主に範囲を使用してクエリされるフィールド、 LIKE、または否定
クエリでほとんど繰り返されない場合の、急速に変化する値または無制限の値
先頭のプレフィックスが実際のクエリパターンと一致しない複数の列

カーディナリティの低いフィールドは、テーブルの大部分を削除する場合にも役立ちます。たとえば、次のようになります。 environment = 'production'。カーディナリティの高い識別子はポイント調査には優れていますが、書き込みや圧縮が断片化する可能性があります。単に最も異なる値を持つフィールドではなく、実際に関心のあるクエリ全体で最も多くのデータを削除するフィールドを優先します。

ロールアウトのワークフロー

人、ダッシュボード、アラート、エージェントによって実行されたクエリを検査します。最も高価な選択クエリによって共有される等価フィルターを特定します。
フィールドを確認して入力します GET /tables/<table>/schema.
テーブル設定UIまたはテーブル API.
重要なクエリの時間フィルターを保持します。パーティションプルーニングは、時間プルーニングを置き換えるのではなく補完します。
既存のデータが書き換えられるまでの時間が経過した後、代表的なクエリを再実行します。 1 回のウォームキャッシュ実行だけでなく、スキャンされた作業と遅延を比較します。
一般的なクエリが最初の列と 2 番目の列を一緒にフィルターする場合にのみ、2 番目の列を追加します。

新しいデータは、変更されたパーティション仕様をすぐに使用します。既存の部分はバックグラウンドで書き換えられ、書き換えられていない部分はクエリ可能なままであるため、移行中も結果は完全なままになります。新しいレイアウトを採用するテーブルが増えるにつれて、パフォーマンスが徐々に向上します。

API を通じて構成します

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

順序を変更するには、完全な希望リストを送信してください。パーティショニングをオフにするには、送信します null または空の配列:

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

API は、テーブルの現在のスキーマに対してフィールドを検証します。を参照してください。テーブル API リファレンス正確なリクエストとレスポンスのコントラクトを作成します。

所有権と技術リファレンス

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

編集基準を見直す

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