warehouse_saved_queries

Report whether a query can be materialized incrementally, without running it.

Parses the SQL only, so it is cheap enough to call from the editor as the user types. Lets the editor explain why the incremental option is unavailable before anything is saved.

post/api/projects/{project_id}/warehouse_saved_queries/check_incremental/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/warehouse_saved_queries/check_incremental/
  • Auth: HTTP bearer

Path parameters

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

querystring required

The HogQL query to check.

incremental_keystring nullable

Output column whose advancing value marks rows as new. Omit to only list candidates.

unique_keystring[] nullable

Output columns that identify a row. Must include every GROUP BY column.

lookback_secondsinteger

How far back before the watermark to re-read each run, to pick up late-arriving data.

Response

eligibleboolean required

True when nothing blocks incremental materialization.

key_candidatesstring[] required

Output columns that could be used as the incremental key. Excludes aggregates, columns whose type cannot serve as an advancing watermark (strings, booleans, arrays), and for a union only includes columns every branch produces.

unique_key_candidatesstring[] required

Output columns the unique key may be built from. A superset of key_candidates: identifying a row only needs equality, so strings qualify here even though they cannot be the incremental key.

key_candidate_typesobject required

Coarse type per candidate, keyed by column name: datetime, date, integer, decimal, float, string, or uuid. A candidate with no entry has a type the check could not determine.

blockersstring[] required

Reasons this query cannot be incremental. Each names the construct responsible.

warningsstring[] required

Things that still work but are worth knowing, such as a filter that cannot be pushed down so each run reads as much data as a full refresh.

Changes

No recorded changes to this operation across all 1 revision of this API.