From 6555983cb0f4999fdba7460b73414eb2ea5e6c24 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 3 Jan 2025 23:05:58 -0800 Subject: [PATCH] [DOCS] Add behavioral analytics and search application examples (#3392) (#3427) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó (cherry picked from commit a83a6ed7a5fdc47c9426f3d4aa47ef77fa2f9e9a) --- compiler/src/model/utils.ts | 2 +- .../elasticsearch-shared-overlays.yaml | 49 ++++++++++++++++++- output/openapi/elasticsearch-openapi.json | 3 +- .../elasticsearch-serverless-openapi.json | 3 +- output/schema/schema.json | 38 +++++++++++--- .../delete/SearchApplicationsDeleteRequest.ts | 2 + .../SearchApplicationGetResponseExample1.yaml | 13 +++++ .../get/SearchApplicationsGetRequest.ts | 1 + ...ehavioralAnalyticsGetResponseExample1.yaml | 10 ++++ .../list/SearchApplicationsListRequest.ts | 4 +- ...earchApplicationsListResponseExample1.yaml | 8 +++ .../SearchApplicationPutRequestExample1.yaml | 17 +++++++ .../put/SearchApplicationsPutRequest.ts | 2 + ...archApplicationsSearchRequestExample1.yaml | 8 +++ 14 files changed, 149 insertions(+), 11 deletions(-) create mode 100644 specification/search_application/get/SearchApplicationGetResponseExample1.yaml create mode 100644 specification/search_application/get_behavioral_analytics/BehavioralAnalyticsGetResponseExample1.yaml create mode 100644 specification/search_application/list/SearchApplicationsListResponseExample1.yaml create mode 100644 specification/search_application/put/SearchApplicationPutRequestExample1.yaml create mode 100644 specification/search_application/search/SearchApplicationsSearchRequestExample1.yaml diff --git a/compiler/src/model/utils.ts b/compiler/src/model/utils.ts index 9f4d3e669e..a3e1e32cba 100644 --- a/compiler/src/model/utils.ts +++ b/compiler/src/model/utils.ts @@ -668,7 +668,7 @@ export function hoistRequestAnnotations ( const privileges = [ 'all', 'cancel_task', 'create_snapshot', 'grant_api_key', 'manage', 'manage_api_key', 'manage_ccr', 'manage_enrich', 'manage_ilm', 'manage_index_templates', 'manage_inference', 'manage_ingest_pipelines', 'manage_logstash_pipelines', - 'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', + 'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform', 'manage_user_profile', 'manage_watcher', 'monitor', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_text_structure', 'monitor_transform', 'monitor_watcher', 'read_ccr', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client' diff --git a/docs/overlays/elasticsearch-shared-overlays.yaml b/docs/overlays/elasticsearch-shared-overlays.yaml index fa8d1bd828..1cbaf6b3f5 100644 --- a/docs/overlays/elasticsearch-shared-overlays.yaml +++ b/docs/overlays/elasticsearch-shared-overlays.yaml @@ -1351,6 +1351,15 @@ actions: examples: indicesRolloverResponseExample1: $ref: "../../specification/indices/rollover/indicesRolloverResponseExample1.yaml" +## Examples for behavioral analytics + - target: "$.components['responses']['search_application.get_behavioral_analytics#200']" + description: "Add example for get behavioral analytics collections response" + update: + content: + application/json: + examples: + getBehavioralAnalyticsCollectionsResponseExample1: + $ref: "../../specification/search_application/get_behavioral_analytics/BehavioralAnalyticsGetResponseExample1.yaml" ## Examples for licensing - target: "$.paths['/_license']['get']" description: "Add example for get license response" @@ -1361,4 +1370,42 @@ actions: application/json: examples: getLicenseResponseExample1: - $ref: "../../specification/license/get/GetLicenseResponseExample1.yaml" \ No newline at end of file + $ref: "../../specification/license/get/GetLicenseResponseExample1.yaml" +## Examples for search applications + - target: "$.paths['/_application/search_application']['get']" + description: "Add examples for get search applications operation" + update: + responses: + 200: + content: + application/json: + examples: + getSearchApplicationsResponseExample1: + $ref: "../../specification/search_application/list/SearchApplicationsListResponseExample1.yaml" + - target: "$.paths['/_application/search_application/{name}']['get']" + description: "Add examples for get search application details operation" + update: + responses: + 200: + content: + application/json: + examples: + getSearchApplicationResponseExample1: + $ref: "../../specification/search_application/get/SearchApplicationGetResponseExample1.yaml" + - target: "$.paths['/_application/search_application/{name}']['put']" + description: "Add examples for create search application operation" + update: + requestBody: + content: + application/json: + examples: + putSearchApplicationRequestExample1: + $ref: "../../specification/search_application/put/SearchApplicationPutRequestExample1.yaml" + - target: "$.components['requestBodies']['search_application.search']" + description: "Add example for search application search request" + update: + content: + application/json: + examples: + searchApplicationSearchRequestExample1: + $ref: "../../specification/search_application/search/SearchApplicationsSearchRequestExample1.yaml" \ No newline at end of file diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 4761add06f..53f0ea988b 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -27126,7 +27126,8 @@ "tags": [ "search_application" ], - "summary": "Returns the existing search applications", + "summary": "Get search applications", + "description": "Get information about search applications.", "operationId": "search-application-list", "parameters": [ { diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index 53b10bd877..974e05aaaa 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -16627,7 +16627,8 @@ "tags": [ "search_application" ], - "summary": "Returns the existing search applications", + "summary": "Get search applications", + "description": "Get information about search applications.", "operationId": "search-application-list", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index 2cb1760e4e..71886bb50d 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -14742,6 +14742,14 @@ "description": "Delete a search application.\nRemove a search application and its associated alias. Indices attached to the search application are not removed.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-search-application.html", "name": "search_application.delete", + "privileges": { + "cluster": [ + "manage_search_application" + ], + "index": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "search_application.delete" @@ -14813,6 +14821,11 @@ "description": "Get search application details.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-search-application.html", "name": "search_application.get", + "privileges": { + "cluster": [ + "manage_search_application" + ] + }, "request": { "name": "Request", "namespace": "search_application.get" @@ -14887,9 +14900,14 @@ "stability": "beta" } }, - "description": "Returns the existing search applications.", + "description": "Get search applications.\nGet information about search applications.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/list-search-applications.html", "name": "search_application.list", + "privileges": { + "cluster": [ + "manage_search_application" + ] + }, "request": { "name": "Request", "namespace": "search_application.list" @@ -14953,6 +14971,14 @@ "description": "Create or update a search application.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/put-search-application.html", "name": "search_application.put", + "privileges": { + "cluster": [ + "manage_search_application" + ], + "index": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "search_application.put" @@ -188256,7 +188282,7 @@ } ], "query": [], - "specLocation": "search_application/delete/SearchApplicationsDeleteRequest.ts#L22-L36" + "specLocation": "search_application/delete/SearchApplicationsDeleteRequest.ts#L22-L38" }, { "kind": "response", @@ -188364,7 +188390,7 @@ } ], "query": [], - "specLocation": "search_application/get/SearchApplicationsGetRequest.ts#L22-L35" + "specLocation": "search_application/get/SearchApplicationsGetRequest.ts#L22-L36" }, { "kind": "response", @@ -188460,7 +188486,7 @@ "body": { "kind": "no_body" }, - "description": "Returns the existing search applications.", + "description": "Get search applications.\nGet information about search applications.", "inherits": { "type": { "name": "RequestBase", @@ -188511,7 +188537,7 @@ } } ], - "specLocation": "search_application/list/SearchApplicationsListRequest.ts#L22-L44" + "specLocation": "search_application/list/SearchApplicationsListRequest.ts#L22-L46" }, { "kind": "response", @@ -188677,7 +188703,7 @@ } } ], - "specLocation": "search_application/put/SearchApplicationsPutRequest.ts#L23-L48" + "specLocation": "search_application/put/SearchApplicationsPutRequest.ts#L23-L50" }, { "kind": "response", diff --git a/specification/search_application/delete/SearchApplicationsDeleteRequest.ts b/specification/search_application/delete/SearchApplicationsDeleteRequest.ts index c0ec929057..ecd7ee74a3 100644 --- a/specification/search_application/delete/SearchApplicationsDeleteRequest.ts +++ b/specification/search_application/delete/SearchApplicationsDeleteRequest.ts @@ -25,6 +25,8 @@ import { Name } from '@_types/common' * @rest_spec_name search_application.delete * @availability stack since=8.8.0 stability=beta * @availability serverless stability=beta visibility=public + * @cluster_privileges manage_search_application + * @index_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/search_application/get/SearchApplicationGetResponseExample1.yaml b/specification/search_application/get/SearchApplicationGetResponseExample1.yaml new file mode 100644 index 0000000000..da6b1463ce --- /dev/null +++ b/specification/search_application/get/SearchApplicationGetResponseExample1.yaml @@ -0,0 +1,13 @@ +# summary: search-application/apis/get-search-application.asciidoc:95 +description: A sucessful response from `GET _application/search_application/my-app/`. +# type: response +# response_code: 200 +value: + "{\n \"name\": \"my-app\",\n \"indices\": [ \"index1\", \"index2\" ],\n \ + \ \"updated_at_millis\": 1682105622204,\n \"template\": {\n \"script\": {\n\ + \ \"source\": {\n \"query\": {\n \"query_string\": {\n \ + \ \"query\": \"{{query_string}}\",\n \"default_field\": \"{{default_field}}\"\ + \n }\n }\n },\n \"lang\": \"mustache\",\n \"options\"\ + : {\n \"content_type\": \"application/json;charset=utf-8\"\n },\n \ + \ \"params\": {\n \"query_string\": \"*\",\n \"default_field\"\ + : \"*\"\n }\n }\n }\n}" diff --git a/specification/search_application/get/SearchApplicationsGetRequest.ts b/specification/search_application/get/SearchApplicationsGetRequest.ts index f9a7ed3378..272d7b2371 100644 --- a/specification/search_application/get/SearchApplicationsGetRequest.ts +++ b/specification/search_application/get/SearchApplicationsGetRequest.ts @@ -24,6 +24,7 @@ import { Name } from '@_types/common' * @rest_spec_name search_application.get * @availability stack since=8.8.0 stability=beta * @availability serverless stability=beta visibility=public + * @cluster_privileges manage_search_application */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/search_application/get_behavioral_analytics/BehavioralAnalyticsGetResponseExample1.yaml b/specification/search_application/get_behavioral_analytics/BehavioralAnalyticsGetResponseExample1.yaml new file mode 100644 index 0000000000..824701b1ab --- /dev/null +++ b/specification/search_application/get_behavioral_analytics/BehavioralAnalyticsGetResponseExample1.yaml @@ -0,0 +1,10 @@ +# summary: behavioral-analytics/apis/list-analytics-collection.asciidoc:112 +description: A successful response from `GET _application/analytics/my*` +# type: response +# response_code: 200 +value: + "{\n \"my_analytics_collection\": {\n \"event_data_stream\": {\n \ + \ \"name\": \"behavioral_analytics-events-my_analytics_collection\"\n \ + \ }\n },\n \"my_analytics_collection2\": {\n \"event_data_stream\": {\n \ + \ \"name\": \"behavioral_analytics-events-my_analytics_collection2\"\n \ + \ }\n }\n}" diff --git a/specification/search_application/list/SearchApplicationsListRequest.ts b/specification/search_application/list/SearchApplicationsListRequest.ts index c7ace9689c..62d2d234df 100644 --- a/specification/search_application/list/SearchApplicationsListRequest.ts +++ b/specification/search_application/list/SearchApplicationsListRequest.ts @@ -20,10 +20,12 @@ import { RequestBase } from '@_types/Base' import { integer } from '@_types/Numeric' /** - * Returns the existing search applications. + * Get search applications. + * Get information about search applications. * @rest_spec_name search_application.list * @availability stack since=8.8.0 stability=beta * @availability serverless stability=beta visibility=public + * @cluster_privileges manage_search_application */ export interface Request extends RequestBase { query_parameters: { diff --git a/specification/search_application/list/SearchApplicationsListResponseExample1.yaml b/specification/search_application/list/SearchApplicationsListResponseExample1.yaml new file mode 100644 index 0000000000..f9d79d87fe --- /dev/null +++ b/specification/search_application/list/SearchApplicationsListResponseExample1.yaml @@ -0,0 +1,8 @@ +# summary: search-application/apis/list-search-applications.asciidoc:108 +description: A succesful response from `GET _application/search_application?from=0&size=3&q=app*` returns the first three search applications whose names start with `app`. +# type: response +# response_code: 200 +value: + "{\n \"count\": 2,\n \"results\": [\n {\n \"name\": \"app-1\",\n\ + \ \"updated_at_millis\": 1690981129366\n },\n {\n \"name\": \"app-2\"\ + ,\n \"updated_at_millis\": 1691501823939\n }\n ]\n}" diff --git a/specification/search_application/put/SearchApplicationPutRequestExample1.yaml b/specification/search_application/put/SearchApplicationPutRequestExample1.yaml new file mode 100644 index 0000000000..e6e94788ce --- /dev/null +++ b/specification/search_application/put/SearchApplicationPutRequestExample1.yaml @@ -0,0 +1,17 @@ +# summary: search-application/apis/put-search-application.asciidoc:148 +# method_request: PUT _application/search_application/my-app +description: > + Run `PUT _application/search_application/my-app` to create or update a search application called `my-app`. When the dictionary parameter is specified, the search application search API will perform the following parameter validation: it accepts only the `query_string` and `default_field` parameters; it verifies that `query_string` and `default_field` are both strings; it accepts `default_field` only if it takes the values title or description. If the parameters are not valid, the search application search API will return an error. +# type: request +value: + "{\n \"indices\": [ \"index1\", \"index2\" ],\n \"template\": {\n \"script\"\ + : {\n \"source\": {\n \"query\": {\n \"query_string\": {\n\ + \ \"query\": \"{{query_string}}\",\n \"default_field\": \"\ + {{default_field}}\"\n }\n }\n },\n \"params\": {\n \ + \ \"query_string\": \"*\",\n \"default_field\": \"*\"\n }\n },\n\ + \ \"dictionary\": {\n \"properties\": {\n \"query_string\": {\n \ + \ \"type\": \"string\"\n },\n \"default_field\": {\n \ + \ \"type\": \"string\",\n \"enum\": [\n \"title\",\n \ + \ \"description\"\n ]\n },\n \"additionalProperties\"\ + : false\n },\n \"required\": [\n \"query_string\"\n ]\n \ + \ }\n }\n}" diff --git a/specification/search_application/put/SearchApplicationsPutRequest.ts b/specification/search_application/put/SearchApplicationsPutRequest.ts index df5efd5ff0..df6f577689 100644 --- a/specification/search_application/put/SearchApplicationsPutRequest.ts +++ b/specification/search_application/put/SearchApplicationsPutRequest.ts @@ -25,6 +25,8 @@ import { SearchApplication } from '../_types/SearchApplication' * @rest_spec_name search_application.put * @availability stack since=8.8.0 stability=beta * @availability serverless stability=beta visibility=public + * @cluster_privileges manage_search_application + * @index_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/search_application/search/SearchApplicationsSearchRequestExample1.yaml b/specification/search_application/search/SearchApplicationsSearchRequestExample1.yaml new file mode 100644 index 0000000000..2951f511e6 --- /dev/null +++ b/specification/search_application/search/SearchApplicationsSearchRequestExample1.yaml @@ -0,0 +1,8 @@ +# summary: search-application/apis/search-application-search.asciidoc:125 +# method_request: POST _application/search_application/my-app/_search +description: Use `POST _application/search_application/my-app/_search` to run a search against a search application called `my-app` that uses a search template. +# type: request +value: + "{\n \"params\": {\n \"query_string\": \"my first query\",\n \"text_fields\"\ + : [\n {\"name\": \"title\", \"boost\": 5},\n {\"name\": \"description\"\ + , \"boost\": 1}\n ]\n }\n}"