Skip to content

Commit a6551af

Browse files
authored
ESQL: Update text formats documentation (#2307)
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
1 parent c5f6b13 commit a6551af

File tree

1 file changed

+34
-6
lines changed

1 file changed

+34
-6
lines changed

explore-analyze/query-filter/languages/esql-rest.md

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -60,26 +60,49 @@ POST /_query?format=txt
6060

6161
{{esql}} can return the data in the following human readable and binary formats. You can set the format by specifying the `format` parameter in the URL or by setting the `Accept` or `Content-Type` HTTP header.
6262

63+
For example:
64+
65+
```console
66+
POST /_query?format=yaml
67+
```
68+
6369
::::{note}
6470
The URL parameter takes precedence over the HTTP headers. If neither is specified then the response is returned in the same format as the request.
6571
::::
6672

73+
#### Structured formats
74+
75+
Complete responses with metadata. Useful for automatic parsing.
6776

6877
| `format` | HTTP header | Description |
6978
| --- | --- | --- |
70-
| Human readable |
71-
| `csv` | `text/csv` | [Comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values) |
7279
| `json` | `application/json` | [JSON](https://www.json.org/) (JavaScript Object Notation) human-readable format |
80+
| `yaml` | `application/yaml` | [YAML](https://en.wikipedia.org/wiki/YAML) (YAML Ain’t Markup Language) human-readable format |
81+
82+
#### Tabular formats
83+
84+
Query results only, without metadata. Useful for quick and manual data previews.
85+
86+
| `format` | HTTP header | Description |
87+
| --- | --- | --- |
88+
| `csv` | `text/csv` | [Comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values) |
7389
| `tsv` | `text/tab-separated-values` | [Tab-separated values](https://en.wikipedia.org/wiki/Tab-separated_values) |
7490
| `txt` | `text/plain` | CLI-like representation |
75-
| `yaml` | `application/yaml` | [YAML](https://en.wikipedia.org/wiki/YAML) (YAML Ain’t Markup Language) human-readable format |
76-
| Binary |
91+
92+
::::{tip}
93+
The `csv` format accepts a formatting URL query attribute, `delimiter`, which indicates which character should be used to separate the CSV values. It defaults to comma (`,`) and cannot take any of the following values: double quote (`"`), carriage-return (`\r`) and new-line (`\n`). The tab (`\t`) can also not be used. Use the `tsv` format instead.
94+
::::
95+
96+
#### Binary formats
97+
98+
Compact binary encoding. To be used by applications.
99+
100+
| `format` | HTTP header | Description |
101+
| --- | --- | --- |
77102
| `cbor` | `application/cbor` | [Concise Binary Object Representation](https://cbor.io/) |
78103
| `smile` | `application/smile` | [Smile](https://en.wikipedia.org/wiki/Smile_(data_interchange_format)) binary data format similarto CBOR |
79104
| `arrow` | `application/vnd.apache.arrow.stream` | **Experimental.** [Apache Arrow](https://arrow.apache.org/) dataframes, [IPC streaming format](https://arrow.apache.org/docs/format/Columnar.html#ipc-streaming-format) |
80105

81-
The `csv` format accepts a formatting URL query attribute, `delimiter`, which indicates which character should be used to separate the CSV values. It defaults to comma (`,`) and cannot take any of the following values: double quote (`"`), carriage-return (`\r`) and new-line (`\n`). The tab (`\t`) can also not be used. Use the `tsv` format instead.
82-
83106

84107
### Filtering using {{es}} Query DSL [esql-rest-filtering]
85108

@@ -322,3 +345,8 @@ Use the [{{esql}} async query delete API](https://www.elastic.co/docs/api/doc/el
322345
```console
323346
DELETE /_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=
324347
```
348+
349+
::::{note}
350+
You will also receive the async ID and running status in the `X-Elasticsearch-Async-Id` and `X-Elasticsearch-Async-Is-Running` HTTP headers of the response, respectively.
351+
Useful if you use a tabular text format like `txt`, `csv` or `tsv`, as you won't receive those fields in the body there.
352+
::::

0 commit comments

Comments
 (0)