From 0cf5c7c79dea9c00d2263ced492bf431102f010d Mon Sep 17 00:00:00 2001 From: "Jihyun(Brian) Jeong" Date: Mon, 23 Jun 2025 16:34:57 +1000 Subject: [PATCH] (Doc+) Add typed_keys parameter set as true ### Description This PR Add `typed_keys` parameter set as `true`: - a `JsonException` that occurs when using aggregations with `SearchTemplateAsync` because the mandatory `typed_keys=true` parameter is undocumented. - This change improves the developer experience by preventing user confusion and saving significant debugging time when using search templates. ### Related issues - https://github.com/elastic/elasticsearch-net/issues/7605#issuecomment-1501825118 - https://github.com/elastic/sdh-search/issues/1648#issuecomment-2990317960 --- docs/usage/aggregations.asciidoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index 1f159763aaa..8e8537fced5 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -3,6 +3,22 @@ This page demonstrates how to use aggregations. +[discrete] +=== Using Aggregations with Search Templates + +[IMPORTANT] +.A Note on `typed_keys` and `SearchTemplateAsync` +==== +When using aggregations with the `SearchTemplateAsync` API, it is **mandatory** to include the `typed_keys: true` parameter in your request. + +Unlike the `SearchAsync` API, which adds the `typed_keys=true` parameter to requests automatically, the `SearchTemplateAsync` API cannot do so due to the flexible nature of search templates. + +If this parameter is omitted, the client's deserializer will fail with a `JsonException` as it cannot determine the aggregation types from the response. +==== + +To correctly receive aggregations from a search template, you must explicitly include `typed_keys: true` in the parameters you provide to the `SearchTemplateAsync` call. + + [discrete] === Top-level aggreggation