[Docs] Add "Using Java Builders" section (#26517)

The current "Building Queries" and "Building Aggregations" pages are
located under the "Supported Apis" section because they are linked to
the "Search API" page.

It should instead be in a dedicated section: this commit adds a new
"Using Java Builders" section and renames few filenames in favor of
more meaningful names.

9 files changed, 57 insertions, 27 deletions

diff --git a/docs/java-rest/high-level/apis/index.asciidoc b/docs/java-rest/high-level/apis/index.asciidoc
index 1f5301fdbd..b4dcf7e9d8 100644
--- a/docs/java-rest/high-level/apis/index.asciidoc
+++ b/docs/java-rest/high-level/apis/index.asciidoc
@@ -6,5 +6,3 @@ include::bulk.asciidoc[]
 include::search.asciidoc[]
 include::scroll.asciidoc[]
 include::main.asciidoc[]
-include::queries.asciidoc[]
-include::aggs.asciidoc[]
diff --git a/docs/java-rest/high-level/apis/search.asciidoc b/docs/java-rest/high-level/apis/search.asciidoc
index 0c0bee985c..de336fd60d 100644
--- a/docs/java-rest/high-level/apis/search.asciidoc
+++ b/docs/java-rest/high-level/apis/search.asciidoc
@@ -82,6 +82,7 @@ After this, the `SearchSourceBuilder` only needs to be added to the
 include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-setter]
 --------------------------------------------------
 
+[[java-rest-high-document-search-request-building-queries]]
 ===== Building queries
 
 Search queries are created using `QueryBuilder` objects. A `QueryBuilder` exists
@@ -125,7 +126,7 @@ to the `SearchSourceBuilder` as follows:
 include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-setter]
 --------------------------------------------------
 
-The <<java-rest-high-search-queries, Search Queries>> page gives a list of all available search queries with
+The <<java-rest-high-query-builders, Building Queries>> page gives a list of all available search queries with
 their corresponding `QueryBuilder` objects and `QueryBuilders` helper methods.
 
 
@@ -178,6 +179,7 @@ setters with a similar name (e.g. `#preTags(String ...)`).
 
 Highlighted text fragments can <<java-rest-high-retrieve-highlighting,later be retrieved>> from the `SearchResponse`.
 
+[[java-rest-high-document-search-request-building-aggs]]
 ===== Requesting Aggregations
 
 Aggregations can be added to the search by first creating the appropriate
@@ -190,7 +192,7 @@ sub-aggregation on the average age of employees in the company:
 include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations]
 --------------------------------------------------
 
-The <<java-rest-high-aggregations, Aggregations>> page gives a list of all available aggregations with
+The <<java-rest-high-aggregation-builders, Building Aggregations>> page gives a list of all available aggregations with
 their corresponding `AggregationBuilder` objects and `AggregationBuilders` helper methods.
 
 We will later see how to <<java-rest-high-retrieve-aggs,access aggregations>> in the `SearchResponse`.
diff --git a/docs/java-rest/high-level/apis/aggs.asciidoc b/docs/java-rest/high-level/builders/aggs.asciidoc
index 101251bee1..3b15243f5b 100644
--- a/docs/java-rest/high-level/apis/aggs.asciidoc
+++ b/docs/java-rest/high-level/builders/aggs.asciidoc
@@ -1,4 +1,4 @@
-[[java-rest-high-aggregations]]
+[[java-rest-high-aggregation-builders]]
 === Building Aggregations
 
 This page lists all the available aggregations with their corresponding `AggregationBuilder` class name and helper method name in the
diff --git a/docs/java-rest/high-level/apis/queries.asciidoc b/docs/java-rest/high-level/builders/queries.asciidoc
index b46823fcf7..88204baa87 100644
--- a/docs/java-rest/high-level/apis/queries.asciidoc
+++ b/docs/java-rest/high-level/builders/queries.asciidoc
@@ -1,5 +1,5 @@
-[[java-rest-high-search-queries]]
-=== Building Search Queries
+[[java-rest-high-query-builders]]
+=== Building Queries
 
 This page lists all the available search queries with their corresponding `QueryBuilder` class name and helper method name in the
 `QueryBuilders` utility class.
diff --git a/docs/java-rest/high-level/usage.asciidoc b/docs/java-rest/high-level/getting-started.asciidoc
index fd56f36238..86fe473fb2 100644
--- a/docs/java-rest/high-level/usage.asciidoc
+++ b/docs/java-rest/high-level/getting-started.asciidoc
@@ -1,4 +1,4 @@
-[[java-rest-high-usage]]
+[[java-rest-high-getting-started]]
 == Getting started
 
 This section describes how to get started with the high-level REST client from
@@ -36,7 +36,7 @@ major version.
 
 The javadoc for the REST high level client can be found at {rest-high-level-client-javadoc}/index.html.
 
-[[java-rest-high-usage-maven]]
+[[java-rest-high-getting-started-maven]]
 === Maven Repository
 
 The high-level Java REST client is hosted on
@@ -46,7 +46,7 @@ Central]. The minimum Java version required is `1.8`.
 The High Level REST Client is subject to the same release cycle as
 Elasticsearch. Replace the version with the desired client version.
 
-[[java-rest-high-usage-maven-maven]]
+[[java-rest-high-getting-started-maven-maven]]
 ==== Maven configuration
 
 Here is how you can configure the dependency using maven as a dependency manager.
@@ -61,7 +61,7 @@ Add the following to your `pom.xml` file:
 </dependency>
 --------------------------------------------------
 
-[[java-rest-high-usage-maven-gradle]]
+[[java-rest-high-getting-started-maven-gradle]]
 ==== Gradle configuration
 
 Here is how you can configure the dependency using gradle as a dependency manager.
