[DOCS] SQL: Add formal API docs (#75506)

Adds formal API docs for the following APIs:

* Clear SQL cursor
* SQL search
* SQL translate

Other changes:

* Removes and redirects the "Supported REST parameters section." This is now covered in the SQL search API docs.
* Updates a few related xrefs.

Closes #75085

Author: jrodewig

docs/reference/redirects.asciidoc

@@ -1632,4 +1632,10 @@ See <<field-usage-stats>>.
 [role="exclude",id="security-api-enroll-kibana"]
 === Enroll {kib} API
 
-See <<security-api-kibana-enrollment>>.
+See <<security-api-kibana-enrollment>>.
+
+[role="exclude",id="sql-rest-fields"]
+=== Supported REST parameters for SQL search API
+
+See the <<sql-search-api-request-body,request body parameters>> for the
+<<sql-search-api,SQL search API>>.

docs/reference/sql/apis/clear-sql-cursor-api.asciidoc

@@ -0,0 +1,48 @@
+[role="xpack"]
+[testenv="basic"]
+[[clear-sql-cursor-api]]
+=== Clear SQL cursor API
+++++
+<titleabbrev>Clear SQL cursor</titleabbrev>
+++++
+
+Clears an <<sql-pagination,SQL search cursor>>.
+
+////
+[source,console]
+----
+POST _sql
+{
+  "query": "SELECT * FROM library ORDER BY page_count DESC",
+  "fetch_size": 5
+}
+----
+// TEST[setup:library]
+////
+
+[source,console]
+----
+POST _sql/close
+{
+  "cursor": "sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWYUpOYklQMHhRUEtld3RsNnFtYU1hQQ==:BAFmBGRhdGUBZgVsaWtlcwFzB21lc3NhZ2UBZgR1c2Vy9f///w8="
+}
+----
+// TEST[continued]
+// TEST[s/sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWYUpOYklQMHhRUEtld3RsNnFtYU1hQQ==:BAFmBGRhdGUBZgVsaWtlcwFzB21lc3NhZ2UBZgR1c2Vy9f\/\/\/w8=/$body.cursor/]
+
+[[clear-sql-cursor-api-request]]
+==== {api-request-title}
+
+`POST _sql/close`
+
+[[clear-sql-cursor-api-limitations]]
+===== Limitations
+
+See <<sql-limitations>>.
+
+[role="child_attributes"]
+[[clear-sql-cursor-api-request-body]]
+==== {api-request-body-title}
+
+`cursor`::
+(Required, string) Cursor to clear.

docs/reference/sql/apis/get-async-sql-search-api.asciidoc

@@ -60,5 +60,5 @@ Defaults to no timeout, meaning the request waits for complete search results.
 [[get-async-sql-search-api-response-body]]
 ==== {api-response-body-title}
 
-The get async SQL search API returns the same response body as the SQL search
-API.
+The get async SQL search API returns the same response body as the
+<<sql-search-api-response-body,SQL search API>>.

docs/reference/sql/apis/sql-apis.asciidoc

@@ -3,17 +3,24 @@
 [[sql-apis]]
 == SQL APIs
 
-NOTE: This list of SQL APIs is incomplete. We're working to add more.
-
 {es}'s SQL APIs let you run SQL queries on {es} indices and data streams.
 For an overview of {es}'s SQL features and related tutorials, see <<xpack-sql>>.
 
+* <<sql-search-api>>
+* <<clear-sql-cursor-api>>
 * <<get-async-sql-search-api>>
 * <<get-async-sql-search-status-api>>
 * <<delete-async-sql-search-api>>
+* <<sql-translate-api>>
+
+include::clear-sql-cursor-api.asciidoc[]
 
 include::delete-async-sql-search-api.asciidoc[]
 
 include::get-async-sql-search-api.asciidoc[]
 
-include::get-async-sql-search-status-api.asciidoc[]
+include::get-async-sql-search-status-api.asciidoc[]
+
+include::sql-search-api.asciidoc[]
+
+include::sql-translate-api.asciidoc[]

docs/reference/sql/apis/sql-search-api.asciidoc

@@ -0,0 +1,180 @@
+[role="xpack"]
+[testenv="basic"]
+[[sql-search-api]]
+=== SQL search API
+++++
+<titleabbrev>SQL search</titleabbrev>
+++++
+
+Returns results for an <<sql-rest-overview,SQL search>>.
+
+[source,console]
+----
+POST _sql?format=txt
+{
+  "query": "SELECT * FROM library ORDER BY page_count DESC LIMIT 5"
+}
+----
+// TEST[setup:library]
+
+[[sql-search-api-request]]
+==== {api-request-title}
+
+`GET _sql`
+
+`POST _sql`
+
+[[sql-search-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `read`
+<<privileges-list-indices,index privilege>> for the data stream, index,
+or alias you search.
+
+[[sql-search-api-limitations]]
+===== Limitations
+
+See <<sql-limitations>>.
+
+[[search-api-query-params]]
+==== {api-query-parms-title}
+
+`delimiter`::
+(Optional, string) Separator for CSV results. Defaults to `,`. The API only
+supports this parameter for CSV responses.
+
+`format`::
+(Optional, string) Format for the response. For valid values, see
+<<sql-rest-format>>.
++
+You can also specify a format using the `Accept` HTTP header. If you specify
+both this parameter and the `Accept` HTTP header, this parameter takes
+precedence.
+
+[role="child_attributes"]
+[[sql-search-api-request-body]]
+==== {api-request-body-title}
+
+`columnar`::
+(Optional, Boolean) If `true`, returns results in a columnar format. Defaults to
+`false`. The API only supports this parameter for CBOR, JSON, SMILE, and YAML
+responses. See <<sql-rest-columnar>>.
+
+`cursor`::
+(Optional, string) <<sql-pagination,Cursor>> used to retrieve a set of paginated
+results. If you specify a `cursor`, the API only uses the `columnar` and
+`time_zone` request body parameters. It ignores other request body parameters.
+
+[[sql-search-api-fetch-size]]
+`fetch_size`::
+(Optional, integer) Maximum number of rows to return in the response. Defaults
+to `1000`.
+
+[[sql-search-api-field-multi-value-leniency]]
+`field_multi_value_leniency`::
+(Optional, Boolean) If `false`, the API returns an error for fields containing
+<<array,array values>>. If `true`, the API returns the first value from the
+array with no guarantee of consistent results. Defaults to `false`.
+
+`filter`::
+(Optional, object) <<query-dsl,Query DSL>> used to filter documents for the SQL
+search. See <<sql-rest-filtering>>.
+
+`index_include_frozen`::
+(Optional, Boolean) If `true`, the search can run on frozen indices. Defaults to
+`false`.
+
+`keep_alive`::
+(Optional, <<time-units,time value>>) Retention period for an
+<<sql-async,async>> or <<sql-store-searches,saved synchronous search>>. Defaults
+to `5d` (five days).
+
+`keep_on_completion`::
+(Optional, Boolean) If `true`, {es} <<sql-store-searches,stores synchronous
+searches>> if you also specify the `wait_for_completion_timeout` parameter. If
+`false`, {es} only stores <<sql-async,async searches>> that don't finish before
+the `wait_for_completion_timeout`. Defaults to `false`.
+
+`page_timeout`::
+(Optional, <<time-units,time value>>) Timeout before a
+<<sql-pagination,pagination request>> fails. Defaults to `45s` (45 seconds).
+
+`params`::
+(Optional, array) Values for parameters in the `query`. For syntax, see
+<<sql-rest-params>>.
+
+`query`::
+(Required, object) SQL query to run. For syntax, see <<sql-spec>>.
+
+`request_timeout`::
+(Optional, <<time-units,time value>>) Timeout before the request fails. Defaults
+to `90s` (90 seconds).
+
+include::{es-repo-dir}/search/search.asciidoc[tag=runtime-mappings-def]
+
+[[sql-search-api-time-zone]]
+`time_zone`::
+(Optional, string) ISO-8601 time zone ID for the search. Several
+<<sql-functions-datetime,SQL date/time functions>> use this time zone. Defaults
+to `Z` (UTC).
+
+`wait_for_completion_timeout`::
+(Optional, <<time-units,time value>>) Period to wait for complete results.
+Defaults to no timeout, meaning the request waits for complete search results.
+If the search doesn’t finish within this period, the search becomes
+<<sql-async,async>>.
++
+To <<sql-store-searches,save a synchronous search>>, you must specify this
+parameter and the `keep_on_completion` parameter.
+
+[role="child_attributes"]
+[[sql-search-api-response-body]]
+==== {api-response-body-title}
+
+The SQL search API supports <<sql-rest-format,multiple response formats>>. Most
+response formats use a tabular layout. JSON responses contain the following
+properties:
+
+`id`::
+(string) Identifier for the search. This value is only returned for
+<<sql-async,async>> and <<sql-store-searches,saved synchronous searches>>. For
+CSV, TSV, and TXT responses, this value is returned in the `Async-ID` HTTP
+header.
+
+`is_running`::
+(Boolean) If `true`, the search is still running. If `false`, the search has
+finished. This value is only returned for <<sql-async,async>> and
+<<sql-store-searches,saved synchronous searches>>. For CSV, TSV, and TXT
+responses, this value is returned in the `Async-partial` HTTP header.
+
+`is_partial`::
+(Boolean) If `true`, the response does not contain complete search results. If
+`is_partial` is `true` and `is_running` is `true`, the search is still running.
+If `is_partial` is `true` but `is_running` is `false`, the results are partial
+due to a failure or timeout.
++
+This value is only returned for <<sql-async,async>> and
+<<sql-store-searches,saved synchronous searches>>. For CSV, TSV, and TXT
+responses, this value is returned in the `Async-partial` HTTP header.
+
+`rows`::
+(array of arrays)
+Values for the search results.
+
+`columns`::
+(array of objects)
+Column headings for the search results. Each object is a column.
++
+.Properties of `columns` objects
+[%collapsible%open]
+====
+`name`::
+(string) Name of the column.
+
+`type`::
+(string) Data type for the column.
+====
+
+`cursor`::
+(string) <<sql-pagination,Cursor>> for the next set of paginated results. For
+CSV, TSV, and TXT responses, this value is returned in the `Cursor` HTTP header.

docs/reference/sql/apis/sql-translate-api.asciidoc

@@ -0,0 +1,53 @@
+[role="xpack"]
+[testenv="basic"]
+[[sql-translate-api]]
+=== SQL translate API
+++++
+<titleabbrev>SQL translate</titleabbrev>
+++++
+
+Translates an <<sql-search-api,SQL search>> into a <<search-search,search API>>
+request containing <<query-dsl,Query DSL>>. See <<sql-translate>>.
+
+[source,console]
+----
+POST _sql/translate
+{
+  "query": "SELECT * FROM library ORDER BY page_count DESC",
+  "fetch_size": 10
+}
+----
+// TEST[setup:library]
+
+[[sql-translate-api-request]]
+==== {api-request-title}
+
+`GET _sql/translate`
+
+`POST _sql/translate`
+
+[[sql-translate-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `read`
+<<privileges-list-indices,index privilege>> for the data stream, index,
+or alias you search.
+
+[[sql-translate-api-limitations]]
+===== Limitations
+
+See <<sql-limitations>>.
+
+[role="child_attributes"]
+[[sql-translate-api-request-body]]
+==== {api-request-body-title}
+
+The SQL translate API accepts the same request body parameters as the
+<<sql-search-api-request-body,SQL search API>>, excluding `cursor`.
+
+[role="child_attributes"]
+[[sql-translate-api-response-body]]
+==== {api-response-body-title}
+
+The SQL translate API returns the same response body as the
+<<search-search,search API>>.

docs/reference/sql/endpoints/odbc/configuration.asciidoc

@@ -220,8 +220,9 @@ timeout.
 * Max page size (rows)
 +
 The maximum number of rows that {es-sql} server should send the driver for one
-page. This corresponds to {es-sql}'s request parameter `fetch_size` (see
-<<sql-rest-fields>>). The value 0 means server default.
+page. This corresponds to the SQL search API's
+<<sql-search-api-fetch-size,`fetch_size`>> parameter. A `0` value indicates a
+server default.
 +
 * Max page length (MB)
 +
@@ -314,8 +315,9 @@ multi-value field is queried. In case this is set and the server encounters
 such a field, it will pick a value in the set - without any guarantees of what
 that will be, but typically the first in natural ascending order - and return
 it as the value for the column. If not set, the server will return an error.
-This corresponds to {es-sql}'s request parameter `field_multi_value_leniency`
-(see <<sql-rest-fields>>).
+This corresponds to the SQL search API's
+<<sql-search-api-field-multi-value-leniency,`field_multi_value_leniency`>>
+parameter.
 +
 * Include frozen indices
 +