reviewing-warehouse-suggestions

ウェアハウスの提案を確認する

PostHog は、プロジェクトがビューやテーブルをどのように読み取るかに基づいて、毎日ウェアハウスの提案を計算します。 各提案は、1 つのビューまたはテーブルに関するものです。 その payload には、提案を承認した場合に作成または変更されるすべての内容が含まれます。

1. 提案を見つける

status=proposed を指定して warehouse-suggestions-list を呼び出します。 結果は優先度順に並んでいるため、先頭から確認してください。 リストが空の場合は、warehouse-suggestions-status を呼び出します。この結果から、提案が無効になっているのか、読み取り履歴の収集中なのか、あるいは対象外なのかがわかります。

ユーザーが相談したい提案について、warehouse-suggestions-get を呼び出します。 その evidence には、提案の根拠となる読み取り回数が含まれています。

2. 提案固有の数値を使って説明する

payload のフィールドを使って、承認するとどうなるか、どのようなコストがかかるかをユーザーに説明します。 スコアや信頼度をでっち上げないでください。

• materialize：ビューが十分な頻度で読み取られているため、結果を保存するとコンピューティングコストを節約できます。
  • saves_seconds_per_month と saves_bytes_per_month は、読み取りによって発生しなくなるコストです。
  • マテリアライズすると定期的なリフレッシュコストが加わりますが、この数値ではすでに差し引かれています。
  • freshness_today_seconds と freshness_after_seconds は、現在とマテリアライズ後にデータがどれだけ古くなり得るかを示します。
  • refresh_interval_seconds は、提案されている間隔です。refresh_interval_basis は、間隔をそれ以上短くできない理由を示します。source_sync（ソースの同期頻度がこれ以上速くない）、fastest_schedule（PostHog がビューをこれ以上頻繁にリフレッシュしない）、read_rate（ビューがこれ以上頻繁に読み取られない）、または savings（間隔を短くすると、節約できる量よりコストのほうが大きくなる）です。
  • refresh_mode は、各リフレッシュで incremental_key によって新しい行のみを読み取り、unique_key によって行を更新できる場合は incremental です。それ以外は full で、リフレッシュのたびにテーブル全体を再構築します。
• unmaterialize：このマテリアライズドビューはほとんど読み取られないため、リフレッシュのコストが、読み取りのたびに計算するコストを上回っています。
  • refresh_seconds_per_month と refresh_bytes_per_month は、現在リフレッシュにかかっているコストです。
  • live_seconds_per_month と live_bytes_per_month は、読み取りのたびにビューを計算する場合のコストの推定値です。この推定では読み取りごとに全件リフレッシュを行うため、実際より高めの値になります。
  • read_seconds は、変更後に 1 回の読み取りにかかる時間です。リフレッシュの 10 回中 9 回は、この時間内に完了しました。読み取りはこの程度遅くなる一方で、最後のリフレッシュ時点ではなく、最新のデータが読み取られることをユーザーに伝えてください。
  • 承認すると、リフレッシュが停止し、保存されたテーブルが削除されます。ビュー定義は残るため、後から再びマテリアライズできます。
  • 承認時に 409 が返された場合は、たとえば別のビューがこのビューから読み取るようになったなど、提案の作成後にビューが変更されています。ユーザーに理由を説明し、再試行しないでください。
• certify：複数の場所から多くの人がこのビューまたはテーブルを読み取っています。evidence の読み取り回数を使って説明してください。
• deprecate：このマテリアライズドビューは誰にも読み取られていませんが、リフレッシュは続いています。refresh_seconds_per_month と refresh_bytes_per_month は、そのコストです。承認すると、データカタログで非推奨としてマークされ、リフレッシュが停止し、保存されたテーブルが削除されます。ビュー定義は残るため、後から再びマテリアライズできます。リフレッシュを継続するには、keep_materialized: true を渡します。承認後、created_asset.stopped_materialization でリフレッシュが停止したかどうかを確認できます。他のビューがこのビューから読み取っている場合、またはリフレッシュ結果がユーザープロパティ、デスティネーション、もしくはワークフローに渡される場合は、リフレッシュは継続します。

3. 承認前にマテリアライズの提案を変更する

ペイロードは出発点となるものです。 変更するには、承認ツールに同名のペイロードフィールドを渡します。 省略したフィールドには、提案された値がそのまま使われます。

• 別の間隔：refresh_interval_seconds を渡します。
• インクリメンタルではなくフルにする、またはその逆：refresh_mode を渡します。
• その他のキー：
  1. view-get でビューのクエリを読み取ります。
  2. そのクエリに、ユーザーが指定したい incremental_key と unique_key を加えて view-check-incremental を呼び出します。 キーを指定しない場合は、key_candidates と unique_key_candidates が一覧表示されます。
  3. チェック結果が eligible: true の場合に限り、それらのキーを指定して承認します。それ以外の場合は、blockers の内容をユーザーに説明します。
• 遅れて到着する行：各更新でその分だけさかのぼって読み取るよう、lookback_seconds を渡します。

PostHog は、キーが確実な場合に限りインクリメンタルを提案します。 full の提案でも、チェックに合格するキーをユーザーが選べば、インクリメンタルに更新できます。 一意キーには、クエリでグループ化されるすべての列を含める必要があります。

4. 承認または却下する

warehouse-suggestions-accept-prepare で承認の準備を行い、ユーザーが confirm と入力した後に warehouse-suggestions-accept-execute を呼び出します。 サーバーは、ビューの現在のクエリに照らしてすべての選択内容をチェックします。

• 400 は、拒否されたフィールドとその理由を示します。理由をユーザーに伝え、何を変更するか確認します。
• 409 は、提案後にビューが変更されたため、提案されたキーが適用できなくなったことを意味します。フル更新を提案するか、view-check-incremental でチェックしたキーを提案します。

warehouse-suggestions-dismiss と理由（not_useful、not_now または other）を指定して、提案を却下します。 warehouse-suggestions-resume を使うと、却下した提案を再表示できます。