(druid) branch 29.0.1 updated: docs: restore information about truncated responses to sql api (#16001) (#16066)

[br...@apache.org]

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 <te...@gmail.com>
AuthorDate: Wed Mar 6 15:45:16 2024 -0800

    docs: restore information about truncated responses to sql api (#16001) (#16066)
    
    Co-authored-by: 317brian <53...@users.noreply.github.com>
    Co-authored-by: Victoria Lim <li...@gmail.com>
---
 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: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org