elastic / elasticsearch-py

Official Python client for Elasticsearch
https://ela.st/es-python
Apache License 2.0
4.17k stars 1.17k forks source link

[DOCS] Add ES|QL doc structure #2563

Closed marciw closed 1 month ago

marciw commented 1 month ago

Adds an esql.asciidoc file that sets up a basic structure for the ES|QL documentation. Based on @szabosteve's Java client docs PR (#789).

This includes adding a folder structure for helpers instead of keeping the docs all on one page (but we can undo that).

@pquentin This needs expanding and tailoring for the Python client (it's really just placeholder text from the Java client docs). All other feedback is welcome, especially because I'm still so new to Elastic and to the client docs.

Preview coming soon

github-actions[bot] commented 1 month ago

A documentation preview will be available soon.

Request a new doc build by commenting * Rebuild this PR: `run docs-build` * Rebuild this PR and all Elastic docs: `run docs-build rebuild` `run docs-build` is much faster than `run docs-build rebuild`. A `rebuild` should only be needed in rare situations. If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status [here](https://buildkite.com/elastic/docs-build).
pquentin commented 1 month ago

Thank you @marciw! The main issue here is that Python does not have ES|QL helpers yet and there are no immediate plans to add some. The Java text does not really apply. However I would like to add ES|QL docs. One option would be to add https://www.elastic.co/search-labs/blog/esql-pandas-dataframes-python under "Integrations -> Pandas".

Another option would be to add a new page explaining how to make queries, including the Query DSL and ES|QL. Any thoughts?

marciw commented 1 month ago

The main issue here is that Python does not have ES|QL helpers yet and there are no immediate plans to add some.

Ohhhhhh, ha, thanks for clarifying 👍

One option would be to add https://www.elastic.co/search-labs/blog/esql-pandas-dataframes-python under "Integrations -> Pandas".

This sounds like a great idea in the short term!

Another option would be to add a new page explaining how to make queries, including the Query DSL and ES|QL. Any thoughts?

... and then this sounds like a great idea in the long (or medium) term, at which point we could decide whether to keep the Pandas integration doc with tweaks, or move the content to the new queries page.

WDYT? Either way, I can start the PR(s) w/ some structure and placeholder text, if you like. (Will probably close this one)

pquentin commented 1 month ago

That sounds good! Let's start with the Pandas integration, ideally adding ES|QL in the page title too. Thanks!