[DOCS] Adds descriptions for the Graph API (#2221)

Author: szabosteve

output/schema/schema.json

@@ -349,6 +349,7 @@ modules-node,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mo
 search-aggregations-bucket-count-ks-test-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-count-ks-test-aggregation.html
 search-aggregations-bucket-correlation-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-correlation-aggregation.html
 search-aggregations-bucket-categorize-text-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-categorize-text-aggregation.html
+search-aggregations-bucket-significantterms-aggregation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-significantterms-aggregation.html
 search-aggregations-pipeline-bucket-path,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-pipeline.html#buckets-path-syntax
 ml-feature-importance,https://www.elastic.co/guide/en/machine-learning/{branch}/ml-feature-importance.html
 analysis-normalizers,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/analysis-normalizers.html

specification/_doc_ids/table.csv

@@ -22,9 +22,29 @@ import { integer } from '@_types/Numeric'
 import { Duration } from '@_types/Time'
 
 export class ExploreControls {
+  /**
+   * To avoid the top-matching documents sample being dominated by a single source of results, it is sometimes necessary to request diversity in the sample.
+   * You can do this by selecting a single-value field and setting a maximum number of documents per value for that field.
+   */
   sample_diversity?: SampleDiversity
+  /**
+   * Each hop considers a sample of the best-matching documents on each shard.
+   * Using samples improves the speed of execution and keeps exploration focused on meaningfully-connected terms.
+   * Very small values (less than 50) might not provide sufficient weight-of-evidence to identify significant connections between terms.
+   * Very large sample sizes can dilute the quality of the results and increase execution times.
+   * @server_default 100
+   */
   sample_size?: integer
+  /**
+   * The length of time in milliseconds after which exploration will be halted and the results gathered so far are returned.
+   * This timeout is honored on a best-effort basis.
+   * Execution might overrun this timeout if, for example, a long pause is encountered while FieldData is loaded for a field.
+   */
   timeout?: Duration
+  /**
+   * Filters associated terms so only those that are significantly associated with your query are included.
+   * @doc_id search-aggregations-bucket-significantterms-aggregation
+   */
   use_significance: boolean
 }
 

specification/graph/_types/ExploreControls.ts

@@ -21,7 +21,16 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
 import { VertexDefinition } from './Vertex'
 
 export class Hop {
+  /**
+   * Specifies one or more fields from which you want to extract terms that are associated with the specified vertices.
+   */
   connections?: Hop
+  /**
+   * An optional guiding query that constrains the Graph API as it explores connected terms.
+   */
   query: QueryContainer
+  /**
+   * Contains the fields you are interested in.
+   */
   vertices: VertexDefinition[]
 }

specification/graph/_types/Hop.ts

@@ -28,11 +28,33 @@ export class Vertex {
 }
 
 export class VertexDefinition {
+  /**
+   * Prevents the specified terms from being included in the results.
+   */
   exclude?: string[]
+  /**
+   * Identifies a field in the documents of interest.
+   */
   field: Field
+  /**
+   * Identifies the terms of interest that form the starting points from which you want to spider out.
+   */
   include?: VertexInclude[]
+  /**
+   * Specifies how many documents must contain a pair of terms before it is considered to be a useful connection.
+   * This setting acts as a certainty threshold.
+   * @server_default 3
+   */
   min_doc_count?: long
+  /**
+   * Controls how many documents on a particular shard have to contain a pair of terms before the connection is returned for global consideration.
+   * @server_default 2
+   */
   shard_min_doc_count?: long
+  /**
+   * Specifies the maximum number of vertex terms returned for each field.
+   * @server_default 5
+   */
   size?: integer
 }
 

specification/graph/_types/Vertex.ts

@@ -26,22 +26,47 @@ import { Hop } from '../_types/Hop'
 import { VertexDefinition } from '@graph/_types/Vertex'
 
 /**
+ * Extracts and summarizes information about the documents and terms in an Elasticsearch data stream or index.
+ * @doc_id graph-explore-api
  * @rest_spec_name graph.explore
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * Name of the index.
+     */
     index: Indices
   }
   query_parameters: {
+    /**
+     * Custom value used to route operations to a specific shard.
+     */
     routing?: Routing
+    /**
+     * Specifies the period of time to wait for a response from each shard.
+     * If no response is received before the timeout expires, the request fails and returns an error.
+     * Defaults to no timeout.
+     */
     timeout?: Duration
   }
   body: {
+    /**
+     * Specifies or more fields from which you want to extract terms that are associated with the specified vertices.
+     */
     connections?: Hop
+    /**
+     * Direct the Graph API how to build the graph.
+     */
     controls?: ExploreControls
+    /**
+     * A seed query that identifies the documents of interest. Can be any valid Elasticsearch query.
+     */
     query?: QueryContainer
+    /**
+     * Specifies one or more fields that contain the terms you want to include in the graph as vertices.
+     */
     vertices?: VertexDefinition[]
   }
 }