From ecf39bc0c18ba2e45c62906ef0cd91a56684e3d5 Mon Sep 17 00:00:00 2001 From: Tanguy Leroux Date: Wed, 6 Sep 2017 14:06:41 +0200 Subject: [PATCH] [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. --- docs/java-rest/high-level/apis/index.asciidoc | 2 -- .../java-rest/high-level/apis/search.asciidoc | 6 ++-- .../{apis => builders}/aggs.asciidoc | 2 +- .../{apis => builders}/queries.asciidoc | 4 +-- ...sage.asciidoc => getting-started.asciidoc} | 14 ++++---- docs/java-rest/high-level/index.asciidoc | 10 ++---- .../high-level/java-builders.asciidoc | 32 +++++++++++++++++++ docs/java-rest/high-level/migration.asciidoc | 4 +-- ...{apis.asciidoc => supported-apis.asciidoc} | 10 +++--- 9 files changed, 57 insertions(+), 27 deletions(-) rename docs/java-rest/high-level/{apis => builders}/aggs.asciidoc (99%) rename docs/java-rest/high-level/{apis => builders}/queries.asciidoc (99%) rename docs/java-rest/high-level/{usage.asciidoc => getting-started.asciidoc} (94%) create mode 100644 docs/java-rest/high-level/java-builders.asciidoc rename docs/java-rest/high-level/{apis.asciidoc => supported-apis.asciidoc} (79%) diff --git a/docs/java-rest/high-level/apis/index.asciidoc b/docs/java-rest/high-level/apis/index.asciidoc index 1f5301fdbd4..b4dcf7e9d80 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 0c0bee985ca..de336fd60d8 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 <> page gives a list of all available search queries with +The <> 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 <> 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 <> page gives a list of all available aggregations with +The <> page gives a list of all available aggregations with their corresponding `AggregationBuilder` objects and `AggregationBuilders` helper methods. We will later see how to <> in the `SearchResponse`. diff --git a/docs/java-rest/high-level/apis/aggs.asciidoc b/docs/java-rest/high-level/builders/aggs.asciidoc similarity index 99% rename from docs/java-rest/high-level/apis/aggs.asciidoc rename to docs/java-rest/high-level/builders/aggs.asciidoc index 101251bee19..3b15243f5b2 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 similarity index 99% rename from docs/java-rest/high-level/apis/queries.asciidoc rename to docs/java-rest/high-level/builders/queries.asciidoc index b46823fcf75..88204baa874 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 similarity index 94% rename from docs/java-rest/high-level/usage.asciidoc rename to docs/java-rest/high-level/getting-started.asciidoc index fd56f362387..86fe473fb29 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: -------------------------------------------------- -[[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 <> diff --git a/docs/java-rest/high-level/index.asciidoc b/docs/java-rest/high-level/index.asciidoc index ec7a1bdaf7d..bc4c2dd89bb 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 00000000000..be5c19293cd --- /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 <> +page shows an example of how to build a full search request using `SearchSourceBuilder` and +`QueryBuilder` objects. The <> 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 <> page. +The <> 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 5006607c47a..7ce0b00bdb0 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 <> page shows +The <> page shows typical configurations for Maven and Gradle and presents the - <> brought by the + <> 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 similarity index 79% rename from docs/java-rest/high-level/apis.asciidoc rename to docs/java-rest/high-level/supported-apis.asciidoc index b294974bacd..51411ea9fca 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:: * <> * <> * <> * <> -.Multi-document APIs +Multi document APIs:: * <> -.Search APIs +Search APIs:: * <> * <> * <> -.Miscellaneous APIs +Miscellaneous APIs:: * <> + +include::apis/index.asciidoc[] \ No newline at end of file