Merge branch 'master' into pr-10624

Conflicts:
	src/main/java/org/elasticsearch/index/shard/IndexShard.java

Author: s1monw

docs/community/clients.asciidoc

@@ -13,7 +13,7 @@ See the {client}/perl-api/current/index.html[official Elasticsearch Perl client]
 See the {client}/python-api/current/index.html[official Elasticsearch Python client].
 
 * http://github.com/elasticsearch/elasticsearch-dsl-py[elasticsearch-dsl-py]
-  chainable query and filter construction built on top of offical client.
+  chainable query and filter construction built on top of official client.
 
 * http://github.com/rhec/pyelasticsearch[pyelasticsearch]:
   Python client.

docs/java-api/client.asciidoc

@@ -134,7 +134,7 @@ be "two hop" operations).
 --------------------------------------------------
 // on startup
 
-Client client = new TransportClient()
+Client client = TransportClient.builder().build()
         .addTransportAddress(new InetSocketTransportAddress("host1", 9300))
         .addTransportAddress(new InetSocketTransportAddress("host2", 9300));
 
@@ -150,7 +150,7 @@ Note that you have to set the cluster name if you use one different than
 --------------------------------------------------
 Settings settings = ImmutableSettings.settingsBuilder()
         .put("cluster.name", "myClusterName").build();
-Client client =    new TransportClient(settings);
+Client client = TransportClient.builder().settings(settings).build();
 //Add transport addresses and do something with the client...
 --------------------------------------------------
 
@@ -166,7 +166,7 @@ used will be the ones that the other nodes were started with (the
 --------------------------------------------------
 Settings settings = ImmutableSettings.settingsBuilder()
         .put("client.transport.sniff", true).build();
-TransportClient client = new TransportClient(settings);
+TransportClient client = TransportClient.builder().settings(settings).build();
 --------------------------------------------------
 
 Other transport client level settings include:

docs/java-api/query-dsl-filters.asciidoc

@@ -150,7 +150,7 @@ FilterBuilder filter = geoDistanceFilter("pin.location")    <1>
 <2> center point
 <3> distance from center point
 <4> optimize bounding box: `memory`, `indexed` or `none`
-<5> distance computation mode: `GeoDistance.SLOPPY_ARC` (default), `GeoDistance.ARC` (slighly more precise but
+<5> distance computation mode: `GeoDistance.SLOPPY_ARC` (default), `GeoDistance.ARC` (slightly more precise but
     significantly slower) or `GeoDistance.PLANE` (faster, but inaccurate on long distances and close to the poles)
 
 Note that you can cache the result using

docs/reference/search/aggregations.asciidoc renamed to docs/reference/aggregations.asciidoc

@@ -1,6 +1,8 @@
 [[search-aggregations]]
-== Aggregations
+= Aggregations
 
+[partintro]
+--
 The aggregations framework helps provide aggregated data based on a search query. It is based on simple building blocks
 called aggregations, that can be composed in order to build complex summaries of the data.
 
@@ -11,16 +13,19 @@ query/filters of the search request).
 There are many different types of aggregations, each with its own purpose and output. To better understand these types,
 it is often easier to break them into two main families:
 
-_Bucketing_::
+<<search-aggregations-bucket, _Bucketing_>>::
 				A family of aggregations that build buckets, where each bucket is associated with a _key_ and a document
 				criterion. When the aggregation is executed, all the buckets criteria are evaluated on every document in
 				the context and when a criterion matches, the document is considered to "fall in" the relevant bucket.
 				By the end of the aggregation process, we'll end up with a list of buckets - each one with a set of
 				documents that "belong" to it.
 
-_Metric_::
+<<search-aggregations-metrics, _Metric_>>::
 				Aggregations that keep track and compute metrics over a set of documents.
 
+<<search-aggregations-reducer, _Reducer_>>::
+				Aggregations that aggregate the output of other aggregations and their associated metrics
+
 The interesting part comes next. Since each bucket effectively defines a document set (all documents belonging to
 the bucket), one can potentially associate aggregations on the bucket level, and those will execute within the context
 of that bucket. This is where the real power of aggregations kicks in: *aggregations can be nested!*
@@ -31,7 +36,7 @@ NOTE:	Bucketing aggregations can have sub-aggregations (bucketing or metric). Th
 		another higher-level aggregation).
 
 [float]
