From dafba64743a48a413d708cbf8491eebf30429bba Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 4 Dec 2024 15:02:56 -0800 Subject: [PATCH] [DOCS] Adds EQL operation summaries (#3207) (cherry picked from commit 9f6c82cd8292e7d8701e3297be14de48bd9b2536) --- output/openapi/elasticsearch-openapi.json | 28 ++++++++++----- .../elasticsearch-serverless-openapi.json | 28 ++++++++++----- output/schema/schema.json | 36 ++++++++++--------- specification/eql/delete/EqlDeleteRequest.ts | 3 +- specification/eql/get/EqlGetRequest.ts | 3 +- .../eql/get_status/EqlGetStatusRequest.ts | 3 +- specification/eql/search/EqlSearchRequest.ts | 4 +++ 7 files changed, 67 insertions(+), 38 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 3bbe534247..d5c407180b 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -7488,7 +7488,8 @@ "tags": [ "eql" ], - "summary": "Returns the current status and available results for an async EQL search or a stored synchronous EQL search", + "summary": "Get async EQL search results", + "description": "Get the current status and available results for an async EQL search or a stored synchronous EQL search.", "operationId": "eql-get", "parameters": [ { @@ -7541,8 +7542,8 @@ "tags": [ "eql" ], - "summary": "Deletes an async EQL search or a stored synchronous EQL search", - "description": "The API also deletes results for the search.", + "summary": "Delete an async EQL search", + "description": "Delete an async EQL search or a stored synchronous EQL search.\nThe API also deletes results for the search.", "operationId": "eql-delete", "parameters": [ { @@ -7577,7 +7578,8 @@ "tags": [ "eql" ], - "summary": "Returns the current status for an async EQL search or a stored synchronous EQL search without returning results", + "summary": "Get the async EQL status", + "description": "Get the current status for an async EQL search or a stored synchronous EQL search without returning results.", "operationId": "eql-get-status", "parameters": [ { @@ -7640,7 +7642,11 @@ "tags": [ "eql" ], - "summary": "Returns results matching a query expressed in Event Query Language (EQL)", + "summary": "Get EQL search results", + "description": "Returns search results for an Event Query Language (EQL) query.\nEQL assumes each document in a data stream or index corresponds to an event.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html" + }, "operationId": "eql-search", "parameters": [ { @@ -7679,7 +7685,11 @@ "tags": [ "eql" ], - "summary": "Returns results matching a query expressed in Event Query Language (EQL)", + "summary": "Get EQL search results", + "description": "Returns search results for an Event Query Language (EQL) query.\nEQL assumes each document in a data stream or index corresponds to an event.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html" + }, "operationId": "eql-search-1", "parameters": [ { @@ -9200,7 +9210,7 @@ "graph" ], "summary": "Explore graph analytics", - "description": "Extract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behaviour of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", + "description": "Extract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behavior of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", "externalDocs": { "url": "https://www.elastic.co/guide/en/kibana/current/xpack-graph.html" }, @@ -9230,7 +9240,7 @@ "graph" ], "summary": "Explore graph analytics", - "description": "Extract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behaviour of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", + "description": "Extract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behavior of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", "externalDocs": { "url": "https://www.elastic.co/guide/en/kibana/current/xpack-graph.html" }, @@ -32631,7 +32641,7 @@ "synonyms" ], "summary": "Create or update a synonym set", - "description": "Synonyms sets are limited to a maximum of 10000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.", + "description": "Synonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.", "operationId": "synonyms-put-synonym", "parameters": [ { diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index e1508cd150..b4287a03eb 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -4788,7 +4788,8 @@ "tags": [ "eql" ], - "summary": "Returns the current status and available results for an async EQL search or a stored synchronous EQL search", + "summary": "Get async EQL search results", + "description": "Get the current status and available results for an async EQL search or a stored synchronous EQL search.", "operationId": "eql-get", "parameters": [ { @@ -4841,8 +4842,8 @@ "tags": [ "eql" ], - "summary": "Deletes an async EQL search or a stored synchronous EQL search", - "description": "The API also deletes results for the search.", + "summary": "Delete an async EQL search", + "description": "Delete an async EQL search or a stored synchronous EQL search.\nThe API also deletes results for the search.", "operationId": "eql-delete", "parameters": [ { @@ -4877,7 +4878,8 @@ "tags": [ "eql" ], - "summary": "Returns the current status for an async EQL search or a stored synchronous EQL search without returning results", + "summary": "Get the async EQL status", + "description": "Get the current status for an async EQL search or a stored synchronous EQL search without returning results.", "operationId": "eql-get-status", "parameters": [ { @@ -4940,7 +4942,11 @@ "tags": [ "eql" ], - "summary": "Returns results matching a query expressed in Event Query Language (EQL)", + "summary": "Get EQL search results", + "description": "Returns search results for an Event Query Language (EQL) query.\nEQL assumes each document in a data stream or index corresponds to an event.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html" + }, "operationId": "eql-search", "parameters": [ { @@ -4979,7 +4985,11 @@ "tags": [ "eql" ], - "summary": "Returns results matching a query expressed in Event Query Language (EQL)", + "summary": "Get EQL search results", + "description": "Returns search results for an Event Query Language (EQL) query.\nEQL assumes each document in a data stream or index corresponds to an event.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html" + }, "operationId": "eql-search-1", "parameters": [ { @@ -5708,7 +5718,7 @@ "graph" ], "summary": "Explore graph analytics", - "description": "Extract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behaviour of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", + "description": "Extract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behavior of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", "externalDocs": { "url": "https://www.elastic.co/guide/en/kibana/current/xpack-graph.html" }, @@ -5738,7 +5748,7 @@ "graph" ], "summary": "Explore graph analytics", - "description": "Extract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behaviour of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", + "description": "Extract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behavior of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", "externalDocs": { "url": "https://www.elastic.co/guide/en/kibana/current/xpack-graph.html" }, @@ -17929,7 +17939,7 @@ "synonyms" ], "summary": "Create or update a synonym set", - "description": "Synonyms sets are limited to a maximum of 10000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.", + "description": "Synonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.", "operationId": "synonyms-put-synonym", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index abf40cfbc8..8a1f110d48 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -4606,7 +4606,7 @@ "stability": "stable" } }, - "description": "Deletes an async EQL search or a stored synchronous EQL search.\nThe API also deletes results for the search.", + "description": "Delete an async EQL search.\nDelete an async EQL search or a stored synchronous EQL search.\nThe API also deletes results for the search.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/eql-search-api.html", "name": "eql.delete", "request": { @@ -4641,7 +4641,7 @@ "stability": "stable" } }, - "description": "Returns the current status and available results for an async EQL search or a stored synchronous EQL search.", + "description": "Get async EQL search results.\nGet the current status and available results for an async EQL search or a stored synchronous EQL search.", "docId": "eql-async-search-api", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-eql-search-api.html", "name": "eql.get", @@ -4677,7 +4677,7 @@ "stability": "stable" } }, - "description": "Returns the current status for an async EQL search or a stored synchronous EQL search without returning results.", + "description": "Get the async EQL status.\nGet the current status for an async EQL search or a stored synchronous EQL search without returning results.", "docId": "eql-async-search-status-api", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-eql-status-api.html", "name": "eql.get_status", @@ -4713,8 +4713,10 @@ "stability": "stable" } }, - "description": "Returns results matching a query expressed in Event Query Language (EQL)", + "description": "Get EQL search results.\nReturns search results for an Event Query Language (EQL) query.\nEQL assumes each document in a data stream or index corresponds to an event.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/eql-search-api.html", + "extDocId": "eql", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html", "name": "eql.search", "request": { "name": "Request", @@ -5446,11 +5448,11 @@ "stability": "stable" } }, - "description": "Explore graph analytics.\nExtract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behaviour of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", + "description": "Explore graph analytics.\nExtract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behavior of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", "docId": "graph-explore-api", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/graph-explore-api.html", "extDocId": "graph", - "extDocUrl": "https://www.elastic.co/guide/en/kibana/current/xpack-graph.html", + "extDocUrl": "https://www.elastic.co/guide/en/kibana/{branch}/xpack-graph.html", "name": "graph.explore", "request": { "name": "Request", @@ -18943,7 +18945,7 @@ "stability": "stable" } }, - "description": "Create or update a synonym set.\nSynonyms sets are limited to a maximum of 10000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.", + "description": "Create or update a synonym set.\nSynonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/put-synonyms-set.html", "name": "synonyms.put_synonym", "request": { @@ -117178,7 +117180,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes an async EQL search or a stored synchronous EQL search.\nThe API also deletes results for the search.", + "description": "Delete an async EQL search.\nDelete an async EQL search or a stored synchronous EQL search.\nThe API also deletes results for the search.", "inherits": { "type": { "name": "RequestBase", @@ -117204,7 +117206,7 @@ } ], "query": [], - "specLocation": "eql/delete/EqlDeleteRequest.ts#L23-L39" + "specLocation": "eql/delete/EqlDeleteRequest.ts#L23-L40" }, { "kind": "response", @@ -117232,7 +117234,7 @@ "body": { "kind": "no_body" }, - "description": "Returns the current status and available results for an async EQL search or a stored synchronous EQL search.", + "description": "Get async EQL search results.\nGet the current status and available results for an async EQL search or a stored synchronous EQL search.", "inherits": { "type": { "name": "RequestBase", @@ -117283,7 +117285,7 @@ } } ], - "specLocation": "eql/get/EqlGetRequest.ts#L24-L50" + "specLocation": "eql/get/EqlGetRequest.ts#L24-L51" }, { "kind": "response", @@ -117326,7 +117328,7 @@ "body": { "kind": "no_body" }, - "description": "Returns the current status for an async EQL search or a stored synchronous EQL search without returning results.", + "description": "Get the async EQL status.\nGet the current status for an async EQL search or a stored synchronous EQL search without returning results.", "inherits": { "type": { "name": "RequestBase", @@ -117352,7 +117354,7 @@ } ], "query": [], - "specLocation": "eql/get_status/EqlGetStatusRequest.ts#L23-L35" + "specLocation": "eql/get_status/EqlGetStatusRequest.ts#L23-L36" }, { "kind": "response", @@ -117674,7 +117676,7 @@ } ] }, - "description": "Returns results matching a query expressed in Event Query Language (EQL)", + "description": "Get EQL search results.\nReturns search results for an Event Query Language (EQL) query.\nEQL assumes each document in a data stream or index corresponds to an event.", "inherits": { "type": { "name": "RequestBase", @@ -117776,7 +117778,7 @@ } } ], - "specLocation": "eql/search/EqlSearchRequest.ts#L28-L118" + "specLocation": "eql/search/EqlSearchRequest.ts#L28-L122" }, { "kind": "response", @@ -120459,7 +120461,7 @@ } ] }, - "description": "Explore graph analytics.\nExtract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behaviour of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", + "description": "Explore graph analytics.\nExtract and summarize information about the documents and terms in an Elasticsearch data stream or index.\nThe easiest way to understand the behavior of this API is to use the Graph UI to explore connections.\nAn initial request to the `_explore` API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.\nSubsequent requests enable you to spider out from one more vertices of interest.\nYou can exclude vertices that have already been returned.", "inherits": { "type": { "name": "RequestBase", @@ -205683,7 +205685,7 @@ } ] }, - "description": "Create or update a synonym set.\nSynonyms sets are limited to a maximum of 10000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.", + "description": "Create or update a synonym set.\nSynonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.", "inherits": { "type": { "name": "RequestBase", diff --git a/specification/eql/delete/EqlDeleteRequest.ts b/specification/eql/delete/EqlDeleteRequest.ts index a25a673f7b..98178c64d2 100644 --- a/specification/eql/delete/EqlDeleteRequest.ts +++ b/specification/eql/delete/EqlDeleteRequest.ts @@ -21,7 +21,8 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** - * Deletes an async EQL search or a stored synchronous EQL search. + * Delete an async EQL search. + * Delete an async EQL search or a stored synchronous EQL search. * The API also deletes results for the search. * @rest_spec_name eql.delete * @availability stack since=7.9.0 stability=stable diff --git a/specification/eql/get/EqlGetRequest.ts b/specification/eql/get/EqlGetRequest.ts index 9e492feeff..40210d77bf 100644 --- a/specification/eql/get/EqlGetRequest.ts +++ b/specification/eql/get/EqlGetRequest.ts @@ -22,7 +22,8 @@ import { Id } from '@_types/common' import { Duration } from '@_types/Time' /** - * Returns the current status and available results for an async EQL search or a stored synchronous EQL search. + * Get async EQL search results. + * Get the current status and available results for an async EQL search or a stored synchronous EQL search. * @doc_id eql-async-search-api * @rest_spec_name eql.get * @availability stack since=7.9.0 stability=stable diff --git a/specification/eql/get_status/EqlGetStatusRequest.ts b/specification/eql/get_status/EqlGetStatusRequest.ts index 8195defc13..2510f61214 100644 --- a/specification/eql/get_status/EqlGetStatusRequest.ts +++ b/specification/eql/get_status/EqlGetStatusRequest.ts @@ -21,7 +21,8 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** - * Returns the current status for an async EQL search or a stored synchronous EQL search without returning results. + * Get the async EQL status. + * Get the current status for an async EQL search or a stored synchronous EQL search without returning results. * @doc_id eql-async-search-status-api * @rest_spec_name eql.get_status * @availability stack since=7.9.0 stability=stable diff --git a/specification/eql/search/EqlSearchRequest.ts b/specification/eql/search/EqlSearchRequest.ts index 99d661d673..87c5c3293f 100644 --- a/specification/eql/search/EqlSearchRequest.ts +++ b/specification/eql/search/EqlSearchRequest.ts @@ -26,9 +26,13 @@ import { Duration } from '@_types/Time' import { ResultPosition } from './types' /** + * Get EQL search results. + * Returns search results for an Event Query Language (EQL) query. + * EQL assumes each document in a data stream or index corresponds to an event. * @rest_spec_name eql.search * @availability stack since=7.9.0 stability=stable * @availability serverless stability=stable visibility=public + * @ext_doc_id eql */ export interface Request extends RequestBase { path_parts: {