Add `_query` endpoint as `_esql` replacement (ESQL-1463)

This adds a new ES|QL endpoint, `_query`, to replace the now deprecated
`_esql`. The latter is still kept for a while, emitting a deprecation
warning.

Fixes ESQL-1379.

docs/reference/esql/index.asciidoc

@@ -35,11 +35,11 @@ The result of a query is the table produced by the final processing command.
 [discrete]
 ==== The {esql} API
 
-Use the `_esql` endpoint to run an {esql} query:
+Use the `_query` endpoint to run an {esql} query:
 
 [source,console]
 ----
-POST /_esql
+POST /_query
 {
   "query": """
     FROM library
@@ -76,7 +76,7 @@ CSV, or TSV, use the `format` parameter:
 
 [source,console]
 ----
-POST /_esql?format=txt
+POST /_query?format=txt
 {
   "query": """
     FROM library

docs/reference/esql/multivalued-fields.asciidoc

@@ -15,7 +15,7 @@ POST /mv/_bulk?refresh
 { "index" : {} }
 { "a": 2, "b": 3 }
 
-POST /_esql
+POST /_query
 {
   "query": "FROM mv"
 }
@@ -63,7 +63,7 @@ POST /mv/_bulk?refresh
 { "index" : {} }
 { "a": 2, "b": ["bar", "bar"] }
 
-POST /_esql
+POST /_query
 {
   "query": "FROM mv"
 }
@@ -104,7 +104,7 @@ POST /mv/_bulk?refresh
 { "index" : {} }
 { "a": 2, "b": [1, 1] }
 
-POST /_esql
+POST /_query
 {
   "query": "FROM mv"
 }
@@ -146,7 +146,7 @@ POST /mv/_bulk?refresh
 { "index" : {} }
 { "a": 2, "b": [1, 1] }
 
-POST /_esql
+POST /_query
 {
   "query": "FROM mv | EVAL b=TO_STRING(b)"
 }
@@ -181,7 +181,7 @@ POST /mv/_bulk?refresh
 { "index" : {} }
 { "a": 2, "b": 3 }
 
-POST /_esql
+POST /_query
 {
   "query": "FROM mv | EVAL b + 2, a + b"
 }
@@ -215,7 +215,7 @@ Work around this limitation by converting the field to single value with one of:
 
 [source,console,esql-multivalued-fields-mv-into-null]
 ----
-POST /_esql
+POST /_query
 {
   "query": "FROM mv | EVAL b=MV_MIN(b) | EVAL b + 2, a + b"
 }

rest-api-spec/src/main/resources/rest-api-spec/api/esql.query.json

@@ -13,7 +13,7 @@
     "url":{
       "paths":[
         {
-          "path":"/_esql",
+          "path":"/_query",
           "methods":[
             "POST"
           ]

x-pack/plugin/esql/qa/security/src/javaRestTest/java/org/elasticsearch/xpack/esql/EsqlSecurityIT.java

@@ -215,7 +215,7 @@ public class EsqlSecurityIT extends ESRestTestCase {
     }
 
     private Response runESQLCommand(String user, String command) throws IOException {
-        Request request = new Request("POST", "_esql");
+        Request request = new Request("POST", "_query");
         request.setJsonEntity("{\"query\":\"" + command + "\"}");
         request.setOptions(RequestOptions.DEFAULT.toBuilder().addHeader("es-security-runas-user", user));
         return client().performRequest(request);

x-pack/plugin/esql/qa/server/src/main/java/org/elasticsearch/xpack/esql/qa/rest/RestEsqlTestCase.java

@@ -374,7 +374,7 @@ public class RestEsqlTestCase extends ESRestTestCase {
     }
 
     private static Request prepareRequest() {
-        Request request = new Request("POST", "/_esql");
+        Request request = new Request("POST", "/_query");
         request.addParameter("error_trace", "true");   // Helps with debugging in case something crazy happens on the server.
         request.addParameter("pretty", "true");        // Improves error reporting readability
         return request;

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/RestEsqlQueryAction.java

@@ -8,6 +8,7 @@
 package org.elasticsearch.xpack.esql.action;
 
 import org.elasticsearch.client.internal.node.NodeClient;
+import org.elasticsearch.core.RestApiVersion;
 import org.elasticsearch.rest.BaseRestHandler;
 import org.elasticsearch.rest.RestRequest;
 import org.elasticsearch.rest.action.RestCancellableNodeClient;
@@ -30,7 +31,11 @@ public class RestEsqlQueryAction extends BaseRestHandler {
 
     @Override
     public List<Route> routes() {
-        return Collections.singletonList(Route.builder(POST, "/_esql").build());
+        return List.of(
+            new Route(POST, "/_query"),
+            // TODO: remove before release
+            Route.builder(POST, "/_esql").deprecated("_esql endpoint has been deprecated in favour of _query", RestApiVersion.V_8).build()
+        );
     }
 
     @Override