[DOCS] SQL: Add formal API docs #75506

jrodewig · 2021-07-19T22:53:34Z

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

Preview

elasticmachine · 2021-07-20T16:26:32Z

Pinging @elastic/clients-team (Team:Clients)

elasticmachine · 2021-07-20T16:26:32Z

Pinging @elastic/es-ql (Team:QL)

elasticmachine · 2021-07-20T16:26:33Z

Pinging @elastic/es-docs (Team:Docs)

rest-api-spec/src/main/resources/rest-api-spec/api/sql.clear_cursor.json

sethmlarson

URL updates in API specs LGTM with one nit.

bpintea

LG, thank you, I've left some minor notes, just one omission that should be corrected.

bpintea · 2021-07-20T19:31:21Z

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

+`false`.
+
+`keep_alive`::
+(Optional, <<time-units,time value>>) Retention period for the search and its


Would it be worth mentioning that this is an async search parameter? Not to have the user assume that any result will be stored by simply providing this parameter alone; or at least mention the required tandem with wait_for_completion_timeout.
And maybe same for keep_on_completion and wait_for_completion_timeout[*]; like for id, is_running.

[*] As implementation detail also when attempting to "store a sync search", that search is actually turned async internally.

Thanks for calling this out. For the keep_alive parameter, I reworded to:

Retention period for an async or saved synchronous search. Defaults to 5d (five days).

Both the async and saved synchronous search copy have xrefs.

I added similar xrefs to the keep_on_completion and wait_for_completion_timeout parameter definitions.

bpintea · 2021-07-20T19:31:24Z

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

+`keep_alive`::
+(Optional, <<time-units,time value>>) Retention period for the search and its
+results. Defaults to `5d` (five days).
+


keep_on_completion is missing.

Thanks for catching this.

bpintea · 2021-07-20T19:38:52Z

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

+both this parameter and the `Accept` HTTP header, the API only uses this
+parameter.


Just a proposal: ", this parameter takes precedence."? Your formulation is easy to understand, the proposal might be more established in case of overlapping specs.

Thanks. I'll use:

If you specify both this parameter and the `Accept` HTTP header, this parameter take precedence.

bpintea · 2021-07-20T19:46:13Z

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

+<<sql-pagination,pagination request>> fails. Defaults to `45s` (45 seconds).
+
+`params`::
+(Optional, array) Values for variables in the `query`. For variable syntax, see


Suggested change

(Optional, array) Values for variables in the `query`. For variable syntax, see

(Optional, array) Values for parameters in the `query`. For variable syntax, see

Some SQL implementations allow for variables in procedural extensions -- I'd avoid this term.

Thanks for pointing this out.

bpintea · 2021-07-20T19:56:09Z

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

+[[clear-sql-cursor-api-limitations]]
+===== Limitations
+
+See <<sql-limitations>>.


I don't think we (currently) have any limitations specifically targeting clear cursor and the async-specific APIs. They are mostly about the SQL implementation and interaction with Elasticsearch concepts. It seems futer-safer to have the limitation section on these pages, but we can also add them if/when we introduce them. Just FYI, in case this section isn't added preventively on all pages.

Thanks for pointing this out. This is largely here for future-proofing. I'll leave it in for now as it's consistent with our EQL docs.

jrodewig · 2021-07-20T21:25:13Z

Thanks, @bpintea!

jrodewig · 2021-07-20T21:30:54Z

@elasticmachine update branch

bpintea

LGTM, thanks!

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 # Conflicts: # docs/reference/redirects.asciidoc

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

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 elastic#75085

elasticsearchmachine added the v8.0.0 label Jul 19, 2021

sethmlarson added the Team:Clients Meta label for clients team label Jul 19, 2021

[DOCS] SQL: Add formal API docs

a4088d7

jrodewig added :Analytics/SQL SQL querying >docs General docs changes v7.14.1 v7.15.0 labels Jul 20, 2021

jrodewig marked this pull request as ready for review July 20, 2021 16:26

elasticmachine added Team:QL (Deprecated) Meta label for query languages team Team:Docs Meta label for docs team labels Jul 20, 2021

jrodewig requested a review from bpintea July 20, 2021 16:26

sethmlarson reviewed Jul 20, 2021

View reviewed changes

rest-api-spec/src/main/resources/rest-api-spec/api/sql.clear_cursor.json Outdated Show resolved Hide resolved

sethmlarson approved these changes Jul 20, 2021

View reviewed changes

jrodewig added the v7.13.5 label Jul 20, 2021

use current link in API spec

e263784

bpintea reviewed Jul 20, 2021

View reviewed changes

Address feedback

baac3cc

elasticmachine and others added 2 commits July 20, 2021 23:30

Merge branch 'master' into docs__sql-apis

0267b94

Fix typos

e27bced

bpintea approved these changes Jul 21, 2021

View reviewed changes

jrodewig merged commit ea635d6 into elastic:master Jul 21, 2021

jrodewig deleted the docs__sql-apis branch July 21, 2021 12:04

This was referenced Jul 21, 2021

[7.x] [DOCS] SQL: Add formal API docs (#75506) #75579

Merged

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

Merged

jrodewig removed the v7.13.5 label Jul 21, 2021

jrodewig added the v7.13.5 label Jul 21, 2021

jrodewig mentioned this pull request Jul 21, 2021

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

Merged

jakelandis added v8.0.0-alpha1 and removed v8.0.0 labels Jul 26, 2021

probakowski added v7.14.0 and removed v7.14.1 labels Jul 27, 2021

		both this parameter and the `Accept` HTTP header, the API only uses this
		parameter.

	(Optional, array) Values for variables in the `query`. For variable syntax, see
	(Optional, array) Values for parameters in the `query`. For variable syntax, see

[DOCS] SQL: Add formal API docs #75506

[DOCS] SQL: Add formal API docs #75506

Uh oh!

Conversation

jrodewig commented Jul 19, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview

Uh oh!

elasticmachine commented Jul 20, 2021

Uh oh!

elasticmachine commented Jul 20, 2021

Uh oh!

elasticmachine commented Jul 20, 2021

Uh oh!

Uh oh!

sethmlarson left a comment

Choose a reason for hiding this comment

Uh oh!

bpintea left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jrodewig Jul 20, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jrodewig Jul 20, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jrodewig commented Jul 20, 2021

Uh oh!

jrodewig commented Jul 20, 2021

Uh oh!

bpintea left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

jrodewig commented Jul 19, 2021 •

edited

Loading

jrodewig Jul 20, 2021 •

edited

Loading

jrodewig Jul 20, 2021 •

edited

Loading