managing-endpoint-versions

エンドポイントのバージョン管理

このスキルは、エンドポイントのバージョン管理に関する実践ガイドです。現在のワークフローを取り上げます。このワークフローには、あらかじめ明確にしておくべき注意点がいくつかあります。

このスキルを使う場面

• 「v3 に戻すにはどうすればよいですか？」
• 「変更を公開前にテストしたいです」
• 「特定のバージョンの説明／data_freshness_seconds を更新するにはどうすればよいですか？」
• 「v5 に影響を与えずに v4 を無効にできますか？」
• クエリの変更によって新しいバージョンが作られるかどうか、ユーザーが判断に迷っている

バージョン管理の仕組み — 知っておくべきこと

動作	実際の動作
クエリの変更	新しいバージョンが自動的に作られます。 クエリに対する編集を保存すると、新しいバージョンが作成され、現在のバージョン番号が上がります
設定の変更（説明、data_freshness_seconds、マテリアライズ）	新しいバージョンは作成されません。対象のバージョンがその場で更新されます
「現在の」バージョン	常に最も大きいバージョン番号です。後ろ向きに移動できるポインターではありません
?version=N を指定せずに呼び出す	最新のバージョンが実行されます。そのため、バージョンを固定していない呼び出し元は常に最新のバージョンを使用します
エンドポイント全体を無効にする	endpoint-update に is_active: false を指定します（version なし）。すべてのバージョンが同時にオフラインになります
単一バージョンを無効にする	endpoint-update に version と is_active: false を指定します。他のバージョンに影響を与えず、1 つのバージョンを停止します

この仕組みでは、バージョンは前に進むだけです。現在、「v3 を再びデフォルトにする」操作はありません。実際には、「ロールバック」するには、古いクエリを再利用した新しい最上位バージョンを作成するか、呼び出し元のバージョンを ?version=N に固定する必要があります。

利用可能なツール

ツール	目的
endpoint-versions	エンドポイントの全バージョンを新しい順に一覧表示します
endpoint-get	設定全体を取得します。?version=N を指定すると特定のバージョンを取得できます
endpoint-update	主に使用するツールです。version の本文パラメーターを指定すると、特定のバージョンを対象にできます
endpoint-run	?version=N を使って特定のバージョンを実行します（他の呼び出し元が使用するバージョンには影響しません）

ワークフロー

公開前にドラフトをプレビューする

この仕組みには「ドラフト」という概念はありません。クエリを編集すると、すぐに新しいバージョンとして確定されます。安全にプレビューするには、次の手順に従ってください。

1. ライブエンドポイントではなく、まず execute-sql ツール（または SQL エディター）で新しいクエリをテストします
2. 準備ができたら、エンドポイントを更新します。新しいバージョンが自動的に作成されます
3. endpoint-run に ?version=N を指定して、新しいバージョンが期待どおりの結果を返すことを確認します
4. 既存の呼び出し元も最新のバージョン（この時点では新しいバージョン）を使用します。「段階的な公開」はできません

ユーザーが本当のステージング用エンドポイントを必要としている場合、現在可能な回避策は、末尾に _v2 または _staging を付けた兄弟エンドポイントを作成することだけです。プロダクト内にステージング用の手段はないことを、正確に説明してください。

古いバージョンへのロールバック

前方向のみのモデルでは、「ロールバック」するにはフォークが必要です。

1. endpoint-versions で適切なクエリがあるバージョンを見つけます（例：v3）。
2. ?version=3 を指定して endpoint-get を呼び出し、そのバージョンのクエリ JSON を取得します。
3. v3 のクエリを新しいクエリとして指定して endpoint-update を呼び出します。これにより、v3 と同じクエリを持つ新しいバージョン（例：v6）が作成されます。
4. ?version=N を指定していないすべての呼び出し元は、v6（＝v3 のクエリ）を使うようになります。

古いバージョン（v5、問題のあるバージョン）は引き続き存在し、明示的に無効化されるまで ?version=5 で呼び出せます。

すべての呼び出し元を変更できる場合は、より迅速な暫定措置として、正式な修正ができるまで ?version=3 に固定します。新しいバージョンを作成するより影響を抑えられます。

特定のバージョンの設定を更新する

endpoint-update は、リクエスト本文で version フィールドを受け付けます。これを設定すると、設定の更新はそのバージョンにのみ適用され、新しいバージョンは作成されません。次のような場合に便利です。

