From 39267da8275798bc866f99dab5fb5f27ee0f30c5 Mon Sep 17 00:00:00 2001 From: Michael Matloka Date: Fri, 27 Sep 2024 10:58:43 +0200 Subject: [PATCH 1/3] docs(api): Document query `refresh` param properly --- frontend/src/queries/schema.json | 5 ++--- frontend/src/queries/schema.ts | 16 ++++++++++------ posthog/api/insight.py | 9 +++++++-- posthog/schema.py | 25 +++++++++++++++---------- 4 files changed, 34 insertions(+), 21 deletions(-) diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.json index b746021db6620..278b42339e5a8 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,8 @@ "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", + "description": "Whether to refresh the insight, how aggresively, and if sync or async. The default `force_cache` value never refreshes. Other possible values are:\n- 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there's very fresh data in the cache already\n- 'async' - kick off background calculation (returning immediately with a query status), UNLESS there's very fresh data in the cache already\n- 'force_blocking' - calculate synchronously (returning only when the query is done), even if there's very fresh data in the cache\n- 'force_async' - kick off background calculation (returning immediately with a query status), even if there's very fresh data in the cache\n- 'lazy_async' - only kick off background calculation if the data is visibly stale 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..7ded5032e6ff8 100644 --- a/frontend/src/queries/schema.ts +++ b/frontend/src/queries/schema.ts @@ -1170,14 +1170,18 @@ export interface QueryRequest { /** Client provided query ID. Can be used to retrieve the status or cancel the query. */ client_query_id?: string /** - * (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. The default `force_cache` value never refreshes. + * Other possible values are: + * - 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there's very fresh data in the cache already + * - 'async' - kick off background calculation (returning immediately with a query status), UNLESS there's very fresh data in the cache already + * - 'force_blocking' - calculate synchronously (returning only when the query is done), even if there's very fresh data in the cache + * - 'force_async' - kick off background calculation (returning immediately with a query status), even if there's very fresh data in the cache + * - 'lazy_async' - only kick off background calculation if the data is visibly stale + * Background calculation can be tracked using the `query_status` response field. */ - 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..556981383cd98 100644 --- a/posthog/api/insight.py +++ b/posthog/api/insight.py @@ -810,8 +810,13 @@ def _filter_request(self, request: request.Request, queryset: QuerySet) -> Query enum=list(ExecutionMode), default=ExecutionMode.CACHE_ONLY_NEVER_CALCULATE, 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. The default `force_cache` value never refreshes. +Other possible values are: +- 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there's very fresh data in the cache already +- 'async' - kick off background calculation (returning immediately with a query status), UNLESS there's very fresh data in the cache already +- 'force_blocking' - calculate synchronously (returning only when the query is done), even if there's very fresh data in the cache +- 'force_async' - kick off background calculation (returning immediately with a query status), even if there's very fresh data in the cache +- 'lazy_async' - only kick off background calculation if the data is visibly stale Background calculation can be tracked using the `query_status` response field.""", ), OpenApiParameter( diff --git a/posthog/schema.py b/posthog/schema.py index 366d477a36cd6..cac5bbfcea4fc 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=None, + description=( + "Whether to refresh the insight, how aggresively, and if sync or async. The default `force_cache` value" + " never refreshes. Other possible values are:\n- 'blocking' - calculate synchronously (returning only when" + " the query is done), UNLESS there's very fresh data in the cache already\n- 'async' - kick off background" + " calculation (returning immediately with a query status), UNLESS there's very fresh data in the cache" + " already\n- 'force_blocking' - calculate synchronously (returning only when the query is done), even if" + " there's very fresh data in the cache\n- 'force_async' - kick off background calculation (returning" + " immediately with a query status), even if there's very fresh data in the cache\n- 'lazy_async' - only" + " kick off background calculation if the data is visibly stale Background calculation can be tracked using" + " the `query_status` response field." + ), + ) class QuerySchemaRoot( From a147ec56accba10d23c1efca99f77b9bd0106fba Mon Sep 17 00:00:00 2001 From: Michael Matloka Date: Mon, 30 Sep 2024 09:24:04 +0200 Subject: [PATCH 2/3] Fix default refresh value for query --- frontend/src/queries/schema.ts | 16 +++++++++------- posthog/api/insight.py | 15 ++++++++------- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/frontend/src/queries/schema.ts b/frontend/src/queries/schema.ts index 7ded5032e6ff8..ca670b7e8a6c7 100644 --- a/frontend/src/queries/schema.ts +++ b/frontend/src/queries/schema.ts @@ -1169,15 +1169,17 @@ 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 /** - * Whether to refresh the insight, how aggresively, and if sync or async. The default `force_cache` value never refreshes. - * Other possible values are: - * - 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there's very fresh data in the cache already - * - 'async' - kick off background calculation (returning immediately with a query status), UNLESS there's very fresh data in the cache already - * - 'force_blocking' - calculate synchronously (returning only when the query is done), even if there's very fresh data in the cache - * - 'force_async' - kick off background calculation (returning immediately with a query status), even if there's very fresh data in the cache - * - 'lazy_async' - only kick off background calculation if the data is visibly stale + * 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' */ refresh?: RefreshType /** @deprecated Use `refresh` instead. */ diff --git a/posthog/api/insight.py b/posthog/api/insight.py index 556981383cd98..a9cc05987a495 100644 --- a/posthog/api/insight.py +++ b/posthog/api/insight.py @@ -809,14 +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, how aggresively, and if sync or async. The default `force_cache` value never refreshes. -Other possible values are: -- 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there's very fresh data in the cache already -- 'async' - kick off background calculation (returning immediately with a query status), UNLESS there's very fresh data in the cache already -- 'force_blocking' - calculate synchronously (returning only when the query is done), even if there's very fresh data in the cache -- 'force_async' - kick off background calculation (returning immediately with a query status), even if there's very fresh data in the cache -- 'lazy_async' - only kick off background calculation if the data is visibly stale +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( From 97cb63313afc908341e57548ce6fec2ff34f16ff Mon Sep 17 00:00:00 2001 From: Michael Matloka Date: Mon, 30 Sep 2024 10:31:15 +0200 Subject: [PATCH 3/3] Rebuild schema --- frontend/src/queries/schema.json | 3 ++- posthog/schema.py | 20 ++++++++++---------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.json index 278b42339e5a8..07c37533c020a 100644 --- a/frontend/src/queries/schema.json +++ b/frontend/src/queries/schema.json @@ -7466,7 +7466,8 @@ }, "refresh": { "$ref": "#/definitions/RefreshType", - "description": "Whether to refresh the insight, how aggresively, and if sync or async. The default `force_cache` value never refreshes. Other possible values are:\n- 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there's very fresh data in the cache already\n- 'async' - kick off background calculation (returning immediately with a query status), UNLESS there's very fresh data in the cache already\n- 'force_blocking' - calculate synchronously (returning only when the query is done), even if there's very fresh data in the cache\n- 'force_async' - kick off background calculation (returning immediately with a query status), even if there's very fresh data in the cache\n- 'lazy_async' - only kick off background calculation if the data is visibly stale Background calculation can be tracked using the `query_status` response 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." } }, "required": ["query"], diff --git a/posthog/schema.py b/posthog/schema.py index cac5bbfcea4fc..04f62d3f62e26 100644 --- a/posthog/schema.py +++ b/posthog/schema.py @@ -6014,17 +6014,17 @@ class QueryRequest(BaseModel): discriminator="kind", ) refresh: Optional[Union[bool, str]] = Field( - default=None, + default="blocking", description=( - "Whether to refresh the insight, how aggresively, and if sync or async. The default `force_cache` value" - " never refreshes. Other possible values are:\n- 'blocking' - calculate synchronously (returning only when" - " the query is done), UNLESS there's very fresh data in the cache already\n- 'async' - kick off background" - " calculation (returning immediately with a query status), UNLESS there's very fresh data in the cache" - " already\n- 'force_blocking' - calculate synchronously (returning only when the query is done), even if" - " there's very fresh data in the cache\n- 'force_async' - kick off background calculation (returning" - " immediately with a query status), even if there's very fresh data in the cache\n- 'lazy_async' - only" - " kick off background calculation if the data is visibly stale Background calculation can be tracked using" - " the `query_status` response field." + "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." ), )