docs/usage/searching.asciidoc

@@ -43,4 +43,29 @@ include-tagged::{doc-tests-src}/usage/SearchingTest.java[search-nested]
 <4> The search query is a boolean query that combines the text search and max price queries.
 <5> Both queries are added as `must` as we want results to match all criteria.
 
+[discrete]
+==== Templated search
+
+A search template is a stored search that you can run with different variables. Search templates let you change your searches without modifying your application code.
+
+Before running a template search, you first have to create the template. This is a stored script that returns the search request body, and is usually defined as a Mustache template. This stored script can be created outside the application, and also with the {java-client}:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/SearchingTest.java[search-template-script]
+--------------------------------------------------
+<1> Identifier of the template script to create.
+
+To use the search template, use the `searchTemplate` method to refer to the script and provide values for its parameters:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/SearchingTest.java[search-template-query]
+--------------------------------------------------
+<1> Identifier of the template script to use.
+<2> Template parameter values.
+
+For more in-depth information, see the {es-docs}/search-template.html[{es} search template documentation].
+
+
 {doc-tests-blurb}

java-client/src/main/java/co/elastic/clients/ApiClient.java

@@ -26,6 +26,7 @@
 import co.elastic.clients.json.JsonpMapperBase;
 
 import javax.annotation.Nullable;
