Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(api): Document query refresh more #25278

Merged
merged 1 commit into from
Sep 30, 2024
Merged

docs(api): Document query refresh more #25278

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion frontend/src/queries/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
Expand Down
4 changes: 2 additions & 2 deletions frontend/src/queries/schema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 10 additions & 4 deletions posthog/api/insight.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.""",
)
]
Expand Down Expand Up @@ -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(
Expand Down
18 changes: 9 additions & 9 deletions posthog/schema.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
),
)

Expand Down
Loading