• 一部の呼び出し元が引き続き固定している古いバージョンの data_freshness_seconds を引き上げる
• わかりやすくするために、過去のバージョンの説明を調整する
• バージョンごとにマテリアライズの状態を変更する（いずれにしても、マテリアライズはバージョンごとに行われます）

重要：query と version を同時に渡すと拒否されます。クエリの変更では常に最上位の新しいバージョンが作成され、履歴は変更されません。version 引数が影響するのは設定のみです。

単一バージョンの無効化

v4 と v5 は呼び出し可能なまま、v3 をサービス対象外にするには、次のようにします。

endpoint-update {name: "...", version: 3, is_active: false}

これにより、v3 のみ is_active: false に設定されます。?version=3 に固定している呼び出し元はエラーを受け取るようになります。それ以外の呼び出し元には影響しません。

再度有効にするには、同じ呼び出しで is_active: true を指定します。

version を指定しないエンドポイント全体の is_active フィールドは、別の切り替え項目です。すべてのバージョンを一度に無効化します。対象を絞って停止するには、バージョンを指定する形式を使用してください。

未使用のバージョンを整理する

古いバージョンは時間とともに蓄積します。使われていないバージョンを見つけるには、endpoint-versions を呼び出して、各バージョンの last_executed_at を確認します。値が null のバージョンや、長期間更新されていないバージョンは、最近呼び出されていません。コストがかかるのは、マテリアライズされた未使用バージョンです。endpoint-update と version と is_materialized: false を指定してマテリアライズを無効にし、is_active: false に設定して廃止済みであることを示します。

バージョンを廃止する前に、ユーザーに確認してください。last_executed_at に記録されるのは個人用 API キーによる呼び出しのみで、追跡機能が追加されてからの実行に限られます（そのため、使用済みのバージョンでも null と表示されることがあります）。また、呼び出し元が ?version=N に固定されている可能性があります。監査の全手順については auditing-endpoints を参照してください。

対話の例

User: "I shipped a broken query last night, v5. How do I roll back?"

Agent:
- endpoint-versions <name> → v5 (latest), v4, v3, v2, v1
- endpoint-get <name> ?version=4 → query JSON for v4
- "Rolling back means creating v6 with v4's query. v5 stays as a
   historical version but nobody hits it unless they explicitly
   pass ?version=5. Sound right?"
- User confirms
- endpoint-update <name> {query: <v4 query>} → creates v6
- endpoint-run <name> ?version=6 to confirm shape
- "Done. v6 is live with v4's query. Want me to also deactivate v5
   so it's clear it's defunct?"
- User: "Yes"
- endpoint-update <name> {version: 5, is_active: false}

重要な注意事項

• ポインターの切り替えはありません。 「ロールバック」すると新しいバージョンが作成されます。バージョン番号は 常に増えていきます。その結果、履歴が煩雑になることをユーザーが懸念するのはもっともなことです。 その懸念を率直に伝えてください。
• クエリを変更すると、必ず新しいバージョンが作成されます。 設定を別途更新しても、新しいバージョンは作成されません。 v6 に上げずに v5 の説明の誤字を修正したい場合は、version パラメーターを使ってください。
• 特定のバージョンを無効にしても、そのバージョンだけがブロックされます。 デフォルトで実行されるバージョンは変わりません。 デフォルトで実行されるのは、常に最も大きいバージョン番号のものです。
• マテリアライズはバージョンごとに行われます。 各バージョンには {endpoint_name}_v{version} という名前の 専用のマテリアライズドビューがあります。あるバージョンのマテリアライズを無効にしても、他のバージョンには影響しません。
• ピン留めは安全策です。呼び出し元にはピン留めを促してください。 ?version=N にピン留めした呼び出し元は クエリの編集から影響を受けません。一方、ピン留めしていない呼び出し元は常に最新バージョンを使うため、新しいバージョンが 作成されると予期しない影響を受ける可能性があります。新しいバージョンを検証してから、意図的にピン留め先を更新するよう、 利用者に勧めてください。
• CLI でもバージョンを管理できます。 posthog-cli exp endpoints {pull,push,diff} を使うと、 エンドポイント定義を YAML としてバージョン管理システムに保存し、プッシュ前に変更をレビューできます。クエリの変更に レビューが必要な場合は、稼働中の環境を直接編集するよりも、こちらのほうがすっきりしたワークフローです。
• 古いバージョンを有効化する機能は、まだ提供されていません。 ユーザーが繰り返しこの操作を望む場合、 フォークではなくポインターを切り替えたいという要望として、機能の不足を率直に伝えてください。また、 agent-feedback を通じてチームにも知らせてください。endpoint-update で実現できるかのように装わないでください。