+import java.util.function.Function;
 
 public abstract class ApiClient<T extends Transport, Self extends ApiClient<T, Self>> {
 
@@ -52,15 +53,27 @@ protected <V> JsonpDeserializer<V> getDeserializer(Class<V> clazz) {
      */
     public abstract Self withTransportOptions(@Nullable TransportOptions transportOptions);
 
+    /**
+     * Creates a new client with additional request options
+     *
+     * @param fn a lambda expression that takes the current options as input
+     */
+    public Self withTransportOptions(Function<TransportOptions.Builder, TransportOptions.Builder> fn) {
+        return withTransportOptions(fn.apply(_transportOptions().toBuilder()).build());
+    }
+
     /**
      * Get the transport used by this client to handle communication with the server.
      */
     public T _transport() {
         return this.transport;
     }
 
+    /**
+     * Get the transport options used for this client. If the client has no custom options, falls back to the transport's options.
+     */
     public TransportOptions _transportOptions() {
-        return this.transportOptions;
+        return this.transportOptions == null ? transport.options() : transportOptions;
     }
 
     /**

java-client/src/main/java/co/elastic/clients/elasticsearch/_types/SortOptions.java

@@ -56,9 +56,6 @@
 @JsonpDeserializable
 public class SortOptions implements TaggedUnion<SortOptions.Kind, Object>, JsonpSerializable {
 
-	/**
-	 * {@link SortOptions} variant kinds.
-	 */
 	/**
 	 * {@link SortOptions} variant kinds.
 	 * 

java-client/src/main/java/co/elastic/clients/elasticsearch/_types/Time.java

@@ -43,7 +43,7 @@
 import java.util.function.Function;
 import javax.annotation.Nullable;
 
-// typedef: _types.Time
+// typedef: _types.Duration
 
 /**
  * Whenever durations need to be specified, e.g. for a timeout parameter, the
@@ -52,7 +52,8 @@
  * @see <a href=
  *      "https://github.com/elastic/elasticsearch/blob/master/libs/core/src/main/java/org/elasticsearch/core/TimeValue.java">Documentation
  *      on elastic.co</a>
- * @see <a href="../doc-files/api-spec.html#_types.Time">API specification</a>
+ * @see <a href="../doc-files/api-spec.html#_types.Duration">API
+ *      specification</a>
  */
 @JsonpDeserializable
 public class Time implements TaggedUnion<Time.Kind, Object>, JsonpSerializable {

java-client/src/main/java/co/elastic/clients/elasticsearch/_types/Transform.java

@@ -53,9 +53,6 @@
 @JsonpDeserializable
 public class Transform implements TaggedUnion<Transform.Kind, Object>, JsonpSerializable {
 
-	/**
-	 * {@link Transform} variant kinds.
-	 */
 	/**
 	 * {@link Transform} variant kinds.
 	 * 

java-client/src/main/java/co/elastic/clients/elasticsearch/_types/aggregations/Aggregate.java

@@ -24,6 +24,7 @@
 package co.elastic.clients.elasticsearch._types.aggregations;
 
 import co.elastic.clients.json.ExternallyTaggedUnion;
+import co.elastic.clients.json.JsonData;
 import co.elastic.clients.json.JsonEnum;
 import co.elastic.clients.json.JsonpDeserializable;
 import co.elastic.clients.json.JsonpDeserializer;
@@ -34,9 +35,10 @@
 import co.elastic.clients.util.ApiTypeHelper;
 import co.elastic.clients.util.ObjectBuilder;
 import co.elastic.clients.util.ObjectBuilderBase;
-import co.elastic.clients.util.TaggedUnion;
+import co.elastic.clients.util.OpenTaggedUnion;
 import co.elastic.clients.util.TaggedUnionUtils;
 import jakarta.json.stream.JsonGenerator;
+import java.lang.Object;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Objects;
@@ -52,11 +54,8 @@
  *      specification</a>
  */
 
-public class Aggregate implements TaggedUnion<Aggregate.Kind, AggregateVariant>, JsonpSerializable {
+public class Aggregate implements OpenTaggedUnion<Aggregate.Kind, Object>, JsonpSerializable {
 
-	/**
-	 * {@link Aggregate} variant kinds.
-	 */
 	/**
 	 * {@link Aggregate} variant kinds.
 	 * 
@@ -198,6 +197,9 @@ public enum Kind implements JsonEnum {
 
 		WeightedAvg("weighted_avg"),
 
+		/** A custom {@code Aggregate} defined by a plugin */
+		_Custom(null)
+
 		;
 
 		private final String jsonValue;
@@ -213,36 +215,48 @@ public String jsonValue() {
 	}
 
 	private final Kind _kind;
-	private final AggregateVariant _value;
+	private final Object _value;
 
 	@Override
 	public final Kind _kind() {
 		return _kind;
 	}
 
 	@Override
-	public final AggregateVariant _get() {
+	public final Object _get() {
 		return _value;
 	}
 
 	public Aggregate(AggregateVariant value) {
 
 		this._kind = ApiTypeHelper.requireNonNull(value._aggregateKind(), this, "<variant kind>");
 		this._value = ApiTypeHelper.requireNonNull(value, this, "<variant value>");
+		this._customKind = null;
 
 	}
 
 	private Aggregate(Builder builder) {
 
 		this._kind = ApiTypeHelper.requireNonNull(builder._kind, builder, "<variant kind>");
 		this._value = ApiTypeHelper.requireNonNull(builder._value, builder, "<variant value>");
+		this._customKind = builder._customKind;
 
 	}
 
 	public static Aggregate of(Function<Builder, ObjectBuilder<Aggregate>> fn) {
 		return fn.apply(new Builder()).build();
 	}
 
+	/**
+	 * Build a custom plugin-defined {@code Aggregate}, given its kind and some JSON
+	 * data
+	 */
+	public Aggregate(String kind, JsonData value) {
+		this._kind = Kind._Custom;
+		this._value = value;
+		this._customKind = kind;
+	}
+
 	/**
 	 * Is this variant instance of kind {@code adjacency_matrix}?
 	 */
@@ -1379,6 +1393,35 @@ public WeightedAvgAggregate weightedAvg() {
 		return TaggedUnionUtils.get(this, Kind.WeightedAvg);
 	}
 
+	@Nullable
+	private final String _customKind;
+
+	/**
+	 * Is this a custom {@code Aggregate} defined by a plugin?
+	 */
+	public boolean _isCustom() {
+		return _kind == Kind._Custom;
+	}
+
+	/**
+	 * Get the actual kind when {@code _kind()} equals {@link Kind#_Custom}
+	 * (plugin-defined variant).
+	 */
+	@Nullable
+	public final String _customKind() {
+		return _customKind;
+	}
+
+	/**
+	 * Get the custom plugin-defined variant value.
+	 *
+	 * @throws IllegalStateException
+	 *             if the current variant is not {@link Kind#_Custom}.
+	 */
+	public JsonData _custom() {
+		return TaggedUnionUtils.get(this, Kind._Custom);
+	}
+
 	@Override
 	public void serialize(JsonGenerator generator, JsonpMapper mapper) {
 
@@ -1393,7 +1436,8 @@ public String toString() {
 
 	public static class Builder extends ObjectBuilderBase implements ObjectBuilder<Aggregate> {
 		private Kind _kind;
-		private AggregateVariant _value;
+		private Object _value;
+		private String _customKind;
 
 		public ObjectBuilder<Aggregate> adjacencyMatrix(AdjacencyMatrixAggregate v) {
 			this._kind = Kind.AdjacencyMatrix;
@@ -2109,6 +2153,22 @@ public ObjectBuilder<Aggregate> weightedAvg(
 			return this.weightedAvg(fn.apply(new WeightedAvgAggregate.Builder()).build());
 		}
 
+		/**
+		 * Define this {@code Aggregate} as a plugin-defined variant.
+		 *
+		 * @param name
+		 *            the plugin-defined identifier
+		 * @param data
+		 *            the data for this custom {@code Aggregate}. It is converted
+		 *            internally to {@link JsonData}.
+		 */
+		public ObjectBuilder<Aggregate> _custom(String name, Object data) {
+			this._kind = Kind._Custom;
+			this._customKind = name;
+			this._value = JsonData.of(data);
+			return this;
+		}
+
 		public Aggregate build() {
 			_checkSingleUse();
 			return new Aggregate(this);
@@ -2187,7 +2247,7 @@ public Aggregate build() {
 		deserializers.put("variable_width_histogram", VariableWidthHistogramAggregate._DESERIALIZER);
 		deserializers.put("weighted_avg", WeightedAvgAggregate._DESERIALIZER);
 
-		_TYPED_KEYS_DESERIALIZER = new ExternallyTaggedUnion.Deserializer<>(deserializers,
-				(name, value) -> new Aggregate(value)).typedKeys();
+		_TYPED_KEYS_DESERIALIZER = new ExternallyTaggedUnion.Deserializer<>(deserializers, Aggregate::new,
+				Aggregate::new).typedKeys();
 	}
 }