[DOCS] Add behavioral analytics and search application examples (#3392)

lcawl · szabosteve · lcawl · commit 6758e269e596 · 2025-01-03T08:13:56.000-08:00
Co-authored-by: István Zoltán Szabó <szabosteve@gmail.com> (cherry picked from commit a83a6ed)
diff --git 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
@@ -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"
+                  $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"
diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
diff --git a/output/schema/schema.json b/output/schema/schema.json
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -25,6 +25,8 @@ import { SearchApplicationParameters } from '../_types/SearchApplicationParamete
  * @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
@@ -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}"
