From 9fb09ba218928d3a83005f67e574748c7a8bbf34 Mon Sep 17 00:00:00 2001 From: Stacey Salamon <76741798+smsalamon@users.noreply.github.com> Date: Thu, 27 Oct 2022 18:14:27 +0200 Subject: [PATCH] Add filter_path parameter and restructure article (#1658) * Add filter_path parameter and restructure article Signed-off-by: smsalamon * Add line break after headers Signed-off-by: smsalamon * Change formatting Signed-off-by: smsalamon * Update _opensearch/common-parameters.md Add cURL example for content_type Co-authored-by: Alice Williams <88908598+alicejw-aws@users.noreply.github.com> Signed-off-by: smsalamon Co-authored-by: Alice Williams <88908598+alicejw-aws@users.noreply.github.com> Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _opensearch/common-parameters.md | 85 +++++++++++++++++++++++++++++--- 1 file changed, 78 insertions(+), 7 deletions(-) diff --git a/_opensearch/common-parameters.md b/_opensearch/common-parameters.md index 2fd8b335..bedd7385 100644 --- a/_opensearch/common-parameters.md +++ b/_opensearch/common-parameters.md @@ -8,10 +8,81 @@ nav_order: 93 OpenSearch supports the following parameters for all REST operations: -Option | Description | Example -:--- | :--- | :--- -Human-readable output | To convert output units to human-readable values (for example, `1h` for 1 hour and `1kb` for 1,024 bytes), add `?human=true` to the request URL. | `GET /_search?human=true` -Pretty result | To get back JSON responses in a readable format, add `?pretty=true` to the request URL. | `GET /_search?pretty=true` -Content type | To specify the type of content in the request body, use the `Content-Type` key name in the request header. Most operations support JSON, YAML, and CBOR formats. | `POST _scripts/ -H 'Content-Type: application/json` -Request body in query string | If the client library does not accept a request body for non-POST requests, use the `source` query string parameter to pass the request body. Also, specify the `source_content_type` parameter with a supported media type such as `application/json`. | `GET _search?source_content_type=application/json&source={"query":{"match_all":{}}}` -Stack traces | To include the error stack trace in the response when an exception is raised, add `error_trace=true` to the request URL.

When the configuration setting `http.detailed_errors.enabled` is set to `false` in opensearch.yml, `error_trace=true` will not contain a detailed error message.| `GET /_search?error_trace=true` +## Human-readable output + +To convert output units to human-readable values (for example, `1h` for 1 hour and `1kb` for 1,024 bytes), add `?human=true` to the request URL. + +### Sample request + +The following request requires response values to be in human-readable format: + +```json + +GET /_search?human=true +``` + +## Pretty result + +To get back JSON responses in a readable format, add `?pretty=true` to the request URL. + +### Sample request + +The following request requires the response to be displayed in pretty JSON format: + +```json + +GET /_search?pretty=true +``` + +## Content type + +To specify the type of content in the request body, use the `Content-Type` key name in the request header. Most operations support JSON, YAML, and CBOR formats. + +### Sample request + +The following request specifies JSON format for the request body: + +```json + +curl -H "Content-type: application/json" -XGET localhost:9200/_scripts/ +``` + +## Request body in query string + +If the client library does not accept a request body for non-POST requests, use the `source` query string parameter to pass the request body. Also, specify the `source_content_type` parameter with a supported media type such as `application/json`. + + +### Sample request + +The following request searches the documents in the `shakespeare` index for a specific field and value: + +```json + +GET shakespeare/search?source={"query":{"exists":{"field":"speaker"}}}&source_content_type=application/json +``` + +## Stack traces + +To include the error stack trace in the response when an exception is raised, add `error_trace=true` to the request URL. + +### Sample request + +The following request sets `error_trace` to `true` so that the response returns exception-triggered errors: + +```json + +GET /_search?error_trace=true +``` + +## Filtered responses + +To reduce the response size use the `filter_path` parameter to filter the fields that are returned. This parameter takes a comma-separated list of filters. It supports using wildcards to match any field or part of a field's name. You can also exclude fields with `-`. + +### Sample request + +The following request specifies filters to limit the fields returned in the response: + +```json + +GET _search?filter_path=.*,- +```