diff --git a/docs/api-reference/sql-api.md b/docs/api-reference/sql-api.md index 50291c7ba3b9..c362e4edb6d3 100644 --- a/docs/api-reference/sql-api.md +++ b/docs/api-reference/sql-api.md @@ -390,12 +390,10 @@ Generally, the `sql` and `sql/statements` endpoints support the same response bo Keep the following in mind when submitting queries to the `sql/statements` endpoint: -- There are additional context parameters for `sql/statements`: +- Apart from the context parameters mentioned [here](../multi-stage-query/reference.md#context-parameters) there are additional context parameters for `sql/statements` specifically: - `executionMode` determines how query results are fetched. Druid currently only supports `ASYNC`. You must manually retrieve your results after the query completes. - - `selectDestination` determines where final results get written. By default, results are written to task reports. Set this parameter to `durableStorage` to instruct Druid to write the results from SELECT queries to durable storage, which allows you to fetch larger result sets. Note that this requires you to have [durable storage for MSQ enabled](../operations/durable-storage.md). - -- The only supported value for `resultFormat` is JSON LINES. + - `selectDestination` determines where final results get written. By default, results are written to task reports. Set this parameter to `durableStorage` to instruct Druid to write the results from SELECT queries to durable storage, which allows you to fetch larger result sets. For result sets with more than 3000 rows, it is highly recommended to use `durableStorage`. Note that this requires you to have [durable storage for MSQ](../operations/durable-storage.md) enabled. #### Responses @@ -812,12 +810,10 @@ Host: http://ROUTER_IP:ROUTER_PORT Retrieves results for completed queries. Results are separated into pages, so you can use the optional `page` parameter to refine the results you get. Druid returns information about the composition of each page and its page number (`id`). For information about pages, see [Get query status](#get-query-status). -If a page number isn't passed, all results are returned sequentially in the same response. If you have large result sets, you may encounter timeouts based on the value configured for `druid.router.http.readTimeout`. -When getting query results, keep the following in mind: +If a page number isn't passed, all results are returned sequentially in the same response. If you have large result sets, you may encounter timeouts based on the value configured for `druid.router.http.readTimeout`. -- JSON Lines is the only supported result format. -- Getting the query results for an ingestion query returns an empty response. +Getting the query results for an ingestion query returns an empty response. #### URL @@ -826,7 +822,10 @@ When getting query results, keep the following in mind: #### Query parameters * `page` (optional) * Type: Int - * Refine paginated results + * Fetch results based on page numbers. If not specified, all results are returned sequentially starting from page 0 to N in the same response. +* `resultFormat` (optional) + * Type: String + * Defines the format in which the results are presented. The following options are supported `arrayLines`,`objectLines`,`array`,`object`, and `csv`. The default is `object`. #### Responses diff --git a/docs/querying/query-from-deep-storage.md b/docs/querying/query-from-deep-storage.md index c9c97f780ddb..1ce74818655d 100644 --- a/docs/querying/query-from-deep-storage.md +++ b/docs/querying/query-from-deep-storage.md @@ -89,10 +89,10 @@ Submitting a query from deep storage uses the same syntax as any other Druid SQL Generally, the request body fields are the same between the `sql` and `sql/statements` endpoints. -There are additional context parameters for `sql/statements` specifically: +Apart from the context parameters mentioned [here](../multi-stage-query/reference.md#context-parameters) there are additional context parameters for `sql/statements`: - `executionMode` (required) determines how query results are fetched. Set this to `ASYNC`. - - `selectDestination` (optional) set to `durableStorage` instructs Druid to write the results from SELECT queries to durable storage. Note that this requires you to have [durable storage for MSQ enabled](../operations/durable-storage.md). + - `selectDestination` (optional) set to `durableStorage` instructs Druid to write the results of SELECT queries to durable storage. For result sets with more than 3000 rows, it is highly recommended to use `durableStorage`. Note that this requires you to have [durable storage for MSQ enabled](../operations/durable-storage.md). The following sample query includes the two additional context parameters that querying from deep storage supports: @@ -182,12 +182,14 @@ Only the user who submitted a query can retrieve the results for the query. Use the following endpoint to retrieve results: ``` -GET https://ROUTER:8888/druid/v2/sql/statements/QUERYID/results?page=PAGENUMBER&size=RESULT_SIZE&timeout=TIMEOUT_MS +GET https://ROUTER:8888/druid/v2/sql/statements/QUERYID/results?page=PAGENUMBER&resultFormat=FORMAT ``` Results are returned in JSON format. -You can use the optional `page`, `size`, and `timeout` parameters to refine your results. You can retrieve the `page` information for your results by fetching the status of the completed query. +You can use the optional `page` parameter to refine your results, and `resultFormat` parameter to define the format in which the results will be presented. +* You can retrieve the `page` information for your results by fetching the status of the completed query. +* For `resultFormat` the following options are supported `arrayLines`,`objectLines`,`array`,`object`, and `csv`. Default value is `object`. More documentation present [here](../api-reference/sql-api.md#request-body). When you try to get results for a query from deep storage, you may receive an error that states the query is still running. Wait until the query completes before you try again.