From 9b9e6a0144b68d09a0b6f82d92dbaa04d29085d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Cea=20Fontenla?= Date: Tue, 29 Jul 2025 14:44:01 +0200 Subject: [PATCH 1/5] ESQL: Update text formats documentation --- explore-analyze/query-filter/languages/esql-rest.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/explore-analyze/query-filter/languages/esql-rest.md b/explore-analyze/query-filter/languages/esql-rest.md index ce8c3134d4..89fa411b56 100644 --- a/explore-analyze/query-filter/languages/esql-rest.md +++ b/explore-analyze/query-filter/languages/esql-rest.md @@ -64,15 +64,21 @@ POST /_query?format=txt 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. :::: +::::{tip} +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. +:::: + | `format` | HTTP header | Description | | --- | --- | --- | -| Human readable | -| `csv` | `text/csv` | [Comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values) | +| Structured | | `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 | +| `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 | | `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 | From 8e376d71f4214b8cb537c4385ff21a353d75866e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Cea=20Fontenla?= Date: Tue, 29 Jul 2025 16:15:51 +0200 Subject: [PATCH 2/5] Moved tip to table description column --- explore-analyze/query-filter/languages/esql-rest.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/explore-analyze/query-filter/languages/esql-rest.md b/explore-analyze/query-filter/languages/esql-rest.md index 89fa411b56..f722632875 100644 --- a/explore-analyze/query-filter/languages/esql-rest.md +++ b/explore-analyze/query-filter/languages/esql-rest.md @@ -64,22 +64,17 @@ POST /_query?format=txt 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. :::: -::::{tip} -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. -:::: - | `format` | HTTP header | Description | | --- | --- | --- | -| Structured | +| Structured | | _Complete response with metadata_ | | `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 | +| Tabular | | _Query results only, no metadata_ | | `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 | -| Binary | +| Binary | | _Compact binary encoding_ | | `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) | From 9b7e41ded0dc83814545317d1521d71f6b781db3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Cea=20Fontenla?= Date: Tue, 29 Jul 2025 16:25:52 +0200 Subject: [PATCH 3/5] Divided into 3 tables --- .../query-filter/languages/esql-rest.md | 24 ++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/explore-analyze/query-filter/languages/esql-rest.md b/explore-analyze/query-filter/languages/esql-rest.md index f722632875..cdd4f6d29c 100644 --- a/explore-analyze/query-filter/languages/esql-rest.md +++ b/explore-analyze/query-filter/languages/esql-rest.md @@ -64,23 +64,41 @@ POST /_query?format=txt 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 | | --- | --- | --- | | Structured | | _Complete response with metadata_ | | `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 | +| --- | --- | --- | | Tabular | | _Query results only, no metadata_ | | `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 | -| Binary | | _Compact binary encoding_ | + +::::{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] From f5293c058f51eaf745649a00b734cee5e6a60cc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Cea=20Fontenla?= Date: Tue, 29 Jul 2025 16:45:37 +0200 Subject: [PATCH 4/5] Added async headers info --- explore-analyze/query-filter/languages/esql-rest.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/explore-analyze/query-filter/languages/esql-rest.md b/explore-analyze/query-filter/languages/esql-rest.md index cdd4f6d29c..d765eae2f3 100644 --- a/explore-analyze/query-filter/languages/esql-rest.md +++ b/explore-analyze/query-filter/languages/esql-rest.md @@ -70,7 +70,6 @@ Complete responses with metadata. Useful for automatic parsing. | `format` | HTTP header | Description | | --- | --- | --- | -| Structured | | _Complete response with metadata_ | | `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 | @@ -80,7 +79,6 @@ Query results only, without metadata. Useful for quick and manual data previews. | `format` | HTTP header | Description | | --- | --- | --- | -| Tabular | | _Query results only, no metadata_ | | `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 | @@ -341,3 +339,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. +:::: From 88a63b128ce31916daeebbe9c66ad8e02e06e440 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Cea=20Fontenla?= Date: Tue, 29 Jul 2025 17:38:56 +0200 Subject: [PATCH 5/5] Add a format explicit example --- explore-analyze/query-filter/languages/esql-rest.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/explore-analyze/query-filter/languages/esql-rest.md b/explore-analyze/query-filter/languages/esql-rest.md index d765eae2f3..6f8e437d02 100644 --- a/explore-analyze/query-filter/languages/esql-rest.md +++ b/explore-analyze/query-filter/languages/esql-rest.md @@ -60,6 +60,12 @@ 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. ::::