docs(api): Document query refresh more (#25278)

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"],

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

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(

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."
         ),
     )