diff --git a/docs/ResultsApi.md b/docs/ResultsApi.md index 8949dee..4c653d4 100644 --- a/docs/ResultsApi.md +++ b/docs/ResultsApi.md @@ -9,11 +9,23 @@ Method | HTTP request | Description # **get_result** -> GetResultResponse get_result(id) +> GetResultResponse get_result(id, offset=offset, limit=limit, format=format) Get result -Retrieve a persisted query result by ID. If the result is still being processed, only the status is returned. Once ready, the full column and row data is included in the response. +Retrieve a persisted query result by ID. The response format for the `ready` state is selected by `Accept` header or `?format=` query param; non-ready states use the same status codes and JSON body shape regardless of format. + +| Result status | Status × body | +|-----------------------|------------------------------------------------------------------------------| +| `ready` + JSON | 200 `application/json` — `GetResultResponse` with `columns`, `rows`, etc. | +| `ready` + Arrow | 200 `application/vnd.apache.arrow.stream` — schema, RecordBatches, EOS | +| `pending`/`processing`| 202 `application/json` `{status, result_id}` + `Retry-After` | +| `failed` | 409 `application/json` `{status, result_id, error_message}` | +| not found | 404 `application/json` (`ApiErrorResponse`) | + +`?format=arrow` (or `?format=json`) takes precedence over `Accept`. Use `?offset=N&limit=M` to slice the result; `offset` defaults to 0 and `limit` is unbounded by default. Both must be non-negative; invalid values return 400. When a finite `limit` doesn't reach the end of the result, a `Link` header with `rel="next"` points at the following page. + +Ready responses (both formats) carry `X-Total-Row-Count` (full result row count from parquet metadata, independent of offset/limit). The Arrow path streams end-to-end with no spawned task between the parquet reader and the wire — clients can disconnect at any time and the server stops reading. ### Example @@ -60,10 +72,13 @@ with hotdata.ApiClient(configuration) as api_client: # Create an instance of the API class api_instance = hotdata.ResultsApi(api_client) id = 'id_example' # str | Result ID + offset = 56 # int | Rows to skip (default: 0) (optional) + limit = 56 # int | Maximum rows to return (default: unbounded) (optional) + format = 'format_example' # str | `arrow` or `json` — overrides the `Accept` header. (optional) try: # Get result - api_response = api_instance.get_result(id) + api_response = api_instance.get_result(id, offset=offset, limit=limit, format=format) print("The response of ResultsApi->get_result:\n") pprint(api_response) except Exception as e: @@ -78,6 +93,9 @@ with hotdata.ApiClient(configuration) as api_client: Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **id** | **str**| Result ID | + **offset** | **int**| Rows to skip (default: 0) | [optional] + **limit** | **int**| Maximum rows to return (default: unbounded) | [optional] + **format** | **str**| `arrow` or `json` — overrides the `Accept` header. | [optional] ### Return type @@ -90,14 +108,17 @@ Name | Type | Description | Notes ### HTTP request headers - **Content-Type**: Not defined - - **Accept**: application/json + - **Accept**: application/json, application/vnd.apache.arrow.stream ### HTTP response details | Status code | Description | Response headers | |-------------|-------------|------------------| -**200** | Result data | - | -**404** | Result not found | - | +**200** | Result data. JSON callers receive `GetResultResponse`. Arrow callers receive an Arrow IPC stream — a sequence of IPC messages: schema header, then RecordBatch messages, then EOS. | * Link - RFC 5988 `Link` header with `rel=\"next\"` pointing at the next page when a finite `limit` does not reach the end of the result.
* X-Total-Row-Count - Total rows in the full result, ignoring offset/limit. Present only when status is `ready`.
| +**202** | Result is still being computed (`pending` or `processing`). Poll the same URL. | * Retry-After - Suggested seconds before the next poll.
| +**400** | Invalid offset, limit, or format. | - | +**404** | Result not found. | - | +**409** | Result computation failed. Body carries `error_message` describing the failure. | - | [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) diff --git a/hotdata/api/results_api.py b/hotdata/api/results_api.py index 656d378..3ac2da3 100644 --- a/hotdata/api/results_api.py +++ b/hotdata/api/results_api.py @@ -44,6 +44,9 @@ def __init__(self, api_client=None) -> None: def get_result( self, id: Annotated[StrictStr, Field(description="Result ID")], + offset: Annotated[Optional[Annotated[int, Field(strict=True, ge=0)]], Field(description="Rows to skip (default: 0)")] = None, + limit: Annotated[Optional[Annotated[int, Field(strict=True, ge=0)]], Field(description="Maximum rows to return (default: unbounded)")] = None, + format: Annotated[Optional[StrictStr], Field(description="`arrow` or `json` — overrides the `Accept` header.")] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -59,10 +62,16 @@ def get_result( ) -> GetResultResponse: """Get result - Retrieve a persisted query result by ID. If the result is still being processed, only the status is returned. Once ready, the full column and row data is included in the response. + Retrieve a persisted query result by ID. The response format for the `ready` state is selected by `Accept` header or `?format=` query param; non-ready states use the same status codes and JSON body shape regardless of format. | Result status | Status × body | |-----------------------|------------------------------------------------------------------------------| | `ready` + JSON | 200 `application/json` — `GetResultResponse` with `columns`, `rows`, etc. | | `ready` + Arrow | 200 `application/vnd.apache.arrow.stream` — schema, RecordBatches, EOS | | `pending`/`processing`| 202 `application/json` `{status, result_id}` + `Retry-After` | | `failed` | 409 `application/json` `{status, result_id, error_message}` | | not found | 404 `application/json` (`ApiErrorResponse`) | `?format=arrow` (or `?format=json`) takes precedence over `Accept`. Use `?offset=N&limit=M` to slice the result; `offset` defaults to 0 and `limit` is unbounded by default. Both must be non-negative; invalid values return 400. When a finite `limit` doesn't reach the end of the result, a `Link` header with `rel=\"next\"` points at the following page. Ready responses (both formats) carry `X-Total-Row-Count` (full result row count from parquet metadata, independent of offset/limit). The Arrow path streams end-to-end with no spawned task between the parquet reader and the wire — clients can disconnect at any time and the server stops reading. :param id: Result ID (required) :type id: str + :param offset: Rows to skip (default: 0) + :type offset: int + :param limit: Maximum rows to return (default: unbounded) + :type limit: int + :param format: `arrow` or `json` — overrides the `Accept` header. + :type format: str :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -87,6 +96,9 @@ def get_result( _param = self._get_result_serialize( id=id, + offset=offset, + limit=limit, + format=format, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -95,7 +107,10 @@ def get_result( _response_types_map: Dict[str, Optional[str]] = { '200': "GetResultResponse", + '202': "GetResultResponse", + '400': "ApiErrorResponse", '404': "ApiErrorResponse", + '409': "GetResultResponse", } response_data = self.api_client.call_api( *_param, @@ -112,6 +127,9 @@ def get_result( def get_result_with_http_info( self, id: Annotated[StrictStr, Field(description="Result ID")], + offset: Annotated[Optional[Annotated[int, Field(strict=True, ge=0)]], Field(description="Rows to skip (default: 0)")] = None, + limit: Annotated[Optional[Annotated[int, Field(strict=True, ge=0)]], Field(description="Maximum rows to return (default: unbounded)")] = None, + format: Annotated[Optional[StrictStr], Field(description="`arrow` or `json` — overrides the `Accept` header.")] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -127,10 +145,16 @@ def get_result_with_http_info( ) -> ApiResponse[GetResultResponse]: """Get result - Retrieve a persisted query result by ID. If the result is still being processed, only the status is returned. Once ready, the full column and row data is included in the response. + Retrieve a persisted query result by ID. The response format for the `ready` state is selected by `Accept` header or `?format=` query param; non-ready states use the same status codes and JSON body shape regardless of format. | Result status | Status × body | |-----------------------|------------------------------------------------------------------------------| | `ready` + JSON | 200 `application/json` — `GetResultResponse` with `columns`, `rows`, etc. | | `ready` + Arrow | 200 `application/vnd.apache.arrow.stream` — schema, RecordBatches, EOS | | `pending`/`processing`| 202 `application/json` `{status, result_id}` + `Retry-After` | | `failed` | 409 `application/json` `{status, result_id, error_message}` | | not found | 404 `application/json` (`ApiErrorResponse`) | `?format=arrow` (or `?format=json`) takes precedence over `Accept`. Use `?offset=N&limit=M` to slice the result; `offset` defaults to 0 and `limit` is unbounded by default. Both must be non-negative; invalid values return 400. When a finite `limit` doesn't reach the end of the result, a `Link` header with `rel=\"next\"` points at the following page. Ready responses (both formats) carry `X-Total-Row-Count` (full result row count from parquet metadata, independent of offset/limit). The Arrow path streams end-to-end with no spawned task between the parquet reader and the wire — clients can disconnect at any time and the server stops reading. :param id: Result ID (required) :type id: str + :param offset: Rows to skip (default: 0) + :type offset: int + :param limit: Maximum rows to return (default: unbounded) + :type limit: int + :param format: `arrow` or `json` — overrides the `Accept` header. + :type format: str :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -155,6 +179,9 @@ def get_result_with_http_info( _param = self._get_result_serialize( id=id, + offset=offset, + limit=limit, + format=format, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -163,7 +190,10 @@ def get_result_with_http_info( _response_types_map: Dict[str, Optional[str]] = { '200': "GetResultResponse", + '202': "GetResultResponse", + '400': "ApiErrorResponse", '404': "ApiErrorResponse", + '409': "GetResultResponse", } response_data = self.api_client.call_api( *_param, @@ -180,6 +210,9 @@ def get_result_with_http_info( def get_result_without_preload_content( self, id: Annotated[StrictStr, Field(description="Result ID")], + offset: Annotated[Optional[Annotated[int, Field(strict=True, ge=0)]], Field(description="Rows to skip (default: 0)")] = None, + limit: Annotated[Optional[Annotated[int, Field(strict=True, ge=0)]], Field(description="Maximum rows to return (default: unbounded)")] = None, + format: Annotated[Optional[StrictStr], Field(description="`arrow` or `json` — overrides the `Accept` header.")] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -195,10 +228,16 @@ def get_result_without_preload_content( ) -> RESTResponseType: """Get result - Retrieve a persisted query result by ID. If the result is still being processed, only the status is returned. Once ready, the full column and row data is included in the response. + Retrieve a persisted query result by ID. The response format for the `ready` state is selected by `Accept` header or `?format=` query param; non-ready states use the same status codes and JSON body shape regardless of format. | Result status | Status × body | |-----------------------|------------------------------------------------------------------------------| | `ready` + JSON | 200 `application/json` — `GetResultResponse` with `columns`, `rows`, etc. | | `ready` + Arrow | 200 `application/vnd.apache.arrow.stream` — schema, RecordBatches, EOS | | `pending`/`processing`| 202 `application/json` `{status, result_id}` + `Retry-After` | | `failed` | 409 `application/json` `{status, result_id, error_message}` | | not found | 404 `application/json` (`ApiErrorResponse`) | `?format=arrow` (or `?format=json`) takes precedence over `Accept`. Use `?offset=N&limit=M` to slice the result; `offset` defaults to 0 and `limit` is unbounded by default. Both must be non-negative; invalid values return 400. When a finite `limit` doesn't reach the end of the result, a `Link` header with `rel=\"next\"` points at the following page. Ready responses (both formats) carry `X-Total-Row-Count` (full result row count from parquet metadata, independent of offset/limit). The Arrow path streams end-to-end with no spawned task between the parquet reader and the wire — clients can disconnect at any time and the server stops reading. :param id: Result ID (required) :type id: str + :param offset: Rows to skip (default: 0) + :type offset: int + :param limit: Maximum rows to return (default: unbounded) + :type limit: int + :param format: `arrow` or `json` — overrides the `Accept` header. + :type format: str :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -223,6 +262,9 @@ def get_result_without_preload_content( _param = self._get_result_serialize( id=id, + offset=offset, + limit=limit, + format=format, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -231,7 +273,10 @@ def get_result_without_preload_content( _response_types_map: Dict[str, Optional[str]] = { '200': "GetResultResponse", + '202': "GetResultResponse", + '400': "ApiErrorResponse", '404': "ApiErrorResponse", + '409': "GetResultResponse", } response_data = self.api_client.call_api( *_param, @@ -243,6 +288,9 @@ def get_result_without_preload_content( def _get_result_serialize( self, id, + offset, + limit, + format, _request_auth, _content_type, _headers, @@ -267,6 +315,18 @@ def _get_result_serialize( if id is not None: _path_params['id'] = id # process the query parameters + if offset is not None: + + _query_params.append(('offset', offset)) + + if limit is not None: + + _query_params.append(('limit', limit)) + + if format is not None: + + _query_params.append(('format', format)) + # process the header parameters # process the form parameters # process the body parameter @@ -276,7 +336,8 @@ def _get_result_serialize( if 'Accept' not in _header_params: _header_params['Accept'] = self.api_client.select_header_accept( [ - 'application/json' + 'application/json', + 'application/vnd.apache.arrow.stream' ] )