reviewing-warehouse-suggestions
Reviews PostHog's warehouse suggestions with a person and acts on them. Explains why a view should be materialized, unmaterialized, certified or deprecated using the numbers in the suggestion, changes a materialize suggestion's refresh mode, keys or interval when the person wants something else, then accepts, dismisses or assigns it. Use when the user asks what PostHog suggests for their data warehouse, whether to materialize a view, why a view should refresh incrementally or every few hours, or wants to accept, change, dismiss or assign a warehouse suggestion.
How do I install this agent skill?
npx skills add https://github.com/posthog/ai-plugin --skill reviewing-warehouse-suggestionsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides instructions for managing data warehouse optimizations within PostHog, such as materializing or deprecating views. No security issues were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Reviewing warehouse suggestions
PostHog computes warehouse suggestions every day from how the project reads its views and tables.
Each suggestion is about one view or table.
Its payload holds everything that accepting it would create or change.
1. Find the suggestions
Call warehouse-suggestions-list with status=proposed.
The results come in priority order, so start at the top.
If the list is empty, call warehouse-suggestions-status: it says whether suggestions are turned off, still collecting read history, or not eligible.
Call warehouse-suggestions-get for a suggestion the user wants to discuss.
Its evidence has the read counts behind it.
Suggestions on query responses
A query that reads a view can return its open suggestions without a separate call.
The /query response, execute-sql and the typed query tools carry them in warehouse_suggestions, on fresh runs only.
A cached result has none. To see them again, call warehouse-suggestions-list with status=proposed, which runs no query.
- Each item has
id,kind(materializeorunmaterialize),view_name,message,urlandcan_act. - Mention them to the person. Do not accept or dismiss one unless the person asks.
- To act on one, pass its
idtowarehouse-suggestions-get, then follow the steps below.
2. Explain it with its own numbers
Tell the user what accepting does and what it costs, using the payload fields. Do not invent a score or a confidence level.
- materialize: the view is computed often enough that storing its result saves compute.
- A view that is not stored is computed on every read, and again on every refresh of each materialized view that reads it.
recomputed_by_viewscounts those materialized views. When it is above 0, the saving comes mostly from their refreshes, not from people's reads. saves_seconds_per_monthandsaves_bytes_per_monthare what those computations stop costing.- Materializing adds a recurring refresh cost, which these numbers already subtract.
- A negative
saves_bytes_per_monthmeans its refreshes scan more than its reads do today. Name that cost to the user. - When
measurement_cappedis true, measuring the view hit the time limit. Every cost and saving is a lower bound, so say "at least", not "about". freshness_today_secondsandfreshness_after_secondssay how old the data can be now and after.refresh_interval_secondsis the proposed interval.refresh_interval_basissays what kept it from being shorter:source_sync(the sources sync no faster),fastest_schedule(PostHog refreshes views no more often),read_rate(people read the view no more often),consumer_refresh(the materialized views that read it refresh no more often) orsavings(a shorter interval costs more than it saves).refresh_modeisincrementalwhen each refresh can read only new rows, byincremental_key, and update rows byunique_key. Otherwise it isfull, and each refresh rebuilds the whole table.
- A view that is not stored is computed on every read, and again on every refresh of each materialized view that reads it.
- unmaterialize: this materialized view is read so rarely that refreshing it costs more than computing it on each read.
refresh_seconds_per_monthandrefresh_bytes_per_monthare what its refreshes cost now.live_seconds_per_monthandlive_bytes_per_monthestimate what its reads would cost if each one computed the view. The estimate uses a full refresh per read, so it leans high.read_secondsis how long one read would take afterwards. Nine in ten of its refreshes finished within this time. Tell the user that reads get slower by about this much, and that each read sees current data instead of the last refresh.- Accepting stops the refreshes and deletes the stored table. The view definition stays, so it can be materialized again later.
- A 409 on accept means the view changed since the suggestion was made, for example another view now reads from it. Explain the reason to the user and do not retry.
- certify: many people read this view or table, from several places. Use the read counts in
evidence. - deprecate: nobody read this view in the window.
- When
materializedis true, it still refreshes.refresh_seconds_per_monthandrefresh_bytes_per_monthare that cost. Whenmaterializedis false, it is a plain view and costs nothing to keep. It only adds clutter. - Accepting marks it deprecated in the data catalog. For a materialized view, it also stops the refreshes and deletes the stored table. The view definition stays, so it can be materialized again later. To keep it refreshing, pass
keep_materialized: true. After accepting,created_asset.stopped_materializationsays whether the refreshes stopped: they keep running when other views read from it or its refreshes feed person properties, a destination or a workflow. - To delete the view instead, pass
delete_view: true. Ask the user first, because a deleted view cannot be restored. A 409 means another view now reads from it, or it now feeds person properties, account properties, a destination or a workflow, or it now reads a direct-connection source. Explain the reason to the user and do not retry. A 400 ondelete_viewmeans some days in the read window have no read data. Offer to mark it deprecated instead.
- When
3. Change a materialize suggestion before accepting
The payload is a starting point. To change it, pass the payload field with the same name to the accept tool. An omitted field keeps the suggested value.
- Another interval: pass
refresh_interval_seconds. - Full instead of incremental, or the reverse: pass
refresh_mode. - Other keys:
- Read the view's query with
view-get. - Call
view-check-incrementalwith that query, plus theincremental_keyandunique_keythe user wants. Without keys it listskey_candidatesandunique_key_candidates. - Accept with those keys only when the check returns
eligible: true. Otherwise explain theblockersto the user.
- Read the view's query with
- Late rows: pass
lookback_secondsso each refresh reads that far back again.
PostHog proposes incremental only when it is certain of the keys.
A full suggestion can still refresh incrementally if the user chooses keys that pass the check.
The unique key must include every column the query groups by.
4. Accept or dismiss
Accept with warehouse-suggestions-accept-prepare, then warehouse-suggestions-accept-execute after the user types confirm.
The server checks every choice against the view's current query:
- A 400 names the field it refused and why. Show the reason to the user and ask what to change.
- A 409 means the view changed after the suggestion was made, so the suggested keys no longer apply. Offer a full refresh, or keys checked with
view-check-incremental.
Dismiss with warehouse-suggestions-dismiss and a reason (not_useful, not_now or other).
warehouse-suggestions-resume brings a dismissed suggestion back.
5. Hand it to someone else
A suggestion's assignee is the person who should decide it.
When a view's suggestion is first shown, PostHog assigns it to the person who created the view, if they can accept it.
To see one person's suggestions, pass assignee_id to warehouse-suggestions-list.
When the user is not the right person to decide, assign it with warehouse-suggestions-assign.
The user needs edit access to the view or table, the same as for dismissing it (can_act).
The assignee gets a notification.
They need edit access to the view or table, and to the data catalog for certify and deprecate suggestions.
A 400 means they do not have it. Tell the user and ask who else should get it.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/posthog/ai-plugin/reviewing-warehouse-suggestions">View reviewing-warehouse-suggestions on skillZs</a>