This is an automated email from the ASF dual-hosted git repository.
brile pushed a commit to branch 29.0.1
in repository https://gitbox.apache.org/repos/asf/druid.git
The following commit(s) were added to refs/heads/29.0.1 by this push:
new 1c36a3231ec docs: restore information about truncated responses to sql
api (#16001) (#16066)
1c36a3231ec is described below
commit 1c36a3231ec5ee0544ba7cb611aced2719373c53
Author: Charles Smith <[email protected]>
AuthorDate: Wed Mar 6 15:45:16 2024 -0800
docs: restore information about truncated responses to sql api (#16001)
(#16066)
Co-authored-by: 317brian <[email protected]>
Co-authored-by: Victoria Lim <[email protected]>
---
docs/api-reference/sql-api.md | 34 +++++++++++++++++++++++++++++-----
1 file changed, 29 insertions(+), 5 deletions(-)
diff --git a/docs/api-reference/sql-api.md b/docs/api-reference/sql-api.md
index e6e39ded660..8cc17bc0641 100644
--- a/docs/api-reference/sql-api.md
+++ b/docs/api-reference/sql-api.md
@@ -53,11 +53,25 @@ The request body takes the following properties:
* `query`: SQL query string.
* `resultFormat`: String that indicates the format to return query results.
Select one of the following formats:
- * `object`: Returns a JSON array of JSON objects with the HTTP response
header `Content-Type: application/json`.
- * `array`: Returns a JSON array of JSON arrays with the HTTP response header
`Content-Type: application/json`.
- * `objectLines`: Returns newline-delimited JSON objects with a trailing
blank line. Returns the HTTP response header `Content-Type: text/plain`.
- * `arrayLines`: Returns newline-delimited JSON arrays with a trailing blank
line. Returns the HTTP response header `Content-Type: text/plain`.
- * `csv`: Returns a comma-separated values with one row per line and a
trailing blank line. Returns the HTTP response header `Content-Type: text/csv`.
+ * `object`: Returns a JSON array of JSON objects with the HTTP response
header `Content-Type: application/json`.
+ Object field names match the columns returned by the SQL query in the
same order as the SQL query.
+
+ * `array`: Returns a JSON array of JSON arrays with the HTTP response header
`Content-Type: application/json`.
+ Each inner array has elements matching the columns returned by the SQL
query, in order.
+
+ * `objectLines`: Returns newline-delimited JSON objects with the HTTP
response header `Content-Type: text/plain`.
+ Newline separation facilitates parsing the entire response set as a
stream if you don't have a streaming JSON parser.
+ This format includes a single trailing newline character so you can
detect a truncated response.
+
+ * `arrayLines`: Returns newline-delimited JSON arrays with the HTTP response
header `Content-Type: text/plain`.
+ Newline separation facilitates parsing the entire response set as a
stream if you don't have a streaming JSON parser.
+ This format includes a single trailing newline character so you can
detect a truncated response.
+
+ * `csv`: Returns comma-separated values with one row per line. Sent with the
HTTP response header `Content-Type: text/csv`.
+ Druid uses double quotes to escape individual field values. For example,
a value with a comma returns `"A,B"`.
+ If the field value contains a double quote character, Druid escapes it
with a second double quote character.
+ For example, `foo"bar` becomes `foo""bar`.
+ This format includes a single trailing newline character so you can
detect a truncated response.
* `header`: Boolean value that determines whether to return information on
column names. When set to `true`, Druid returns the column names as the first
row of the results. To also get information on the column types, set
`typesHeader` or `sqlTypesHeader` to `true`. For a comparative overview of data
formats and configurations for the header, see the [Query output
format](#query-output-format) table.
@@ -124,6 +138,16 @@ The request body takes the following properties:
</TabItem>
</Tabs>
+#### Client-side error handling and truncated responses
+
+Druid reports errors that occur before the response body is sent as JSON with
an HTTP 500 status code. The errors are reported using the same format as
[native Druid query errors](../querying/querying.md#query-errors).
+If an error occurs while Druid is sending the response body, the server
handling the request stops the response midstream and logs an error.
+
+This means that when you call the SQL API, you must properly handle response
truncation.
+For `object` and `array` formats, truncated responses are invalid JSON.
+For line-oriented formats, Druid includes a newline character as the final
character of every complete response. Absence of a final newline character
indicates a truncated response.
+
+If you detect a truncated response, treat it as an error.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
