From 62b456a33e3cb442c908c637149a742992e9cfc0 Mon Sep 17 00:00:00 2001 From: Michael Matloka Date: Mon, 30 Sep 2024 14:03:03 +0200 Subject: [PATCH] docs(api): Document query `refresh` param properly (#25254) --- frontend/src/queries/schema.json | 6 +++--- frontend/src/queries/schema.ts | 18 ++++++++++++------ posthog/api/insight.py | 10 ++++++++-- posthog/schema.py | 25 +++++++++++++++---------- 4 files changed, 38 insertions(+), 21 deletions(-) diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.json index b746021db6620..07c37533c020a 100644 --- a/frontend/src/queries/schema.json +++ b/frontend/src/queries/schema.json @@ -7451,8 +7451,6 @@ "properties": { "async": { "deprecated": "Use `refresh` instead.", - "description": "(Experimental) Whether to run the query asynchronously. Defaults to False. If True, the `id` of the query can be used to check the status and to cancel it.", - "examples": [true], "type": "boolean" }, "client_query_id": { @@ -7467,7 +7465,9 @@ "description": "Submit a JSON string representing a query for PostHog data analysis, for example a HogQL query.\n\nExample payload:\n\n```\n\n{\"query\": {\"kind\": \"HogQLQuery\", \"query\": \"select * from events limit 100\"}}\n\n```\n\nFor more details on HogQL queries, see the [PostHog HogQL documentation](/docs/hogql#api-access)." }, "refresh": { - "$ref": "#/definitions/RefreshType" + "$ref": "#/definitions/RefreshType", + "default": "blocking", + "description": "Whether to refresh the insight, how aggresively, and if sync or async:\n- `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache\n- `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache\n- `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache\n- `'force_blocking'` - calculate synchronously, even if fresh results are already cached\n- `'force_async'` - kick off background calculation, even if fresh results are already cached\n- `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates Background calculation can be tracked using the `query_status` response field." } }, "required": ["query"], diff --git a/frontend/src/queries/schema.ts b/frontend/src/queries/schema.ts index 920c653f948dd..ca670b7e8a6c7 100644 --- a/frontend/src/queries/schema.ts +++ b/frontend/src/queries/schema.ts @@ -1169,15 +1169,21 @@ export type RefreshType = export interface QueryRequest { /** Client provided query ID. Can be used to retrieve the status or cancel the query. */ client_query_id?: string + // Sync the `refresh` description here with the one in posthog/api/insight.py /** - * (Experimental) - * Whether to run the query asynchronously. Defaults to False. - * If True, the `id` of the query can be used to check the status and to cancel it. - * @example true - * @deprecated Use `refresh` instead. + * Whether to refresh the insight, how aggresively, and if sync or async: + * - `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache + * - `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache + * - `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache + * - `'force_blocking'` - calculate synchronously, even if fresh results are already cached + * - `'force_async'` - kick off background calculation, even if fresh results are already cached + * - `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates + * Background calculation can be tracked using the `query_status` response field. + * @default 'blocking' */ - async?: boolean refresh?: RefreshType + /** @deprecated Use `refresh` instead. */ + async?: boolean /** * Submit a JSON string representing a query for PostHog data analysis, * for example a HogQL query. diff --git a/posthog/api/insight.py b/posthog/api/insight.py index 1905a49ca8c2a..a9cc05987a495 100644 --- a/posthog/api/insight.py +++ b/posthog/api/insight.py @@ -809,9 +809,15 @@ def _filter_request(self, request: request.Request, queryset: QuerySet) -> Query name="refresh", enum=list(ExecutionMode), default=ExecutionMode.CACHE_ONLY_NEVER_CALCULATE, + # Sync the `refresh` description here with the one in frontend/src/queries/schema.ts description=""" -Whether to refresh the insight and how aggressively. (The default `force_cache` value never refreshes.) -If an `_async` mode is chosen, this request kicks off a background query and returns immediately. +Whether to refresh the insight, how aggresively, and if sync or async: +- `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache +- `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache +- `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache +- `'force_blocking'` - calculate synchronously, even if fresh results are already cached +- `'force_async'` - kick off background calculation, even if fresh results are already cached +- `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates Background calculation can be tracked using the `query_status` response field.""", ), OpenApiParameter( diff --git a/posthog/schema.py b/posthog/schema.py index 366d477a36cd6..04f62d3f62e26 100644 --- a/posthog/schema.py +++ b/posthog/schema.py @@ -5963,15 +5963,7 @@ class QueryRequest(BaseModel): model_config = ConfigDict( extra="forbid", ) - async_: Optional[bool] = Field( - default=None, - alias="async", - description=( - "(Experimental) Whether to run the query asynchronously. Defaults to False. If True, the `id` of the query" - " can be used to check the status and to cancel it." - ), - examples=[True], - ) + async_: Optional[bool] = Field(default=None, alias="async") client_query_id: Optional[str] = Field( default=None, description="Client provided query ID. Can be used to retrieve the status or cancel the query." ) @@ -6021,7 +6013,20 @@ class QueryRequest(BaseModel): ), discriminator="kind", ) - refresh: Optional[Union[bool, str]] = None + refresh: Optional[Union[bool, str]] = Field( + default="blocking", + description=( + "Whether to refresh the insight, how aggresively, and if sync or async:\n- `'blocking'` - calculate" + " synchronously (returning only when the query is done), UNLESS there are very fresh results in the" + " cache\n- `'async'` - kick off background calculation (returning immediately with a query status), UNLESS" + " there are very fresh results in the cache\n- `'lazy_async'` - kick off background calculation, UNLESS" + " there are somewhat fresh results in the cache\n- `'force_blocking'` - calculate synchronously, even if" + " fresh results are already cached\n- `'force_async'` - kick off background calculation, even if fresh" + " results are already cached\n- `'force_cache'` - return cached data or a cache miss; always completes" + " immediately as it never calculates Background calculation can be tracked using the `query_status`" + " response field." + ), + ) class QuerySchemaRoot(