From 4eba0409cdcbedd8f8d77815b2aa782500201c48 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 5 Dec 2024 12:06:44 -0800
Subject: [PATCH] [DOCS] Add ES|QL search operation summary (#3208) (#3238)

(cherry picked from commit 2d220a5096a4e68ef9cf439e6ce1d6715d881c87)

Co-authored-by: Lisa Cawley <lcawley@elastic.co>
---
 output/openapi/elasticsearch-openapi.json            |  6 +++++-
 output/openapi/elasticsearch-serverless-openapi.json |  6 +++++-
 output/schema/schema.json                            | 10 ++++++----
 specification/_doc_ids/table.csv                     |  1 +
 specification/esql/query/QueryRequest.ts             |  4 +++-
 5 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index 2aa0f0f4c8..1c2d67f411 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -7737,7 +7737,11 @@
         "tags": [
           "esql"
         ],
-        "summary": "Executes an ES|QL request",
+        "summary": "Run an ES|QL query",
+        "description": "Get search results for an ES|QL (Elasticsearch query language) query.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html"
+        },
         "operationId": "esql-query",
         "parameters": [
           {
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
index 4bc531c503..08e32c4993 100644
--- a/output/openapi/elasticsearch-serverless-openapi.json
+++ b/output/openapi/elasticsearch-serverless-openapi.json
@@ -5037,7 +5037,11 @@
         "tags": [
           "esql"
         ],
-        "summary": "Executes an ES|QL request",
+        "summary": "Run an ES|QL query",
+        "description": "Get search results for an ES|QL (Elasticsearch query language) query.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html"
+        },
         "operationId": "esql-query",
         "parameters": [
           {
diff --git a/output/schema/schema.json b/output/schema/schema.json
index 1e0b238d22..32a5a4d804 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -4803,9 +4803,11 @@
           "since": "8.11.0"
         }
       },
-      "description": "Executes an ES|QL request",
+      "description": "Run an ES|QL query.\nGet search results for an ES|QL (Elasticsearch query language) query.",
       "docId": "esql-query",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html",
+      "extDocId": "esql",
+      "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql.html",
       "name": "esql.query",
       "request": {
         "name": "Request",
@@ -117994,7 +117996,7 @@
         "name": "EsqlFormat",
         "namespace": "esql.query"
       },
-      "specLocation": "esql/query/QueryRequest.ts#L91-L100"
+      "specLocation": "esql/query/QueryRequest.ts#L93-L102"
     },
     {
       "kind": "request",
@@ -118116,7 +118118,7 @@
           }
         ]
       },
-      "description": "Executes an ES|QL request",
+      "description": "Run an ES|QL query.\nGet search results for an ES|QL (Elasticsearch query language) query.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -118167,7 +118169,7 @@
           }
         }
       ],
-      "specLocation": "esql/query/QueryRequest.ts#L26-L89"
+      "specLocation": "esql/query/QueryRequest.ts#L26-L91"
     },
     {
       "kind": "response",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index 02c04d4df9..28e1e06073 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -151,6 +151,7 @@ eql-sequences,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/e
 eql-missing-events,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql-syntax.html#eql-missing-events
 eql-syntax,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql-syntax.html
 eql,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html
+esql,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql.html
 esql-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html
 esql-query-params,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html#esql-rest-params
 esql-returning-localized-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html#esql-locale-param
diff --git a/specification/esql/query/QueryRequest.ts b/specification/esql/query/QueryRequest.ts
index 44ba0d0953..2c56dc5914 100644
--- a/specification/esql/query/QueryRequest.ts
+++ b/specification/esql/query/QueryRequest.ts
@@ -24,11 +24,13 @@ import { FieldValue } from '@_types/common'
 import { QueryContainer } from '@_types/query_dsl/abstractions'
 
 /**
- * Executes an ES|QL request
+ * Run an ES|QL query.
+ * Get search results for an ES|QL (Elasticsearch query language) query.
  * @rest_spec_name esql.query
  * @availability stack since=8.11.0
  * @availability serverless
  * @doc_id esql-query
+ * @ext_doc_id esql
  */
 export interface Request extends RequestBase {
   query_parameters: {