@@ -74,7 +74,7 @@ dependencies {
 }
 --------------------------------------------------
 
-[[java-rest-high-usage-maven-lucene]]
+[[java-rest-high-getting-started-maven-lucene]]
 ==== Lucene Snapshot repository
 
 The very first releases of any major version (like a beta), might have been built on top of a Lucene Snapshot version.
@@ -105,7 +105,7 @@ maven {
 }
 --------------------------------------------------
 
-[[java-rest-high-usage-dependencies]]
+[[java-rest-high-getting-started-dependencies]]
 === Dependencies
 
 The High Level Java REST Client depends on the following artifacts and their
@@ -115,7 +115,7 @@ transitive dependencies:
 - org.elasticsearch:elasticsearch
 
 
-[[java-rest-high-usage-initialization]]
+[[java-rest-high-getting-started-initialization]]
 === Initialization
 
 A `RestHighLevelClient` instance needs a <<java-rest-low-usage-initialization,REST low-level client builder>>
diff --git a/docs/java-rest/high-level/index.asciidoc b/docs/java-rest/high-level/index.asciidoc
index ec7a1bdaf7..bc4c2dd89b 100644
--- a/docs/java-rest/high-level/index.asciidoc
+++ b/docs/java-rest/high-level/index.asciidoc
@@ -24,14 +24,10 @@ the same response objects.
 
 :doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
 
-include::usage.asciidoc[]
-
-include::apis.asciidoc[]
-
-include::apis/index.asciidoc[]
-
+include::getting-started.asciidoc[]
+include::supported-apis.asciidoc[]
+include::java-builders.asciidoc[]
 include::migration.asciidoc[]
-
 include::../license.asciidoc[]
 
 :doc-tests!:
diff --git a/docs/java-rest/high-level/java-builders.asciidoc b/docs/java-rest/high-level/java-builders.asciidoc
new file mode 100644
index 0000000000..be5c19293c
--- /dev/null
+++ b/docs/java-rest/high-level/java-builders.asciidoc
@@ -0,0 +1,32 @@
+[[java-rest-high-java-builders]]
+== Using Java Builders
+
+The Java High Level REST Client depends on the Elasticsearch core project which provides
+different types of Java `Builders` objects, including:
+
+Query Builders::
+
+The query builders are used to create the query to execute within a search request. There
+is a query builder for every type of query supported by the Query DSL. Each query builder
+implements the `QueryBuilder` interface and allows to set the specific options for a given
+type of query. Once created, the `QueryBuilder` object can be set as the query parameter of
+`SearchSourceBuilder`. The <<java-rest-high-document-search-request-building-queries, Search Request>>
+page shows an example of how to build a full search request using `SearchSourceBuilder` and
+`QueryBuilder` objects. The <<java-rest-high-query-builders, Building Search Queries>> page
+gives a list of all available search queries with their corresponding `QueryBuilder` objects
+and `QueryBuilders` helper methods.
+
+Aggregation Builders::
+
+Similarly to query builders, the aggregation builders are used to create the aggregations to
+compute during a search request execution. There is an aggregation builder for every type of
+aggregation (or pipeline aggregation) supported by Elasticsearch. All builders extend the
+`AggregationBuilder` class (or `PipelineAggregationBuilder`class). Once created, `AggregationBuilder`
+objects can be set as the aggregation parameter of `SearchSourceBuilder`. There is a example
+of how `AggregationBuilder` objects are used with `SearchSourceBuilder` objects to define the aggregations
+to compute with a search query in <<java-rest-high-document-search-request-building-aggs, Search Request>> page.
+The <<java-rest-high-aggregation-builders, Building Aggregations>> page gives a list of all available
+aggregations with their corresponding `AggregationBuilder` objects and `AggregationBuilders` helper methods.
+
+include::builders/queries.asciidoc[]
+include::builders/aggs.asciidoc[]
diff --git a/docs/java-rest/high-level/migration.asciidoc b/docs/java-rest/high-level/migration.asciidoc
index 5006607c47..7ce0b00bdb 100644
--- a/docs/java-rest/high-level/migration.asciidoc
+++ b/docs/java-rest/high-level/migration.asciidoc
@@ -40,9 +40,9 @@ Java application that uses the `TransportClient` depends on the
 `org.elasticsearch.client:transport` artifact. This dependency
 must be replaced by a new dependency on the high-level client.
 
-The <<java-rest-high-usage,Getting Started>> page shows
+The <<java-rest-high-getting-started,Getting Started>> page shows
  typical configurations for Maven and Gradle and presents the
- <<java-rest-high-usage-dependencies, dependencies>> brought by the
+ <<java-rest-high-getting-started-dependencies, dependencies>> brought by the
  high-level client.
 
 === Changing the client's initialization code
diff --git a/docs/java-rest/high-level/apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc
index b294974bac..51411ea9fc 100644
--- a/docs/java-rest/high-level/apis.asciidoc
+++ b/docs/java-rest/high-level/supported-apis.asciidoc
@@ -3,19 +3,21 @@
 
 The Java High Level REST Client supports the following APIs:
 
-.Single document APIs
+Single document APIs::
 * <<java-rest-high-document-index>>
 * <<java-rest-high-document-get>>
 * <<java-rest-high-document-delete>>
 * <<java-rest-high-document-update>>
 
-.Multi-document APIs
+Multi document APIs::
 * <<java-rest-high-document-bulk>>
 
-.Search APIs
+Search APIs::
 * <<java-rest-high-search>>
 * <<java-rest-high-search-scroll>>
 * <<java-rest-high-clear-scroll>>
 
-.Miscellaneous APIs
+Miscellaneous APIs::
 * <<java-rest-high-main>>
+
+include::apis/index.asciidoc[]
\ No newline at end of file