From 2333f38d9d98eb4fee98aaf913d555d1d33f82f1 Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Tue, 30 Apr 2024 19:35:07 +0200 Subject: [PATCH] Add EQ|QL version support with its default value (#791) --- .../_helpers/esql/EsqlHelper.java | 22 +++-- .../esql/ElasticsearchEsqlAsyncClient.java | 19 ++++- .../esql/ElasticsearchEsqlClient.java | 19 ++++- .../elasticsearch/esql/EsqlVersion.java | 84 +++++++++++++++++++ .../elasticsearch/esql/QueryRequest.java | 34 ++++++++ .../ElasticsearchTestServer.java | 4 +- .../esql/EsqlAdapterEndToEndTest.java | 4 +- .../_helpers/esql/EsqlVersionTest.java | 52 ++++++++++++ .../spec_issues/SpecIssuesTest.java | 1 + 9 files changed, 228 insertions(+), 11 deletions(-) create mode 100644 java-client/src/main/java/co/elastic/clients/elasticsearch/esql/EsqlVersion.java create mode 100644 java-client/src/test/java/co/elastic/clients/elasticsearch/_helpers/esql/EsqlVersionTest.java diff --git a/java-client/src/main-flavored/java/co/elastic/clients/elasticsearch/_helpers/esql/EsqlHelper.java b/java-client/src/main-flavored/java/co/elastic/clients/elasticsearch/_helpers/esql/EsqlHelper.java index a57afcdb3..8b26b4824 100644 --- a/java-client/src/main-flavored/java/co/elastic/clients/elasticsearch/_helpers/esql/EsqlHelper.java +++ b/java-client/src/main-flavored/java/co/elastic/clients/elasticsearch/_helpers/esql/EsqlHelper.java @@ -22,6 +22,7 @@ import co.elastic.clients.elasticsearch._types.FieldValue; import co.elastic.clients.elasticsearch.esql.ElasticsearchEsqlAsyncClient; import co.elastic.clients.elasticsearch.esql.ElasticsearchEsqlClient; +import co.elastic.clients.elasticsearch.esql.EsqlVersion; import co.elastic.clients.elasticsearch.esql.QueryRequest; import co.elastic.clients.json.JsonData; import co.elastic.clients.transport.endpoints.BinaryResponse; @@ -36,9 +37,9 @@ public class EsqlHelper { //----- Synchronous public static T query( - ElasticsearchEsqlClient client, EsqlAdapter adapter, String query, Object... params + ElasticsearchEsqlClient client, EsqlVersion version, EsqlAdapter adapter, String query, Object... params ) throws IOException { - QueryRequest request = buildRequest(adapter, query, params); + QueryRequest request = buildRequest(version, adapter, query, params); BinaryResponse response = client.query(request); return adapter.deserialize(client, request, response); } @@ -52,9 +53,9 @@ public static T query(ElasticsearchEsqlClient client, EsqlAdapter adapter //----- Asynchronous public static CompletableFuture queryAsync( - ElasticsearchEsqlAsyncClient client, EsqlAdapter adapter, String query, Object... params + ElasticsearchEsqlAsyncClient client, EsqlVersion version, EsqlAdapter adapter, String query, Object... params ) { - return doQueryAsync(client, adapter, buildRequest(adapter, query, params)); + return doQueryAsync(client, adapter, buildRequest(version, adapter, query, params)); } public static CompletableFuture queryAsync( @@ -79,9 +80,19 @@ private static CompletableFuture doQueryAsync( //----- Utilities - private static QueryRequest buildRequest(EsqlAdapter adapter, String query, Object... params) { + private static QueryRequest buildRequest(EsqlVersion version, EsqlAdapter adapter, String query, Object... params) { + if (version == null) { + version = EsqlVersion.getDefault(); + } + if (version == null) { + throw new IllegalStateException( + "ES|QL default version not set. Either specify it explicitly or set a default value"); + } + EsqlVersion v = version; + return QueryRequest.of(esql -> esql .format(adapter.format()) + .version(v) .columnar(adapter.columnar()) .query(query) .params(asFieldValues(params)) @@ -99,6 +110,7 @@ private static QueryRequest buildRequest(EsqlAdapter adapter, QueryRequest re .locale(request.locale()) .params(request.params()) .query(request.query()) + .version(request.version()) ); } diff --git a/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/ElasticsearchEsqlAsyncClient.java b/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/ElasticsearchEsqlAsyncClient.java index 5bc1b79fd..b9bb666d5 100644 --- a/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/ElasticsearchEsqlAsyncClient.java +++ b/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/ElasticsearchEsqlAsyncClient.java @@ -111,7 +111,24 @@ public final CompletableFuture query( * values for query parameters, if any */ public final CompletableFuture query(EsqlAdapter adapter, String query, Object... parameters) { - return EsqlHelper.queryAsync(this, adapter, query, parameters); + return EsqlHelper.queryAsync(this, null, adapter, query, parameters); + } + + /** + * Executes an ES|QL request and adapts its result to a target type. + * + * @param version + * the ES|QL language version + * @param adapter + * the ES|QL response adapter + * @param query + * the ES|QL query + * @param parameters + * values for query parameters, if any + */ + public final CompletableFuture query(EsqlVersion version, EsqlAdapter adapter, String query, + Object... parameters) { + return EsqlHelper.queryAsync(this, version, adapter, query, parameters); } /** diff --git a/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/ElasticsearchEsqlClient.java b/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/ElasticsearchEsqlClient.java index 93cbebacc..e44c20f80 100644 --- a/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/ElasticsearchEsqlClient.java +++ b/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/ElasticsearchEsqlClient.java @@ -113,7 +113,24 @@ public final BinaryResponse query(Function T query(EsqlAdapter adapter, String query, Object... parameters) throws IOException, ElasticsearchException { - return EsqlHelper.query(this, adapter, query, parameters); + return EsqlHelper.query(this, null, adapter, query, parameters); + } + + /** + * Executes an ES|QL request and adapts its result to a target type. + * + * @param version + * the ES|QL language version + * @param adapter + * the ES|QL response adapter + * @param query + * the ES|QL query + * @param parameters + * values for query parameters, if any + */ + public final T query(EsqlVersion version, EsqlAdapter adapter, String query, Object... parameters) + throws IOException, ElasticsearchException { + return EsqlHelper.query(this, version, adapter, query, parameters); } /** diff --git a/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/EsqlVersion.java b/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/EsqlVersion.java new file mode 100644 index 000000000..39cbb214e --- /dev/null +++ b/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/EsqlVersion.java @@ -0,0 +1,84 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package co.elastic.clients.elasticsearch.esql; + +import co.elastic.clients.json.JsonEnum; +import co.elastic.clients.json.JsonpDeserializable; +import co.elastic.clients.json.JsonpDeserializer; + +//---------------------------------------------------------------- +// THIS CODE IS GENERATED. MANUAL EDITS WILL BE LOST. +//---------------------------------------------------------------- +// +// This code is generated from the Elasticsearch API specification +// at https://github.com/elastic/elasticsearch-specification +// +// Manual updates to this file will be lost when the code is +// re-generated. +// +// If you find a property that is missing or wrongly typed, please +// open an issue or a PR on the API specification repository. +// +//---------------------------------------------------------------- + +/** + * + * @see API + * specification + */ +@JsonpDeserializable +public enum EsqlVersion implements JsonEnum { + /** + * Run against the first version of ES|QL. + */ + V2024_04_01("2024.04.01"), + + ; + + private final String jsonValue; + + EsqlVersion(String jsonValue) { + this.jsonValue = jsonValue; + } + + public String jsonValue() { + return this.jsonValue; + } + + private static EsqlVersion DEFAULT_VERSION = V2024_04_01; + + /** + * The default ES|QL language version used when not explicitly specified. + */ + public static EsqlVersion getDefault() { + return DEFAULT_VERSION; + } + + /** + * Set the default ES|QL language version to be used. This is a global + * application-wide setting. + */ + public static void setDefault(EsqlVersion version) { + DEFAULT_VERSION = version; + } + + public static final JsonEnum.Deserializer _DESERIALIZER = new JsonEnum.Deserializer<>( + EsqlVersion.values()); +} diff --git a/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/QueryRequest.java b/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/QueryRequest.java index 68f52f6ae..ea893bd99 100644 --- a/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/QueryRequest.java +++ b/java-client/src/main/java/co/elastic/clients/elasticsearch/esql/QueryRequest.java @@ -90,6 +90,8 @@ public class QueryRequest extends RequestBase implements JsonpSerializable { private final String query; + private final EsqlVersion version; + // --------------------------------------------------------------------------------------------- private QueryRequest(Builder builder) { @@ -101,6 +103,7 @@ private QueryRequest(Builder builder) { this.locale = builder.locale; this.params = ApiTypeHelper.unmodifiable(builder.params); this.query = ApiTypeHelper.requireNonNull(builder.query, this, "query"); + this.version = ApiTypeHelper.requireNonNull(builder.version, this, "version"); } @@ -182,6 +185,16 @@ public final String query() { return this.query; } + /** + * Required - The version of the ES|QL language in which the "query" + * field was written. + *

+ * API name: {@code version} + */ + public final EsqlVersion version() { + return this.version; + } + /** * Serialize this object to JSON. */ @@ -221,6 +234,9 @@ protected void serializeInternal(JsonGenerator generator, JsonpMapper mapper) { generator.writeKey("query"); generator.write(this.query); + generator.writeKey("version"); + this.version.serialize(generator, mapper); + } // --------------------------------------------------------------------------------------------- @@ -250,6 +266,8 @@ public static class Builder extends RequestBase.AbstractBuilder impleme private String query; + private EsqlVersion version; + /** * By default, ES|QL returns results as rows. For example, FROM returns each * individual document as one row. For the JSON, YAML, CBOR and smile formats, @@ -365,6 +383,17 @@ public final Builder query(String value) { return this; } + /** + * Required - The version of the ES|QL language in which the "query" + * field was written. + *

+ * API name: {@code version} + */ + public final Builder version(EsqlVersion value) { + this.version = value; + return this; + } + @Override protected Builder self() { return this; @@ -381,6 +410,10 @@ public QueryRequest build() { return new QueryRequest(this); } + { + // Use the default ES|QL language version if not set explicitly + this.version = EsqlVersion.getDefault(); + } } // --------------------------------------------------------------------------------------------- @@ -398,6 +431,7 @@ protected static void setupQueryRequestDeserializer(ObjectDeserializer q + .query("foo") + ); + + assertEquals(EsqlVersion.getDefault(), r.version()); + } + + @Test + public void testSetVersionToNull() { + + assertThrows(MissingRequiredPropertyException.class, () -> { + // If version is explicitly set to null, the default isn't used + QueryRequest r = QueryRequest.of(q -> q + .version(null) + .query("foo") + ); + }); + } +} diff --git a/java-client/src/test/java/co/elastic/clients/elasticsearch/spec_issues/SpecIssuesTest.java b/java-client/src/test/java/co/elastic/clients/elasticsearch/spec_issues/SpecIssuesTest.java index cc1a6ba8c..4f5df4597 100644 --- a/java-client/src/test/java/co/elastic/clients/elasticsearch/spec_issues/SpecIssuesTest.java +++ b/java-client/src/test/java/co/elastic/clients/elasticsearch/spec_issues/SpecIssuesTest.java @@ -164,6 +164,7 @@ public void i0254_suggesterTest() throws Exception { } @Test + @Disabled("Plugins cannot be installed on snapshot versions of ES") public void i0249_variantKind() throws Exception { try (ElasticsearchTestServer server = new ElasticsearchTestServer("analysis-icu").start()) {