Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restructure ES|QL docs #100806

Merged
merged 13 commits into from
Oct 17, 2023
Merged

Restructure ES|QL docs #100806

merged 13 commits into from
Oct 17, 2023

Conversation

abdonpijpelink
Copy link
Contributor

@abdonpijpelink abdonpijpelink commented Oct 13, 2023 •
edited
Loading

Restructures the ES|QL documentation, modelled after the SQL and EQL docs.

  • Moves commands, functions, and operator to one section, with an overview page that lists all of them. Instead of having each command/function on a separate page, they're now listed on a single page per category.
  • Adds reference docs for the query API and an overview of the API.
  • Breaks out "Limitations" into its own page.
  • Moves syntax, multivalued fields and metadata fields pages under a "Language" page.
  • Adds placeholders for "Getting started" and "Using ES|QL in Kibana" pages.
  • Proposes a standard layout for commands and functions, implemented in this PR for ACOS, CASE, and DATE_PARSE.

Notes for reviewers:

This PR changes a lot of files. Most changes are trivial, but please take a look at:

@github-actions
Copy link
Contributor

Documentation preview:

@abdonpijpelink abdonpijpelink mentioned this pull request Oct 13, 2023
Merged
abdonpijpelink added a commit to elastic/kibana that referenced this pull request Oct 13, 2023
@abdonpijpelink
Temporary link change for ES|QL STATS-BY (#168820)
8a98763 
Temporarily changes the deep link to the documentation for ES|QL
STATS...BY to unblock
elastic/elasticsearch#100806 .

I'll change the link to the new STATS...BY link after
elastic/elasticsearch#100806 merges.
@abdonpijpelink abdonpijpelink requested a review from costin October 13, 2023 14:31
@abdonpijpelink abdonpijpelink marked this pull request as ready for review October 13, 2023 14:31
@elasticsearchmachine elasticsearchmachine added Team:Docs Meta label for docs team Team:QL (Deprecated) Meta label for query languages team labels Oct 13, 2023
@elasticsearchmachine
Copy link
Collaborator

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

@elasticsearchmachine
Copy link
Collaborator

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

@elasticsearchmachine
Copy link
Collaborator

Pinging @elastic/elasticsearch-esql (:Query Languages/ES|QL)

@abdonpijpelink
Copy link
Contributor Author

@elasticmachine merge upstream

@costin costin requested a review from abatsakis October 16, 2023 05:22
dej611 pushed a commit to dej611/kibana that referenced this pull request Oct 17, 2023
@abdonpijpelink @dej611
Temporary link change for ES|QL STATS-BY (elastic#168820)
2161bc4 
Temporarily changes the deep link to the documentation for ES|QL
STATS...BY to unblock
elastic/elasticsearch#100806 .

I'll change the link to the new STATS...BY link after
elastic/elasticsearch#100806 merges.
abatsakis
abatsakis approved these changes Oct 17, 2023
View reviewed changes
Copy link
Contributor

@abatsakis abatsakis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like the "ESQL Language" section title, but I can't think of something better now

costin
costin approved these changes Oct 17, 2023
View reviewed changes
Copy link
Member

@costin costin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.
The structure misses a page on security and the impact it has on the data the users sees.
There is ongoing work around security and enrich that needs to be incorporated (see the work from Nhat).

@abdonpijpelink
Copy link
Contributor Author

I will follow up with a security page (it's an item on the meta issue)

@abdonpijpelink abdonpijpelink merged commit 8ac4ba7 into elastic:main Oct 17, 2023
@abdonpijpelink abdonpijpelink deleted the esql-docs-structure branch October 17, 2023 15:36
@abdonpijpelink abdonpijpelink mentioned this pull request Oct 17, 2023
Merged
@elasticsearchmachine
Copy link
Collaborator

💚 Backport successful

Status Branch Result
✅ 8.11

abdonpijpelink added a commit to abdonpijpelink/elasticsearch that referenced this pull request Oct 17, 2023
@abdonpijpelink @elasticmachine
Restructure ES|QL docs (elastic#100806)
45b2666 
* Break out 'Limitations' into separate page

* Add REST API docs

* Restructure commands, functions, and operators refs

* Add placeholder for getting started guide

* Group 'Syntax', 'Metafields', and 'MV fields' under 'Language'

* Add placeholder for Kibana page

* Add link from landing page

* Apply uniform formatting to ACOS, CASE, and DATE_PARSE function refs

* Reword default LIMIT

* Add support for COUNT(*)

* Move 'Commands' and 'Functions and operators' to individual pages

---------

Co-authored-by: Elastic Machine <[email protected]>
abdonpijpelink added a commit to abdonpijpelink/kibana that referenced this pull request Oct 17, 2023
@abdonpijpelink
Temporary link change for ES|QL STATS-BY (elastic#168820)
ab14390 
Temporarily changes the deep link to the documentation for ES|QL
STATS...BY to unblock
elastic/elasticsearch#100806 .

I'll change the link to the new STATS...BY link after
elastic/elasticsearch#100806 merges.

(cherry picked from commit 8a98763)
abdonpijpelink added a commit to elastic/kibana that referenced this pull request Oct 18, 2023
@abdonpijpelink
[8.11] Temporary link change for ES|QL STATS-BY (#168820) (#169136)
397fe2e 
# Backport

This will backport the following commits from `main` to `8.11`:
- [Temporary link change for ES|QL STATS-BY
(#168820)](#168820)

<!--- Backport version: 8.9.7 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Abdon
Pijpelink","email":"[email protected]"},"sourceCommit":{"committedDate":"2023-10-13T13:22:57Z","message":"Temporary
link change for ES|QL STATS-BY (#168820)\n\nTemporarily changes the deep
link to the documentation for ES|QL\r\nSTATS...BY to
unblock\r\nhttps://github.com/elastic/elasticsearch/pull/100806
.\r\n\r\nI'll change the link to the new STATS...BY link
after\r\nhttps://github.com/elastic/elasticsearch/pull/100806
merges.","sha":"8a98763f588d77bb956fb9579f9543c38ded5b9c","branchLabelMapping":{"^v8.12.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","backport:skip","docs","v8.12.0"],"number":168820,"url":"https://github.com/elastic/kibana/pull/168820","mergeCommit":{"message":"Temporary
link change for ES|QL STATS-BY (#168820)\n\nTemporarily changes the deep
link to the documentation for ES|QL\r\nSTATS...BY to
unblock\r\nhttps://github.com/elastic/elasticsearch/pull/100806
.\r\n\r\nI'll change the link to the new STATS...BY link
after\r\nhttps://github.com/elastic/elasticsearch/pull/100806
merges.","sha":"8a98763f588d77bb956fb9579f9543c38ded5b9c"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v8.12.0","labelRegex":"^v8.12.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/168820","number":168820,"mergeCommit":{"message":"Temporary
link change for ES|QL STATS-BY (#168820)\n\nTemporarily changes the deep
link to the documentation for ES|QL\r\nSTATS...BY to
unblock\r\nhttps://github.com/elastic/elasticsearch/pull/100806
.\r\n\r\nI'll change the link to the new STATS...BY link
after\r\nhttps://github.com/elastic/elasticsearch/pull/100806
merges.","sha":"8a98763f588d77bb956fb9579f9543c38ded5b9c"}}]}]
BACKPORT-->
elasticsearchmachine pushed a commit that referenced this pull request Oct 18, 2023
@abdonpijpelink @elasticmachine
Restructure ES|QL docs (#100806) (#100991)
3d8c143 
* Break out 'Limitations' into separate page

* Add REST API docs

* Restructure commands, functions, and operators refs

* Add placeholder for getting started guide

* Group 'Syntax', 'Metafields', and 'MV fields' under 'Language'

* Add placeholder for Kibana page

* Add link from landing page

* Apply uniform formatting to ACOS, CASE, and DATE_PARSE function refs

* Reword default LIMIT

* Add support for COUNT(*)

* Move 'Commands' and 'Functions and operators' to individual pages

---------

Co-authored-by: Elastic Machine <[email protected]>
This was referenced Oct 23, 2023
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@abatsakis abatsakis abatsakis approved these changes

@costin costin costin approved these changes

Assignees
No one assigned
Labels
:Analytics/ES|QL AKA ESQL >docs General docs changes Team:Docs Meta label for docs team Team:QL (Deprecated) Meta label for query languages team v8.11.1 v8.12.0
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@abdonpijpelink @elasticsearchmachine @costin @abatsakis @elasticmachine