-=== Structuring Aggregations
+== Structuring Aggregations
 
 The following snippet captures the basic structure of aggregations:
 
@@ -62,7 +67,7 @@ bucketing aggregation. For example, if you define a set of aggregations under th
 sub-aggregations will be computed for the range buckets that are defined.
 
 [float]
-==== Values Source
+=== Values Source
 
 Some aggregations work on values extracted from the aggregated documents. Typically, the values will be extracted from
 a specific document field which is set using the `field` key for the aggregations. It is also possible to define a
@@ -89,146 +94,12 @@ perform optimizations when dealing with sorted values (for example, with the `mi
 sorted, Elasticsearch will skip the iterations over all the values and rely on the first value in the list to be the
 minimum value among all other values associated with the same document).
 
-[float]
-=== Metrics Aggregations
-
-The aggregations in this family compute metrics based on values extracted in one way or another from the documents that
-are being aggregated. The values are typically extracted from the fields of the document (using the field data), but
-can also be generated using scripts.
-
-Numeric metrics aggregations are a special type of metrics aggregation which output numeric values. Some aggregations output
-a single numeric metric (e.g. `avg`) and are called `single-value numeric metrics aggregation`, others generate multiple
-metrics (e.g. `stats`) and are called `multi-value numeric metrics aggregation`. The distinction between single-value and
-multi-value numeric metrics aggregations plays a role when these aggregations serve as direct sub-aggregations of some
-bucket aggregations (some bucket aggregations enable you to sort the returned buckets based on the numeric metrics in each bucket).
-
-
-[float]
-=== Bucket Aggregations
-
-Bucket aggregations don't calculate metrics over fields like the metrics aggregations do, but instead, they create
-buckets of documents. Each bucket is associated with a criterion (depending on the aggregation type) which determines
-whether or not a document in the current context "falls" into it. In other words, the buckets effectively define document
-sets. In addition to the buckets themselves, the `bucket` aggregations also compute and return the number of documents
-that "fell in" to each bucket.
-
-Bucket aggregations, as opposed to `metrics` aggregations, can hold sub-aggregations. These sub-aggregations will be
-aggregated for the buckets created by their "parent" bucket aggregation.
-
-There are different bucket aggregators, each with a different "bucketing" strategy. Some define a single bucket, some
-define fixed number of multiple buckets, and others dynamically create the buckets during the aggregation process.
-
-[float]
-=== Reducer Aggregations
-
-coming[2.0.0]
-
-experimental[]
-
-Reducer aggregations work on the outputs produced from other aggregations rather than from document sets, adding 
-information to the output tree. There are many different types of reducer, each computing different information from  
-other aggregations, but these types can broken down into two families:
-
-_Parent_::
-				A family of reducer aggregations that is provided with the output of its parent aggregation and is able
-				to compute new buckets or new aggregations to add to existing buckets.
-
-_Sibling_::
-				Reducer aggregations that are provided with the output of a sibling aggregation and are able to compute a 
-				new aggregation which will be at the same level as the sibling aggregation.
-
-Reducer aggregations can reference the aggregations they need to perform their computation by using the `buckets_paths` 
-parameter to indicate the paths to the required metrics. The syntax for defining these paths can be found in the
-<<search-aggregations-bucket-terms-aggregation-order, terms aggregation order>> section.
-
-??????  SHOULD THE SECTION ABOUT DEFINING AGGREGATION PATHS 
-BE IN THIS PAGE AND REFERENCED FROM THE TERMS AGGREGATION DOCUMENTATION  ???????
-
-Reducer aggregations cannot have sub-aggregations but depending on the type it can reference another reducer in the `buckets_path` 
-allowing reducers to be chained.
-
-NOTE: Because reducer aggregations only add to the output, when chaining reducer aggregations the output of each reducer will be 
-included in the final output.
-
-[float]
-=== Caching heavy aggregations
-
-Frequently used aggregations (e.g. for display on the home page of a website)
-can be cached for faster responses. These cached results are the same results
-that would be returned by an uncached aggregation -- you will never get stale
-results.
-
-See <<index-modules-shard-query-cache>> for more details.
-
-[float]
-=== Returning only aggregation results
-
-There are many occasions when aggregations are required but search hits are not.  For these cases the hits can be ignored by
-setting `size=0`. For example:
-
-[source,js]
---------------------------------------------------
-$ curl -XGET 'http://localhost:9200/twitter/tweet/_search' -d '{
-  "size": 0,
-  "aggregations": {
-    "my_agg": {
-      "terms": {
-        "field": "text"
-      }
-    }
-  }
-}
-'
---------------------------------------------------
-
-Setting `size` to `0` avoids executing the fetch phase of the search making the request more efficient.
-
-[float]
-=== Metadata
-
-You can associate a piece of metadata with individual aggregations at request time that will be returned in place
-at response time.
-
-Consider this example where we want to associate the color blue with our `terms` aggregation.
-
-[source,js]
---------------------------------------------------
-{
-    ...
-    aggs": {
-        "titles": {
-            "terms": {
-                "field": "title"
-            },
-            "meta": {
-                "color": "blue"
-            },
-        }
-    }
-}
---------------------------------------------------
-
-Then that piece of metadata will be returned in place for our `titles` terms aggregation
-
-[source,js]
---------------------------------------------------
-{
-    ...
-    "aggregations": {
-        "titles": {
-            "meta": {
-                "color" : "blue"
-            },
-            "buckets": [
-            ]
-        }
-    }
-}
---------------------------------------------------
+--
 
 include::aggregations/metrics.asciidoc[]
 
 include::aggregations/bucket.asciidoc[]
 
 include::aggregations/reducer.asciidoc[]
 
+include::aggregations/misc.asciidoc[]

docs/reference/aggregations/bucket.asciidoc

@@ -0,0 +1,49 @@
+[[search-aggregations-bucket]]
+== Bucket Aggregations
+
+Bucket aggregations don't calculate metrics over fields like the metrics aggregations do, but instead, they create
+buckets of documents. Each bucket is associated with a criterion (depending on the aggregation type) which determines
+whether or not a document in the current context "falls" into it. In other words, the buckets effectively define document
+sets. In addition to the buckets themselves, the `bucket` aggregations also compute and return the number of documents
+that "fell in" to each bucket.
+
+Bucket aggregations, as opposed to `metrics` aggregations, can hold sub-aggregations. These sub-aggregations will be
+aggregated for the buckets created by their "parent" bucket aggregation.
+
+There are different bucket aggregators, each with a different "bucketing" strategy. Some define a single bucket, some
+define fixed number of multiple buckets, and others dynamically create the buckets during the aggregation process.
+
+include::bucket/children-aggregation.asciidoc[]
+
+include::bucket/datehistogram-aggregation.asciidoc[]
+
+include::bucket/daterange-aggregation.asciidoc[]
+
+include::bucket/filter-aggregation.asciidoc[]
+
+include::bucket/filters-aggregation.asciidoc[]
+
+include::bucket/geodistance-aggregation.asciidoc[]
+
+include::bucket/geohashgrid-aggregation.asciidoc[]
+
+include::bucket/global-aggregation.asciidoc[]
+
+include::bucket/histogram-aggregation.asciidoc[]
+
+include::bucket/iprange-aggregation.asciidoc[]
+
+include::bucket/missing-aggregation.asciidoc[]
+
+include::bucket/nested-aggregation.asciidoc[]
+
+include::bucket/range-aggregation.asciidoc[]
+
+include::bucket/reverse-nested-aggregation.asciidoc[]
+
+include::bucket/sampler-aggregation.asciidoc[]
+
+include::bucket/significantterms-aggregation.asciidoc[]
+
+include::bucket/terms-aggregation.asciidoc[]
+

docs/reference/search/aggregations/bucket/children-aggregation.asciidoc renamed to docs/reference/aggregations/bucket/children-aggregation.asciidoc

@@ -2,7 +2,7 @@
 === Date Range Aggregation
 
 A range aggregation that is dedicated for date values. The main difference between this aggregation and the normal <<search-aggregations-bucket-range-aggregation,range>> aggregation is that the `from` and `to` values can be expressed in <<date-math,Date Math>> expressions, and it is also possible to specify a date format by which the `from` and `to` response fields will be returned.
-Note that this aggregration includes the `from` value and excludes the `to` value for each range.
+Note that this aggregation includes the `from` value and excludes the `to` value for each range.
 
 Example: