317brian commented on code in PR #16001:
URL: https://github.com/apache/druid/pull/16001#discussion_r1515085847
##########
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 trailer of one blank 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 trailer of one blank 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"`.
Review Comment:
```suggestion
Druid uses double quotes to escape individual field values. For
example, a value with a comma returns `"A,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 trailer of one blank newline character so you can
detect a truncated response.
Review Comment:
```suggestion
This format includes a single trailing newline character so you can
detect a truncated response.
```
##########
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 trailer of one blank newline character so you can
detect a truncated response.
Review Comment:
I've never seen it called a trailer? It's usually described as a trailing
character. Same comment for all appearances of this line
##########
docs/api-reference/sql-api.md:
##########
@@ -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, 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 will be invalid JSON.
Review Comment:
```suggestion
For `object` and `array` formats, truncated responses are invalid JSON.
```
##########
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 trailer of one blank 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 trailer of one blank 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`.
Review Comment:
```suggestion
For example, `foo"bar` becomes `foo""bar`.
```
##########
docs/api-reference/sql-api.md:
##########
@@ -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, using the same format as [native Druid query
errors](../querying/querying.md#query-errors).
Review Comment:
```suggestion
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).
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
