This is an automated email from the ASF dual-hosted git repository.
victoria pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/druid.git
The following commit(s) were added to refs/heads/master by this push:
new e68979e03be Docs: update SQL API reference (#15515)
e68979e03be is described below
commit e68979e03be2ff6b453aa5a5e761a677e64ff041
Author: Victoria Lim <[email protected]>
AuthorDate: Fri Dec 8 11:53:19 2023 -0800
Docs: update SQL API reference (#15515)
Co-authored-by: 317brian <[email protected]>
---
docs/api-reference/sql-api.md | 31 +++++++++++++++++++++----------
1 file changed, 21 insertions(+), 10 deletions(-)
diff --git a/docs/api-reference/sql-api.md b/docs/api-reference/sql-api.md
index c362e4edb6d..e6e39ded660 100644
--- a/docs/api-reference/sql-api.md
+++ b/docs/api-reference/sql-api.md
@@ -40,7 +40,7 @@ In this topic, `http://ROUTER_IP:ROUTER_PORT` is a
placeholder for your Router s
Submits a SQL-based query in the JSON request body. Returns a JSON object with
the query results and optional metadata for the results. You can also use this
endpoint to query [metadata tables](../querying/sql-metadata-tables.md).
-Each query has an associated SQL query ID. You can set this ID manually using
the SQL context parameter `sqlQueryId`. If not set, Druid automatically
generates `sqlQueryId` and returns it in the response header for
`X-Druid-SQL-Query-Id`. Note that you need the `sqlQueryId` to [cancel a
query](#cancel-a-query) endpoint.
+Each query has an associated SQL query ID. You can set this ID manually using
the SQL context parameter `sqlQueryId`. If not set, Druid automatically
generates `sqlQueryId` and returns it in the response header for
`X-Druid-SQL-Query-Id`. Note that you need the `sqlQueryId` to [cancel a
query](#cancel-a-query).
#### URL
@@ -51,20 +51,30 @@ Each query has an associated SQL query ID. You can set this
ID manually using th
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 header
`Content-Type: application/json`.
- * `array`: Returns a JSON array of JSON arrays with the HTTP header
`Content-Type: application/json`.
- * `objectLines`: Returns newline-delimited JSON objects with a trailing
blank line. Returns the HTTP header `Content-Type: text/plain`.
- * `arrayLines`: Returns newline-delimited JSON arrays with a trailing blank
line. Returns the HTTP header `Content-Type: text/plain`.
- * `csv`: Returns a comma-separated values with one row per line and a
trailing blank line. Returns the HTTP header `Content-Type: text/csv`.
+ * `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`.
+
* `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.
+
* `typesHeader`: Adds Druid runtime type information in the header. Requires
`header` to be set to `true`. Complex types, like sketches, will be reported as
`COMPLEX<typeName>` if a particular complex type name is known for that field,
or as `COMPLEX` if the particular type name is unknown or mixed.
+
* `sqlTypesHeader`: Adds SQL type information in the header. Requires `header`
to be set to `true`.
+
+ For compatibility, Druid returns the HTTP header
`X-Druid-SQL-Header-Included: yes` when all of the following conditions are met:
+ * The `header` property is set to true.
+ * The version of Druid supports `typesHeader` and `sqlTypesHeader`,
regardless of whether either property is set.
+
* `context`: JSON object containing optional [SQL query context
parameters](../querying/sql-query-context.md), such as to set the query ID,
time zone, and whether to use an approximation algorithm for distinct count.
+
* `parameters`: List of query parameters for parameterized queries. Each
parameter in the array should be a JSON object containing the parameter's SQL
data type and parameter value. For a list of supported SQL types, see [Data
types](../querying/sql-data-types.md).
For example:
- ```
+ ```json
"parameters": [
{
"type": "VARCHAR",
@@ -114,7 +124,6 @@ The request body takes the following properties:
</TabItem>
</Tabs>
-Older versions of Druid that support the `typesHeader` and `sqlTypesHeader`
parameters return the HTTP header `X-Druid-SQL-Header-Included: yes` when you
set `header` to `true`. Druid returns the HTTP response header for
compatibility, regardless of whether `typesHeader` and `sqlTypesHeader` are set.
---
@@ -346,10 +355,12 @@ A successful response results in an `HTTP 202` message
code and an empty respons
### Query output format
-The following table shows examples of how Druid returns the column names and
data types based on the result format and the type request. The examples
includes the first row of results, where the value of `user` is `BlueMoon2662`.
+The following table shows examples of how Druid returns the column names and
data types based on the result format and the type request.
+In all cases, `header` is true.
+The examples includes the first row of results, where the value of `user` is
`BlueMoon2662`.
```
-| Format | typesHeader | sqlTypesHeader | Example Output
|
+| Format | typesHeader | sqlTypesHeader | Example output
|
|--------|-------------|----------------|--------------------------------------------------------------------------------------------|
| object | true | false | [ { "user" : { "type" : "STRING" }
}, { "user" : "BlueMoon2662" } ] |
| object | true | true | [ { "user" : { "type" : "STRING",
"sqlType" : "VARCHAR" } }, { "user" : "BlueMoon2662" } ] |
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
