ESQL: Update text formats documentation #2307
Conversation
🔍 Preview links for changed docs |
| In the "Tabular" formats, only the resulting data will be returned. Other response fields will be missing. | ||
| Use them when you want a quick view of the results. |
There was a problem hiding this comment.
This reads a bit weird to me; looking for suggestions
There was a problem hiding this comment.
It's fine with me. And lines up with my feelings about that format. Great for seeing the results in a dense way as a human being. CSV may even be good out of curl too. But "applications" should use json.
| In the "Tabular" formats, only the resulting data will be returned. Other response fields will be missing. | ||
| Use them when you want a quick view of the results. |
There was a problem hiding this comment.
It's fine with me. And lines up with my feelings about that format. Great for seeing the results in a dense way as a human being. CSV may even be good out of curl too. But "applications" should use json.
|
@ivancea maybe you just add descriptions of what each category means directly in the table, and cut down on the admonitions:
|
There was a problem hiding this comment.
Looks great now, and super helpful.
Optional addition suggestion:
I was thinking at the start of this section, we could just have an example of how to set the format in Console after we say You can set the format by specifying the format parameter in the URL or by setting the Accept or Content-Type HTTP header.
For example:
POST /_query?format=txt| | `json` | `application/json` | [JSON](https://www.json.org/) (JavaScript Object Notation) human-readable format | | ||
| | `yaml` | `application/yaml` | [YAML](https://en.wikipedia.org/wiki/YAML) (YAML Ain’t Markup Language) human-readable format | |
There was a problem hiding this comment.
| | `yaml` | `application/yaml` | [YAML](https://en.wikipedia.org/wiki/YAML) (YAML Ain’t Markup Language) human-readable format | | |
| | `yaml` | `application/yaml` | [YAML](https://en.wikipedia.org/wiki/YAML) human-readable format | |
nit: not sure if it's useful to provide the recursive acronym 😄
There was a problem hiding this comment.
I also don't think it adds much, but we have it in every other format, so I'd say to keep it, even if just for normalization and flavor 👀
There was a problem hiding this comment.
nothing wrong with a bit of flavor 🫡
Spec docs update for the ESQL `format` parameter. Text formats result in missing metadata in the response body. Main docs change: elastic/docs-content#2307
Spec docs update for the ESQL `format` parameter. Text formats result in missing metadata in the response body. Main docs change: elastic/docs-content#2307 (cherry picked from commit a04b872)
Spec docs update for the ESQL `format` parameter. Text formats result in missing metadata in the response body. Main docs change: elastic/docs-content#2307 (cherry picked from commit a04b872) Co-authored-by: Iván Cea Fontenla <[email protected]>
Spec docs update for the ESQL `format` parameter. Text formats result in missing metadata in the response body. Main docs change: elastic/docs-content#2307 (cherry picked from commit a04b872)
Spec docs update for the ESQL `format` parameter. Text formats result in missing metadata in the response body. Main docs change: elastic/docs-content#2307 (cherry picked from commit a04b872)
Spec docs update for the ESQL `format` parameter. Text formats result in missing metadata in the response body. Main docs change: elastic/docs-content#2307 (cherry picked from commit a04b872)
Spec docs update for the ESQL `format` parameter. Text formats result in missing metadata in the response body. Main docs change: elastic/docs-content#2307 (cherry picked from commit a04b872)
Separated the ESQL endpoint formats docs in 3 blocks: Structured, Tabular and Binary (Open to suggestions for the names here).
Initially, it was only "Human readable" and "Binary". But CSV, TSV and TXT are different from JSON and YAML, as they don't show all the results, only the query results as a table (For example, no "took" or "is_partial" fields).
API specification change: elastic/elasticsearch-specification#5054