diff --git a/explore-analyze/query-filter/languages/esql-rest.md b/explore-analyze/query-filter/languages/esql-rest.md index ce8c3134d4..6f8e437d02 100644 --- a/explore-analyze/query-filter/languages/esql-rest.md +++ b/explore-analyze/query-filter/languages/esql-rest.md @@ -60,26 +60,49 @@ POST /_query?format=txt {{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. +For example: + +```console +POST /_query?format=yaml +``` + ::::{note} 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. :::: +#### Structured formats + +Complete responses with metadata. Useful for automatic parsing. | `format` | HTTP header | Description | | --- | --- | --- | -| Human readable | -| `csv` | `text/csv` | [Comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values) | | `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 | + +#### Tabular formats + +Query results only, without metadata. Useful for quick and manual data previews. + +| `format` | HTTP header | Description | +| --- | --- | --- | +| `csv` | `text/csv` | [Comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values) | | `tsv` | `text/tab-separated-values` | [Tab-separated values](https://en.wikipedia.org/wiki/Tab-separated_values) | | `txt` | `text/plain` | CLI-like representation | -| `yaml` | `application/yaml` | [YAML](https://en.wikipedia.org/wiki/YAML) (YAML Ain’t Markup Language) human-readable format | -| Binary | + +::::{tip} +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. +:::: + +#### Binary formats + +Compact binary encoding. To be used by applications. + +| `format` | HTTP header | Description | +| --- | --- | --- | | `cbor` | `application/cbor` | [Concise Binary Object Representation](https://cbor.io/) | | `smile` | `application/smile` | [Smile](https://en.wikipedia.org/wiki/Smile_(data_interchange_format)) binary data format similarto CBOR | | `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) | -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. - ### Filtering using {{es}} Query DSL [esql-rest-filtering] @@ -322,3 +345,8 @@ Use the [{{esql}} async query delete API](https://www.elastic.co/docs/api/doc/el ```console DELETE /_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI= ``` + +::::{note} +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. +Useful if you use a tabular text format like `txt`, `csv` or `tsv`, as you won't receive those fields in the body there. +::::