From ca8fd1a79b69bc0e15107c792ab58df1009c6fa7 Mon Sep 17 00:00:00 2001 From: Michael Matloka Date: Mon, 30 Sep 2024 14:08:50 +0200 Subject: [PATCH] docs(api): Document query refresh more --- frontend/src/queries/schema.json | 2 +- frontend/src/queries/schema.ts | 4 ++-- posthog/api/insight.py | 14 ++++++++++---- posthog/schema.py | 18 +++++++++--------- 4 files changed, 22 insertions(+), 16 deletions(-) diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.json index 07c37533c020a..1c712e7052caa 100644 --- a/frontend/src/queries/schema.json +++ b/frontend/src/queries/schema.json @@ -7467,7 +7467,7 @@ "refresh": { "$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." + "description": "Whether results should be calculated sync or async, and how much to rely on the cache:\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 ca670b7e8a6c7..ca203854b035c 100644 --- a/frontend/src/queries/schema.ts +++ b/frontend/src/queries/schema.ts @@ -1169,9 +1169,9 @@ 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 + // Sync the `refresh` description here with the two instances in posthog/api/insight.py /** - * Whether to refresh the insight, how aggresively, and if sync or async: + * Whether results should be calculated sync or async, and how much to rely on the cache: * - `'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 diff --git a/posthog/api/insight.py b/posthog/api/insight.py index a9cc05987a495..793edcb105e15 100644 --- a/posthog/api/insight.py +++ b/posthog/api/insight.py @@ -643,9 +643,15 @@ def dashboard_tile_from_context(self, insight: Insight, dashboard: Optional[Dash name="refresh", enum=list(ExecutionMode), default=ExecutionMode.CACHE_ONLY_NEVER_CALCULATE, + # Sync the `refresh` description here with the other one in this file, and with frontend/src/queries/schema.ts description=""" -Whether to refresh the retrieved insights 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 retrieved insights, how aggresively, and if sync or async: +- `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates +- `'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 Background calculation can be tracked using the `query_status` response field.""", ) ] @@ -809,15 +815,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 + # Sync the `refresh` description here with the other one in this file, and with frontend/src/queries/schema.ts description=""" Whether to refresh the insight, how aggresively, and if sync or async: +- `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates - `'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 04f62d3f62e26..ff67c63b368d5 100644 --- a/posthog/schema.py +++ b/posthog/schema.py @@ -6016,15 +6016,15 @@ class QueryRequest(BaseModel): 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." + "Whether results should be calculated sync or async, and how much to rely on the cache:\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." ), )