Docs: Reorganised the Query DSL docs into families and explaing query vs filter context

docs/reference/query-dsl.asciidoc

@@ -3,32 +3,48 @@
 
 [partintro]
 --
-*elasticsearch* provides a full Query DSL based on JSON to define
-queries. In general, there are basic queries such as
-<<query-dsl-term-query,term>> or
-<<query-dsl-prefix-query,prefix>>. There are
-also compound queries like the
-<<query-dsl-bool-query,bool>> query.
-
-While queries have scoring capabilities, in some contexts they will
-only be used to filter the result set, such as in the
-<<query-dsl-filtered-query,filtered>> or
-<<query-dsl-constant-score-query,constant_score>>
-queries.
-
-Think of the Query DSL as an AST of queries.
-Some queries can be used by themselves like the
-<<query-dsl-term-query,term>> query but other queries can contain
-queries (like the <<query-dsl-bool-query,bool>> query), and each
-of these composite queries can contain *any* query of the list of
-queries, resulting in the ability to build quite
-complex (and interesting) queries.
-
-Queries can be used in different APIs. For example,
-within a <<search-request-query,search query>>, or
-as an <<search-aggregations-bucket-filter-aggregation,aggregation filter>>.
-This section explains the queries that can form the AST one can use.
 
+Elasticsearch provides a full Query DSL based on JSON to define queries.
+Think of the Query DSL as an AST of queries, consisting of two types of
+clauses:
+
+Leaf query clauses::
+
+Leaf query clauses look for a particular value in a particular field, such as the
+<<query-dsl-match-query,`match`>>, <<query-dsl-term-query,`term`>> or
+<<query-dsl-range-query,`range`>> queries.  These queries can be used
+by themselves.
+
+Compound query clauses::
+
+Compound query clauses wrap other leaf *or* compound queries and are used to combine
+multiple queries in a logical fashion (such as the
+<<query-dsl-bool-query,`bool`>> or <<query-dsl-dis-max-query,`dis_max`>> query),
+or to alter their behaviour (such as the <<query-dsl-not-query,`not`>> or
+<<query-dsl-constant-score-query,`constant_score`>> query).
+
+Query clauses behave differently depending on whether they are used in
+<<query-filter-context,query context or filter context>>.
 --
 
-include::query-dsl/index.asciidoc[]
+include::query-dsl/query_filter_context.asciidoc[]
+
+include::query-dsl/match-all-query.asciidoc[]
+
+include::query-dsl/full-text-queries.asciidoc[]
+
+include::query-dsl/term-level-queries.asciidoc[]
+
+include::query-dsl/compound-queries.asciidoc[]
+
+include::query-dsl/joining-queries.asciidoc[]
+
+include::query-dsl/geo-queries.asciidoc[]
+
+include::query-dsl/special-queries.asciidoc[]
+
+include::query-dsl/span-queries.asciidoc[]
+
+include::query-dsl/minimum-should-match.asciidoc[]
+
+include::query-dsl/multi-term-rewrite.asciidoc[]

docs/reference/query-dsl/and-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-and-query]]
-== And Query
+=== And Query
 
 deprecated[2.0.0, Use the `bool` query instead]
 

docs/reference/query-dsl/bool-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-bool-query]]
-== Bool Query
+=== Bool Query
 
 A query that matches documents matching boolean combinations of other
 queries. The bool query maps to Lucene `BooleanQuery`. It is built using

docs/reference/query-dsl/boosting-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-boosting-query]]
-== Boosting Query
+=== Boosting Query
 
 The `boosting` query can be used to effectively demote results that
 match a given query. Unlike the "NOT" clause in bool query, this still

docs/reference/query-dsl/common-terms-query.asciidoc

@@ -1,12 +1,12 @@
 [[query-dsl-common-terms-query]]
-== Common Terms Query
+=== Common Terms Query
 
 The `common` terms query is a modern alternative to stopwords which
 improves the precision and recall of search results (by taking stopwords
 into account), without sacrificing performance.
 
 [float]
-=== The problem
+==== The problem
 
 Every term in a query has a cost. A search for `"The brown fox"`
 requires three term queries, one for each of `"the"`, `"brown"` and
@@ -25,7 +25,7 @@ and `"not happy"`) and we lose recall (eg text like `"The The"` or
 `"To be or not to be"` would simply not exist in the index).
 
 [float]
-=== The solution
+==== The solution
 
 The `common` terms query divides the query terms into two groups: more
 important (ie _low frequency_ terms) and less important (ie _high
@@ -63,7 +63,7 @@ site, common terms like `"clip"` or `"video"` will automatically behave
 as stopwords without the need to maintain a manual list.
 
 [float]
-=== Examples
+==== Examples
 
 In this example, words that have a document frequency greater than 0.1%
 (eg `"this"` and `"is"`) will be treated as _common terms_.

docs/reference/query-dsl/compound-queries.asciidoc

@@ -0,0 +1,69 @@
+[[compound-queries]]
+== Compound queries
+
+Compound queries wrap other compound or leaf queries, either to combine their
+results and scores, to change their behaviour, or to switch from query to
+filter context.
+
+The queries in this group are:
+
+<<query-dsl-constant-score-query,`constant_score` query>>::
+
+A query which wraps another query, but executes it in filter context.  All
+matching documents are given the same ``constant'' `_score`.
+
+<<query-dsl-bool-query,`bool` query>>::
+
+The default query for combining multiple leaf or compound query clauses, as
+`must`, `should`, `must_not`, or `filter` clauses.  The `must` and `should`
+clauses have their scores combined -- the more matching clauses, the better --
+while the `must_not` and `filter` clauses are executed in filter context.
+
+<<query-dsl-dis-max-query,`dis_max` query>>::
+
+A query which accepts multiple queries, and returns any documents which match
+any of the query clauses.  While the `bool` query combines the scores from all
+matching queries, the `dis_max` query uses the score of the single best-
+matching query clause.
+
+<<query-dsl-function-score-query,`function_score` query>>::
+
+Modify the scores returned by the main query with functions to take into
+account factors like popularity, recency, distance, or custom algorithms
+implemented with scripting.
+
+<<query-dsl-boosting-query,`boosting` query>>::
+
+Return documents which match a `positive` query, but reduce the score of
+documents which also match a `negative` query.
+
+<<query-dsl-indices-query,`indices` query>>::
+
+Execute one query for the specified indices, and another for other indices.
+
+<<query-dsl-and-query,`and`>>, <<query-dsl-or-query,`or`>>, <<query-dsl-not-query,`not`>>::
+
+Synonyms for the `bool` query.
+
+<<query-dsl-filtered-query,`filtered` query>>::
+
+Combine a query clause in query context with another in filter context. deprecated[2.0.0,Use the `bool` query instead]
+
+<<query-dsl-limit-query,`limit` query>>::
+
+Limits the number of documents examined per shard. deprecated[1.6.0]
+
+
+include::constant-score-query.asciidoc[]
+include::bool-query.asciidoc[]
+include::dis-max-query.asciidoc[]
+include::function-score-query.asciidoc[]
+include::boosting-query.asciidoc[]
+include::indices-query.asciidoc[]
+include::and-query.asciidoc[]
+include::not-query.asciidoc[]
+include::or-query.asciidoc[]
+include::filtered-query.asciidoc[]
+include::limit-query.asciidoc[]
+
+

docs/reference/query-dsl/constant-score-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-constant-score-query]]
-== Constant Score Query
+=== Constant Score Query
 
 A query that wraps another query and simply returns a
 constant score equal to the query boost for every document in the

docs/reference/query-dsl/dis-max-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-dis-max-query]]
-== Dis Max Query
+=== Dis Max Query
 
 A query that generates the union of documents produced by its
 subqueries, and that scores each document with the maximum score for

docs/reference/query-dsl/exists-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-exists-query]]
-== Exists Query
+=== Exists Query
 
 Returns documents that have at least one non-`null` value in the original field:
 
@@ -42,7 +42,7 @@ These documents would *not* match the above query:
 <3> The `user` field is missing completely.
 
 [float]
-==== `null_value` mapping
+===== `null_value` mapping
 
 If the field mapping includes the `null_value` setting (see <<mapping-core-types>>)
 then explicit `null` values are replaced with the specified `null_value`.  For

docs/reference/query-dsl/filtered-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-filtered-query]]
-== Filtered Query
+=== Filtered Query
 
 deprecated[2.0.0, Use the `bool` query instead with a `must` clause for the query and a `filter` clause for the filter]
 
@@ -47,7 +47,7 @@ curl -XGET localhost:9200/_search -d '
 <1> The `filtered` query is passed as the value of the `query`
     parameter in the search request.
 
-=== Filtering without a query
+==== Filtering without a query
 
 If a `query` is not specified, it defaults to the
 <<query-dsl-match-all-query,`match_all` query>>.  This means that the
@@ -71,7 +71,7 @@ curl -XGET localhost:9200/_search -d '
 <1> No `query` has been specified, so this request applies just the filter,
    returning all documents created since yesterday.
 
-==== Multiple filters
+===== Multiple filters
 
 Multiple filters can be applied by wrapping them in a
 <<query-dsl-bool-query,`bool` query>>, for example:
@@ -95,7 +95,7 @@ Multiple filters can be applied by wrapping them in a
 }
 --------------------------------------------------
 
-==== Filter strategy
+===== Filter strategy
 
 You can control how the filter and query are executed with the `strategy`
 parameter:

docs/reference/query-dsl/full-text-queries.asciidoc

@@ -0,0 +1,44 @@
+[[full-text-queries]]
+== Full text queries
+
+The high-level full text queries are usually used for running full text
+queries on full text fields like the body of an email. They understand how the
+field being queried is <<analysis,analyzed>> and will apply each field's
+`analyzer` (or `search_analyzer`) to the query string before executing.
+
+The queries in this group are:
+
+<<query-dsl-match-query,`match` query>>::
+
+    The standard query for performing full text queries, including fuzzy matching
+    and phrase or proximity queries.
+
+<<query-dsl-multi-match-query,`multi_match` query>>::
+
+    The multi-field version of the `match` query.
+
+<<query-dsl-common-terms-query,`common_terms` query>>::
+
+    A more specialized query which gives more preference to uncommon words.
+
+<<query-dsl-query-string-query,`query_string` query>>::
+
+    Supports the compact Lucene <<query-string-syntax,query string syntax>>,
+    allowing you to specify AND|OR|NOT conditions and multi-field search
+    within a single query string. For expert users only.
+
+<<query-dsl-simple-query-string-query,`simple_query_string`>>::
+
+    A simpler, more robust version of the `query_string` syntax suitable
+    for exposing directly to users.
+
+include::match-query.asciidoc[]
+
+include::multi-match-query.asciidoc[]
+
+include::common-terms-query.asciidoc[]
+
+include::query-string-query.asciidoc[]
+
+include::simple-query-string-query.asciidoc[]
+

docs/reference/query-dsl/function-score-query.asciidoc

@@ -1,15 +1,13 @@
 [[query-dsl-function-score-query]]
-== Function Score Query
+=== Function Score Query
 
 The `function_score` allows you to modify the score of documents that are
 retrieved by a query. This can be useful if, for example, a score
 function is computationally expensive and it is sufficient to compute
 the score on a filtered set of documents.
 
-=== Using function score
-
 To use `function_score`, the user has to define a query and one or
-several functions, that compute a new score for each document returned
+more functions, that compute a new score for each document returned
 by the query.
 
 `function_score` can be used with only one function like this:
@@ -89,13 +87,13 @@ query. The parameter `boost_mode` defines how:
 `min`::         min of query score and function score
 
 By default, modifying the score does not change which documents match. To exclude
-documents that do not meet a certain score threshold the `min_score` parameter can be set to the desired score threshold.  
+documents that do not meet a certain score threshold the `min_score` parameter can be set to the desired score threshold.
 
 ==== Score functions
 
 The `function_score` query provides several types of score functions.
 
-===== Script score
+====== Script score
 
 The `script_score` function allows you to wrap another query and customize
 the scoring of it optionally with a computation derived from other numeric
@@ -135,7 +133,7 @@ Note that unlike the `custom_score` query, the
 score of the query is multiplied with the result of the script scoring. If
 you wish to inhibit this, set `"boost_mode": "replace"`
 
-===== Weight
+====== Weight
 
 The `weight` score allows you to multiply the score by the provided
 `weight`. This can sometimes be desired since boost value set on
@@ -147,7 +145,7 @@ not.
 "weight" : number
 --------------------------------------------------
 
-===== Random
+====== Random
 
 The `random_score` generates scores using a hash of the `_uid` field,
 with a `seed` for variation. If `seed` is not specified, the current
@@ -163,7 +161,7 @@ be a memory intensive operation since the values are unique.
 }
 --------------------------------------------------
 
-===== Field Value factor
+====== Field Value factor
 
 The `field_value_factor` function allows you to use a field from a document to
 influence the score. It's similar to using the `script_score` function, however,
@@ -207,7 +205,7 @@ is an illegal operation, and an exception will be thrown. Be sure to limit the
 values of the field with a range filter to avoid this, or use `log1p` and
 `ln1p`.
 
-===== Decay functions
+====== Decay functions
 
 Decay functions score a document with a function that decays depending
 on the distance of a numeric field value of the document from a user
@@ -254,13 +252,13 @@ The `offset` and `decay` parameters are optional.
 
 [horizontal]
 `origin`::
-    The point of origin used for calculating distance. Must be given as a 
-    number for numeric field, date for date fields and geo point for geo fields. 
+    The point of origin used for calculating distance. Must be given as a
+    number for numeric field, date for date fields and geo point for geo fields.
     Required for geo and numeric field. For date fields the default is `now`. Date
     math (for example `now-1h`) is supported for origin.
 
 `scale`::
-    Required for all types. Defines the distance from origin at which the computed 
+    Required for all types. Defines the distance from origin at which the computed
     score will equal `decay` parameter. For geo fields: Can be defined as number+unit (1km, 12m,...).
     Default unit is meters. For date fields: Can to be defined as a number+unit ("1h", "10d",...).
     Default unit is milliseconds. For numeric field: Any number.
@@ -334,7 +332,7 @@ For single functions the three decay functions together with their parameters ca
 
 image:images/decay_2d.png[width=600]
 
-===== Multiple values:
+====== Multiple values:
 
 If a field used for computing the decay contains multiple values, per default the value closest to the origin is chosen for determining the distance.
 This can be changed by setting `multi_value_mode`.
@@ -360,7 +358,7 @@ Example:
 
 
 
-==== Detailed example
+===== Detailed example
 
 Suppose you are searching for a hotel in a certain town. Your budget is
 limited. Also, you would like the hotel to be close to the town center,
@@ -450,7 +448,7 @@ curl 'localhost:9200/hotels/_search/' -d '{
 Next, we show how the computed score looks like for each of the three
 possible decay functions.
 
-===== Normal decay, keyword `gauss`
+====== Normal decay, keyword `gauss`
 
 When choosing `gauss` as the decay function in the above example, the
 contour and surface plot of the multiplier looks like this:
@@ -471,7 +469,7 @@ of 0.56. "BnB Bellevue" and "Backback Nap" are both pretty close to the
 defined location but "BnB Bellevue" is cheaper, so it gets a multiplier
 of 0.86 whereas "Backpack Nap" gets a value of 0.66.
 
-===== Exponential decay, keyword `exp`
+====== Exponential decay, keyword `exp`
 
 When choosing `exp` as the decay function in the above example, the
 contour and surface plot of the multiplier looks like this:
@@ -480,7 +478,7 @@ image::https://f.cloud.github.com/assets/4320215/768161/082975c0-e899-11e2-86f7-
 
 image::https://f.cloud.github.com/assets/4320215/768162/0b606884-e899-11e2-907b-aefc77eefef6.png[width="700px"]
 
-===== Linear' decay, keyword `linear`
+====== Linear' decay, keyword `linear`
 
 When choosing `linear` as the decay function in the above example, the
 contour and surface plot of the multiplier looks like this:
@@ -489,12 +487,12 @@ image::https://f.cloud.github.com/assets/4320215/768164/1775b0ca-e899-11e2-9f4a-
 
 image::https://f.cloud.github.com/assets/4320215/768165/19d8b1aa-e899-11e2-91bc-6b0553e8d722.png[width="700px"]
 
-==== Supported fields for decay functions
+===== Supported fields for decay functions
 
 Only single valued numeric fields, including time and geo locations,
 are supported.
 
-==== What if a field is missing?
+===== What if a field is missing?
 
 If the numeric field is missing in the document, the function will
 return 1.

docs/reference/query-dsl/fuzzy-query.asciidoc

@@ -1,10 +1,10 @@
 [[query-dsl-fuzzy-query]]
-== Fuzzy Query
+=== Fuzzy Query
 
 The fuzzy query uses similarity based on Levenshtein edit distance for
 `string` fields, and a `+/-` margin on numeric and date fields.
 
-=== String fields
+==== String fields
 
 The `fuzzy` query generates all possible matching terms that are within  the
 maximum edit distance specified in `fuzziness` and then checks the term
@@ -38,7 +38,7 @@ Or with more advanced settings:
 --------------------------------------------------
 
 [float]
-==== Parameters
+===== Parameters
 
 [horizontal]
 `fuzziness`::
@@ -62,7 +62,7 @@ are both set to `0`. This could cause every term in the index to be examined!
 
 
 [float]
-=== Numeric and date fields
+==== Numeric and date fields
 
 Performs a <<query-dsl-range-query>> ``around'' the value using the
 `fuzziness` value as a `+/-` range, where:

docs/reference/query-dsl/geo-bounding-box-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-geo-bounding-box-query]]
-== Geo Bounding Box Query
+=== Geo Bounding Box Query
 
 A query allowing to filter hits based on a point location using a
 bounding box. Assuming the following indexed document:
@@ -45,13 +45,13 @@ Then the following simple query can be executed with a
 --------------------------------------------------
 
 [float]
-=== Accepted Formats
+==== Accepted Formats
 
 In much the same way the geo_point type can accept different
 representation of the geo point, the filter can accept it as well:
 
 [float]
-==== Lat Lon As Properties
+===== Lat Lon As Properties
 
 [source,js]
 --------------------------------------------------
@@ -79,7 +79,7 @@ representation of the geo point, the filter can accept it as well:
 --------------------------------------------------
 
 [float]
-==== Lat Lon As Array
+===== Lat Lon As Array
 
 Format in `[lon, lat]`, note, the order of lon/lat here in order to
 conform with http://geojson.org/[GeoJSON].
@@ -104,7 +104,7 @@ conform with http://geojson.org/[GeoJSON].
 --------------------------------------------------
 
 [float]
-==== Lat Lon As String
+===== Lat Lon As String
 
 Format in `lat,lon`.
 
@@ -128,7 +128,7 @@ Format in `lat,lon`.
 --------------------------------------------------
 
 [float]
-==== Geohash
+===== Geohash
 
 [source,js]
 --------------------------------------------------
@@ -150,7 +150,7 @@ Format in `lat,lon`.
 --------------------------------------------------
 
 [float]
-=== Vertices
+==== Vertices
 
 The vertices of the bounding box can either be set by `top_left` and
 `bottom_right` or by `top_right` and `bottom_left` parameters. More
@@ -182,20 +182,20 @@ values separately.
 
 
 [float]
-=== geo_point Type
+==== geo_point Type
 
 The filter *requires* the `geo_point` type to be set on the relevant
 field.
 
 [float]
-=== Multi Location Per Document
+==== Multi Location Per Document
 
 The filter can work with multiple locations / points per document. Once
 a single location / point matches the filter, the document will be
 included in the filter
 
 [float]
-=== Type
+==== Type
 
 The type of the bounding box execution by default is set to `memory`,
 which means in memory checks if the doc falls within the bounding box

docs/reference/query-dsl/geo-distance-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-geo-distance-query]]
-== Geo Distance Query
+=== Geo Distance Query
 
 Filters documents that include only hits that exists within a specific
 distance from a geo point. Assuming the following indexed json:
@@ -40,13 +40,13 @@ filter:
 --------------------------------------------------
 
 [float]
-=== Accepted Formats
+==== Accepted Formats
 
 In much the same way the `geo_point` type can accept different
 representation of the geo point, the filter can accept it as well:
 
 [float]
-==== Lat Lon As Properties
+===== Lat Lon As Properties
 
 [source,js]
 --------------------------------------------------
@@ -69,7 +69,7 @@ representation of the geo point, the filter can accept it as well:
 --------------------------------------------------
 
 [float]
-==== Lat Lon As Array
+===== Lat Lon As Array
 
 Format in `[lon, lat]`, note, the order of lon/lat here in order to
 conform with http://geojson.org/[GeoJSON].
@@ -92,7 +92,7 @@ conform with http://geojson.org/[GeoJSON].
 --------------------------------------------------
 
 [float]
-==== Lat Lon As String
+===== Lat Lon As String
 
 Format in `lat,lon`.
 
@@ -114,7 +114,7 @@ Format in `lat,lon`.
 --------------------------------------------------
 
 [float]
-==== Geohash
+===== Geohash
 
 [source,js]
 --------------------------------------------------
@@ -134,7 +134,7 @@ Format in `lat,lon`.
 --------------------------------------------------
 
 [float]
-=== Options
+==== Options
 
 The following are options allowed on the filter:
 
@@ -160,13 +160,13 @@ The following are options allowed on the filter:
 
 
 [float]
-=== geo_point Type
+==== geo_point Type
 
 The filter *requires* the `geo_point` type to be set on the relevant
 field.
 
 [float]
-=== Multi Location Per Document
+==== Multi Location Per Document
 
 The `geo_distance` filter can work with multiple locations / points per
 document. Once a single location / point matches the filter, the

docs/reference/query-dsl/geo-distance-range-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-geo-distance-range-query]]
-== Geo Distance Range Query
+=== Geo Distance Range Query
 
 Filters documents that exists within a range from a specific point:
 

docs/reference/query-dsl/geo-polygon-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-geo-polygon-query]]
-== Geo Polygon Query
+=== Geo Polygon Query
 
 A query allowing to include hits that only fall within a polygon of
 points. Here is an example:
@@ -27,10 +27,10 @@ points. Here is an example:
 --------------------------------------------------
 
 [float]
-=== Allowed Formats
+==== Allowed Formats
 
 [float]
-==== Lat Long as Array
+===== Lat Long as Array
 
 Format in `[lon, lat]`, note, the order of lon/lat here in order to
 conform with http://geojson.org/[GeoJSON].
@@ -58,7 +58,7 @@ conform with http://geojson.org/[GeoJSON].
 --------------------------------------------------
 
 [float]
-==== Lat Lon as String
+===== Lat Lon as String
 
 Format in `lat,lon`.
 
@@ -85,7 +85,7 @@ Format in `lat,lon`.
 --------------------------------------------------
 
 [float]
-==== Geohash
+===== Geohash
 
 [source,js]
 --------------------------------------------------
@@ -110,7 +110,7 @@ Format in `lat,lon`.
 --------------------------------------------------
 
 [float]
-=== geo_point Type
+==== geo_point Type
 
 The filter *requires* the
 <<mapping-geo-point-type,geo_point>> type to be

docs/reference/query-dsl/geo-queries.asciidoc

@@ -0,0 +1,50 @@
+[[geo-queries]]
+== Geo queries
+
+Elasticsearch supports two types of geo data:
+<<mapping-geo-point-type,`geo_point`>> fields which support lat/lon pairs, and
+<<mapping-geo-shape-type,`geo_shape`>> fields, which support points,
+lines, circles, polygons, multi-polygons etc.
+
+The queries in this group are:
+
+<<query-dsl-geo-shape-query,`geo_shape`>> query::
+
+    Find document with geo-shapes which either intersect, are contained by, or
+    do not interesect with the specified geo-shape.
+
+<<query-dsl-geo-bounding-box-query,`geo_bounding_box`>> query::
+
+    Finds documents with geo-points that fall into the specified rectangle.
+
+<<query-dsl-geo-distance-query,`geo_distance`>> query::
+
+    Finds document with geo-points within the specified distance of a central
+    point.
+
+<<query-dsl-geo-distance-range-query,`geo_distance_range`>> query::
+
+    Like the `geo_point` query, but the range starts at a specified distance
+    from the central point.
+
+<<query-dsl-geo-polygon-query,`geo_polygon`>> query::
+
+    Find documents with geo-points within the specified polygon.
+
+<<query-dsl-geohash-cell-query,`geohash_cell`>> query::
+
+    Find geo-points whose geohash intersects with the geohash of the specified
+    point.
+
+
+include::geo-shape-query.asciidoc[]
+
+include::geo-bounding-box-query.asciidoc[]
+
+include::geo-distance-query.asciidoc[]
+
+include::geo-distance-range-query.asciidoc[]
+
+include::geo-polygon-query.asciidoc[]
+
+include::geohash-cell-query.asciidoc[]

docs/reference/query-dsl/geo-shape-query.asciidoc

@@ -1,17 +1,15 @@
 [[query-dsl-geo-shape-query]]
-== GeoShape Filter
+=== GeoShape Filter
 
 Filter documents indexed using the `geo_shape` type.
 
-Requires the <<mapping-geo-shape-type,geo_shape
-Mapping>>.
+Requires the <<mapping-geo-shape-type,geo_shape Mapping>>.
 
 The `geo_shape` query uses the same grid square representation as the
 geo_shape mapping to find documents that have a shape that intersects
 with the query shape. It will also use the same PrefixTree configuration
 as defined for the field mapping.
 
-[float]
 ==== Filter Format
 
 The Filter supports two ways of defining the Filter shape, either by
@@ -19,8 +17,7 @@ providing a whole shape definition, or by referencing the name of a shape
 pre-indexed in another index. Both formats are defined below with
 examples.
 
-[float]
-===== Provided Shape Definition
+====== Provided Shape Definition
 
 Similar to the `geo_shape` type, the `geo_shape` Filter uses
 http://www.geojson.org[GeoJSON] to represent shapes.
@@ -64,7 +61,6 @@ The following query will find the point using the Elasticsearch's
 }
 --------------------------------------------------
 
-[float]
 ===== Pre-Indexed Shape
 
 The Filter also supports using a shape which has already been indexed in

docs/reference/query-dsl/geohash-cell-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-geohash-cell-query]]
-== Geohash Cell Query
+=== Geohash Cell Query
 
 The `geohash_cell` query provides access to a hierarchy of geohashes.
 By defining a geohash cell, only <<mapping-geo-point-type,geopoints>>

docs/reference/query-dsl/has-child-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-has-child-query]]
-== Has Child Query
+=== Has Child Query
 
 The `has_child` filter accepts a query and the child type to run against, and
 results in parent documents that have child docs matching the query. Here is
@@ -20,7 +20,7 @@ an example:
 --------------------------------------------------
 
 [float]
-=== Scoring capabilities
+==== Scoring capabilities
 
 The `has_child` also has scoring support. The
 supported score types are `min`, `max`, `sum`, `avg` or `none`. The default is
@@ -46,7 +46,7 @@ inside the `has_child` query:
 --------------------------------------------------
 
 [float]
-=== Min/Max Children
+==== Min/Max Children
 
 The `has_child` query allows you to specify that a minimum and/or maximum
 number of children are required to match for the parent doc to be considered

docs/reference/query-dsl/has-parent-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-has-parent-query]]
-== Has Parent Query
+=== Has Parent Query
 
 The `has_parent` query accepts a query and a parent type. The query is
 executed in the parent document space, which is specified by the parent
@@ -22,7 +22,7 @@ in the same manner as the `has_child` query.
 --------------------------------------------------
 
 [float]
-=== Scoring capabilities
+==== Scoring capabilities
 
 The `has_parent` also has scoring support. The
 supported score types are `score` or `none`. The default is `none` and

docs/reference/query-dsl/ids-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-ids-query]]
-== Ids Query
+=== Ids Query
 
 Filters documents that only have the provided ids. Note, this query
 uses the <<mapping-uid-field,_uid>> field.

docs/reference/query-dsl/index.asciidoc

@@ -1,3 +1,5 @@
+include::query_filter_context.asciidoc[]
+
 include::match-query.asciidoc[]
 
 include::multi-match-query.asciidoc[]

docs/reference/query-dsl/indices-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-indices-query]]
-== Indices Query
+=== Indices Query
 
 The `indices` query can be used when executed across multiple indices,
 allowing to have a query that executes only when executed on an index
@@ -29,9 +29,9 @@ documents), and `all` (to match all). Defaults to `all`.
 `query` is mandatory, as well as `indices` (or `index`).
 
 [TIP]
-===================================================================
+====================================================================
 The fields order is important: if the `indices` are provided before `query`
 or `no_match_query`, the related queries get parsed only against the indices
 that they are going to be executed on. This is useful to avoid parsing queries
 when it is not necessary and prevent potential mapping errors.
-===================================================================
+====================================================================

docs/reference/query-dsl/joining-queries.asciidoc

@@ -0,0 +1,32 @@
+[[joining-queries]]
+== Joining queries
+
+Performing full SQL-style joins in a distributed system like Elasticsearch is
+prohibitively expensive.  Instead, Elasticsearch offers two forms of join
+which are designed to scale horizontally.
+
+<<query-dsl-nested-query,`nested` query>>::
+
+Documents may contains fields of type <<mapping-nested-type,`nested`>>. These
+fields are used to index arrays of objects, where each object can be queried
+(with the `nested` query) as an independent document.
+
+<<query-dsl-has-child-query,`has_child`>> and <<query-dsl-has-parent-query,`has_parent`>> queries::
+
+A <<mapping-parent-field,parent-child relationship>> can exist between two
+document types within a single index. The `has_child` query returns parent
+documents whose child documents match the specified query, while the
+`has_parent` query returns child documents whose parent document matches the
+specified query.
+
+Also see the <<query-dsl-terms-lookup,terms-lookup mechanism>> in the `terms`
+query, which allows you to build a `terms` query from values contained in
+another document.
+
+include::nested-query.asciidoc[]
+
+include::has-child-query.asciidoc[]
+
+include::has-parent-query.asciidoc[]
+
+

docs/reference/query-dsl/limit-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-limit-query]]
-== Limit Query
+=== Limit Query
 
 deprecated[1.6.0, Use <<search-request-body,terminate_after>> instead]
 

docs/reference/query-dsl/match-all-query.asciidoc

@@ -1,20 +1,17 @@
 [[query-dsl-match-all-query]]
 == Match All Query
 
-A query that matches all documents. Maps to Lucene `MatchAllDocsQuery`.
+The most simple query, which matches all documents, giving them all a `_score`
+of `1.0`.
 
 [source,js]
 --------------------------------------------------
-{
-    "match_all" : { }
-}
+{ "match_all": {} }
 --------------------------------------------------
 
-Which can also have boost associated with it:
+The `_score` can be changed with the `boost` parameter:
 
 [source,js]
 --------------------------------------------------
-{
-    "match_all" : { "boost" : 1.2 }
-}
+{ "match_all": { "boost" : 1.2 }}
 --------------------------------------------------

docs/reference/query-dsl/match-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-match-query]]
-== Match Query
+=== Match Query
 
 A family of `match` queries that accept text/numerics/dates, analyzes
 it, and constructs a query out of it. For example:
@@ -16,10 +16,8 @@ it, and constructs a query out of it. For example:
 Note, `message` is the name of a field, you can substitute the name of
 any field (including `_all`) instead.
 
-[float]
-=== Types of Match Queries
+There are three types of `match` query: `boolean`, `phrase`, and `phrase_prefix`:
 
-[float]
 [[query-dsl-match-query-boolean]]
 ==== boolean
 
@@ -40,8 +38,7 @@ data-type mismatches,  such as trying to query a numeric field with a text
 query string. Defaults to `false`.
 
 [[query-dsl-match-query-fuzziness]]
-[float]
-===== Fuzziness
+====== Fuzziness
 
 `fuzziness` allows _fuzzy matching_ based on the type of field being queried.
 See <<fuzziness>> for allowed settings.
@@ -69,7 +66,6 @@ change in structure, `message` is the field name):
 --------------------------------------------------
 
 [[query-dsl-match-query-zero]]
-[float]
 ===== Zero terms query
 If the analyzer used removes all tokens in a query like a `stop` filter
 does, the default behavior is to match no documents at all. In order to
@@ -90,7 +86,6 @@ change that the `zero_terms_query` option can be used, which accepts
 --------------------------------------------------
 
 [[query-dsl-match-query-cutoff]]
-[float]
 ===== Cutoff frequency
 
 The match query supports a `cutoff_frequency` that allows
@@ -132,7 +127,6 @@ that when trying it out on test indexes with low document numbers you
 should follow the advice in {defguide}/relevance-is-broken.html[Relevance is broken].
 
 [[query-dsl-match-query-phrase]]
-[float]
 ==== phrase
 
 The `match_phrase` query analyzes the text and creates a `phrase` query
@@ -181,9 +175,8 @@ definition, or the default search analyzer, for example:
 }
 --------------------------------------------------
 
-[float]
 [[query-dsl-match-query-phrase-prefix]]
-===== match_phrase_prefix
+==== match_phrase_prefix
 
 The `match_phrase_prefix` is the same as `match_phrase`, except that it
 allows for prefix matches on the last term in the text. For example:

docs/reference/query-dsl/missing-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-missing-query]]
-== Missing Query
+=== Missing Query
 
 Returns documents that have only `null` values or no value in the original field:
 
@@ -42,7 +42,7 @@ These documents would *not* match the above filter:
 <3> This field has one non-`null` value.
 
 [float]
-=== `null_value` mapping
+==== `null_value` mapping
 
 If the field mapping includes a `null_value` (see <<mapping-core-types>>) then explicit `null` values
 are replaced with the specified `null_value`.  For instance, if the `user` field were mapped
@@ -75,7 +75,7 @@ no values in the `user` field and thus would match the `missing` filter:
 --------------------------------------------------
 
 [float]
-==== `existence` and `null_value` parameters
+===== `existence` and `null_value` parameters
 
 When the field being queried has a `null_value` mapping, then the behaviour of
 the `missing` filter can be altered with the `existence` and `null_value`

docs/reference/query-dsl/mlt-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-mlt-query]]
-== More Like This Query
+=== More Like This Query
 
 The More Like This Query (MLT Query) finds documents that are "like" a given
 set of documents. In order to do so, MLT selects a set of representative terms
@@ -87,7 +87,7 @@ present in the index, the syntax is similar to <<docs-termvectors-artificial-doc
 }
 --------------------------------------------------
 
-=== How it Works
+==== How it Works
 
 Suppose we wanted to find all documents similar to a given input document.
 Obviously, the input document itself should be its best match for that type of
@@ -139,14 +139,14 @@ curl -s -XPUT 'http://localhost:9200/imdb/' -d '{
 }
 --------------------------------------------------
 
-=== Parameters
+==== Parameters
 
 The only required parameter is `like`, all other parameters have sensible
 defaults. There are three types of parameters: one to specify the document
 input, the other one for term selection and for query formation.
 
 [float]
-=== Document Input Parameters
+==== Document Input Parameters
 
 [horizontal]
 `like`:: coming[2.0]
@@ -179,7 +179,7 @@ A list of documents following the same syntax as the <<docs-multi-get,Multi GET
 
 [float]
 [[mlt-query-term-selection]]
-=== Term Selection Parameters
+==== Term Selection Parameters
 
 [horizontal]
 `max_query_terms`::
@@ -219,7 +219,7 @@ The analyzer that is used to analyze the free form text. Defaults to the
 analyzer associated with the first field in `fields`.
 
 [float]
-=== Query Formation Parameters
+==== Query Formation Parameters
 
 [horizontal]
 `minimum_should_match`::

docs/reference/query-dsl/multi-match-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-multi-match-query]]
-== Multi Match Query
+=== Multi Match Query
 
 The `multi_match` query builds on the <<query-dsl-match-query,`match` query>>
 to allow multi-field queries:
@@ -17,7 +17,7 @@ to allow multi-field queries:
 <2> The fields to be queried.
 
 [float]
-=== `fields` and per-field boosting
+==== `fields` and per-field boosting
 
 Fields can be specified with wildcards, eg:
 
@@ -47,7 +47,7 @@ Individual fields can be boosted with the caret (`^`) notation:
 
 [[multi-match-types]]
 [float]
-=== Types of `multi_match` query:
+==== Types of `multi_match` query:
 
 The way the `multi_match` query is executed internally depends on the `type`
 parameter, which can be set to:
@@ -70,7 +70,7 @@ parameter, which can be set to:
                     combines the `_score` from each field.  See <<type-phrase>>.
 
 [[type-best-fields]]
-=== `best_fields`
+==== `best_fields`
 
 The `best_fields` type is most useful when you are searching for multiple
 words best found in the same field. For instance ``brown fox'' in a single
@@ -121,7 +121,7 @@ and `cutoff_frequency`, as explained in <<query-dsl-match-query, match query>>.
 [IMPORTANT]
 [[operator-min]]
 .`operator` and `minimum_should_match`
-==================================================
+===================================================
 
 The `best_fields` and `most_fields` types are _field-centric_ -- they generate
 a `match` query *per field*.  This means that the `operator` and
@@ -153,10 +153,10 @@ to match.
 
 See <<type-cross-fields>> for a better solution.
 
-==================================================
+===================================================
 
 [[type-most-fields]]
-=== `most_fields`
+==== `most_fields`
 
 The `most_fields` type is most useful when querying multiple fields that
 contain the same text analyzed in different ways.  For instance, the main
@@ -203,7 +203,7 @@ and `cutoff_frequency`, as explained in <<query-dsl-match-query,match query>>, b
 *see <<operator-min>>*.
 
 [[type-phrase]]
-=== `phrase` and `phrase_prefix`
+==== `phrase` and `phrase_prefix`
 
 The `phrase` and `phrase_prefix` types behave just like <<type-best-fields>>,
 but they use a `match_phrase` or `match_phrase_prefix` query instead of a
@@ -240,7 +240,7 @@ in <<query-dsl-match-query>>.  Type `phrase_prefix` additionally accepts
 `max_expansions`.
 
 [[type-cross-fields]]
-=== `cross_fields`
+==== `cross_fields`
 
 The `cross_fields` type is particularly useful with structured documents where
 multiple fields *should* match.  For instance, when querying the `first_name`
@@ -317,7 +317,7 @@ Also, accepts `analyzer`, `boost`, `operator`, `minimum_should_match`,
 `zero_terms_query` and `cutoff_frequency`, as explained in
 <<query-dsl-match-query, match query>>.
 
-==== `cross_field` and analysis
+===== `cross_field` and analysis
 
 The `cross_field` type can only work in term-centric mode on fields that have
 the same analyzer. Fields with the same analyzer are grouped together as in
@@ -411,7 +411,7 @@ which will be executed as:
     blended("will",  fields: [first, first.edge, last.edge, last])
     blended("smith", fields: [first, first.edge, last.edge, last])
 
-==== `tie_breaker`
+===== `tie_breaker`
 
 By default, each per-term `blended` query will use the best score returned by
 any field in a group, then these scores are added together to give the final

docs/reference/query-dsl/nested-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-nested-query]]
-== Nested Query
+=== Nested Query
 
 Nested query allows to query nested objects / docs (see
 <<mapping-nested-type,nested mapping>>). The

docs/reference/query-dsl/not-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-not-query]]
-== Not Query
+=== Not Query
 
 A query that filters out matched documents using a query. For example:
 

docs/reference/query-dsl/or-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-or-query]]
-== Or Query
+=== Or Query
 
 deprecated[2.0.0, Use the `bool` query instead]
 

docs/reference/query-dsl/prefix-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-prefix-query]]
-== Prefix Query
+=== Prefix Query
 
 Matches documents that have fields containing terms with a specified
 prefix (*not analyzed*). The prefix query maps to Lucene `PrefixQuery`.

docs/reference/query-dsl/query-string-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-query-string-query]]
-== Query String Query
+=== Query String Query
 
 A query that uses a query parser in order to parse its content. Here is
 an example:
@@ -89,7 +89,7 @@ rewritten using the
 parameter.
 
 [float]
-=== Default Field
+==== Default Field
 
 When not explicitly specifying the field to search on in the query
 string syntax, the `index.query.default_field` will be used to derive
@@ -99,7 +99,7 @@ So, if `_all` field is disabled, it might make sense to change it to set
 a different default field.
 
 [float]
-=== Multi Field
+==== Multi Field
 
 The `query_string` query can also run against multiple fields. Fields can be
 provided via the `"fields"` parameter (example below).

docs/reference/query-dsl/query-string-syntax.asciidoc

@@ -1,6 +1,6 @@
 [[query-string-syntax]]
 
-=== Query string syntax
+==== Query string syntax
 
 The query string ``mini-language'' is used by the
 <<query-dsl-query-string-query>> and by the
@@ -14,7 +14,7 @@ phrase, in the same order.
 Operators allow you to customize the search -- the available options are
 explained below.
 
-==== Field names
+===== Field names
 
 As mentioned in <<query-dsl-query-string-query>>, the `default_field` is searched for the
 search terms, but it is possible to specify other fields in the query syntax:
@@ -46,7 +46,7 @@ search terms, but it is possible to specify other fields in the query syntax:
 
     _exists_:title
 
-==== Wildcards
+===== Wildcards
 
 Wildcard searches can be run on individual terms, using `?` to replace
 a single character, and `*` to replace zero or more characters:
@@ -58,12 +58,12 @@ perform very badly -- just think how many terms need to be queried to
 match the query string `"a* b* c*"`.
 
 [WARNING]
-======
+=======
 Allowing a wildcard at the beginning of a word (eg `"*ing"`) is particularly
 heavy, because all terms in the index need to be examined, just in case
 they match.  Leading wildcards can be disabled by setting
 `allow_leading_wildcard` to `false`.
-======
+=======
 
 Wildcarded terms are not analyzed by default -- they are lowercased
 (`lowercase_expanded_terms` defaults to `true`) but no further analysis
@@ -72,7 +72,7 @@ is missing some of its letters.  However, by setting `analyze_wildcard` to
 `true`, an attempt will be made to analyze wildcarded words before searching
 the term list for matching terms.
 
-==== Regular expressions
+===== Regular expressions
 
 Regular expression patterns can be embedded in the query string by
 wrapping them in forward-slashes (`"/"`):
@@ -82,7 +82,7 @@ wrapping them in forward-slashes (`"/"`):
 The supported regular expression syntax is explained in <<regexp-syntax>>.
 
 [WARNING]
-======
+=======
 The `allow_leading_wildcard` parameter does not have any control over
 regular expressions.  A query string such as the following would force
 Elasticsearch to visit every term in the index:
@@ -90,9 +90,9 @@ Elasticsearch to visit every term in the index:
     /.*n/
 
 Use with caution!
-======
+=======
 
-==== Fuzziness
+===== Fuzziness
 
 We can search for terms that are
 similar to, but not exactly like our search terms, using the ``fuzzy''
@@ -112,7 +112,7 @@ sufficient to catch 80% of all human misspellings. It can be specified as:
 
     quikc~1
 
-==== Proximity searches
+===== Proximity searches
 
 While a phrase query (eg `"john smith"`) expects all of the terms in exactly
 the same order, a proximity query allows the specified words to be further
@@ -127,7 +127,7 @@ query string, the more relevant that document is considered to be. When
 compared to the above example query, the phrase `"quick fox"` would be
 considered more relevant than `"quick brown fox"`.
 
-==== Ranges
+===== Ranges
 
 Ranges can be specified for date, numeric or string fields. Inclusive ranges
 are specified with square brackets `[min TO max]` and exclusive ranges with
@@ -168,20 +168,20 @@ Ranges with one side unbounded can use the following syntax:
     age:<=10
 
 [NOTE]
-===================================================================
+====================================================================
 To combine an upper and lower bound with the simplified syntax, you
 would need to join two clauses with an `AND` operator:
 
     age:(>=10 AND <20)
     age:(+>=10 +<20)
 
-===================================================================
+====================================================================
 
 The parsing of ranges in query strings can be complex and error prone. It is
 much more reliable to use an explicit <<query-dsl-range-query,`range` query>>.
 
 
-==== Boosting
+===== Boosting
 
 Use the _boost_ operator `^` to make one term more relevant than another.
 For instance, if we want to find all documents about foxes, but we are
@@ -196,7 +196,7 @@ Boosts can also be applied to phrases or to groups:
 
     "john smith"^2   (foo bar)^4
 
-==== Boolean operators
+===== Boolean operators
 
 By default, all terms are optional, as long as one term matches.  A search
 for `foo bar baz` will find any document that contains one or more of
@@ -256,7 +256,7 @@ would look like this:
 
 ****
 
-==== Grouping
+===== Grouping
 
 Multiple terms or clauses can be grouped together with parentheses, to form
 sub-queries:
@@ -268,7 +268,7 @@ of a sub-query:
 
     status:(active OR pending) title:(full text search)^2
 
-==== Reserved characters
+===== Reserved characters
 
 If you need to use any of the characters which function as operators in your
 query itself (and not as operators), then you should escape them with
@@ -290,7 +290,7 @@ index is actually `"wifi"`.  Escaping the space will protect it from
 being touched by the query string parser: `"wi\ fi"`.
 ****
 
-==== Empty Query
+===== Empty Query
 
 If the query string is empty or only contains whitespaces the query will
 yield an empty result set.

docs/reference/query-dsl/query_filter_context.asciidoc

@@ -0,0 +1,77 @@
+[[query-filter-context]]
+== Query and filter context
+
+The behaviour of a query clause depends on whether it is used in _query context_ or
+in _filter context_:
+
+Query context::
++
+--
+A query clause used in query context answers the question ``__How well does this
+document match this query clause?__'' Besides deciding whether or not the
+document matches, the query clause also calculated a `_score` representing how
+well the document matches, relative to other documents.
+
+Query context is in effect whenever a query clause is passed to a `query` parameter,
+such as the `query` parameter in the <<search-request-query,`search`>> API.
+--
+
+Filter context::
++
+--
+In _filter_ context, a query clause answers the question ``__Does this document
+match this query clause?__''  The answer is a simple Yes or No -- no scores are
+calculated.  Filter context is mostly used for filtering structured data, e.g.
+
+*  __Does this +timestamp+ fall into the range 2015 to 2016?__
+*  __Is the +status+  field set to ++"published"++__?
+
+Frequently used filters will be cached automatically by Elasticsearch, to
+speed up performance.
+
+Filter context is in effect whenever a query clause is passed to a `filter`
+parameter, such as the `filter` or `must_not` parameters in the
+<<query-dsl-bool-query,`bool`>> query, the `filter` parameter in the
+<<query-dsl-constant-score-query,`constant_score`>> query, or the
+<<search-aggregations-bucket-filter-aggregation,`filter`>> aggregation.
+--
+
+Below is an example of query clauses being used in query and filter context
+in the `search` API.  This query will match documents where all of the following
+conditions are met:
+
+* The `title` field contains the word `search`.
+* The `content` field contains the word `elasticsearch`.
+* The `status` field contains the exact word `published`.
+* The `publish_date` field contains a date from 1 Jan 2015 onwards.
+
+[source,json]
+------------------------------------
+GET _search
+{
+  "query": { <1>
+    "bool": { <2>
+      "must": [
+        { "match": { "title":   "Search"        }}, <2>
+        { "match": { "content": "Elasticsearch" }}  <2>
+      ],
+      "filter": [ <3>
+        { "term":  { "status": "published" }}, <4>
+        { "range": { "publish_date": { "gte": "2015-01-01" }}} <4>
+      ]
+    }
+  }
+}
+------------------------------------
+<1> The `query` parameter indicates query context.
+<2> The `bool` and two `match` clauses are used in query context,
+    which means that they are used to score how well each document
+    matches.
+<3> The `filter` parameter indicates filter context.
+<4> The `term` and `range` clauses are used in filter context.
+    They will filter out documents which do not match, but they will
+    not affect the score for matching documents.
+
+TIP: Use query clauses in query context for conditions which should affect the
+score of matching documents (i.e. how well does the document match), and use
+all other query clauses in filter context.

docs/reference/query-dsl/range-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-range-query]]
-== Range Query
+=== Range Query
 
 Matches documents with fields that have terms within a certain range.
 The type of the Lucene query depends on the field type, for `string`
@@ -30,7 +30,7 @@ The `range` query accepts the following parameters:
 `boost`:: 	Sets the boost value of the query, defaults to `1.0`
 
 [float]
-=== Date options
+==== Date options
 
 When applied on `date` fields the `range` filter accepts also a `time_zone` parameter.
 The `time_zone` parameter will be applied to your input lower and upper bounds and will

docs/reference/query-dsl/regexp-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-regexp-query]]
-== Regexp Query
+=== Regexp Query
 
 The `regexp` query allows you to use regular expression term queries.
 See <<regexp-syntax>> for details of the supported regular expression language.

docs/reference/query-dsl/regexp-syntax.asciidoc

@@ -1,17 +1,17 @@
 [[regexp-syntax]]
-=== Regular expression syntax
+==== Regular expression syntax
 
 Regular expression queries are supported by the `regexp` and the `query_string`
 queries.  The Lucene regular expression engine
 is not Perl-compatible but supports a smaller range of operators.
 
 [NOTE]
-====
+=====
 We will not attempt to explain regular expressions, but
 just explain the supported operators.
-====
+=====
 
-==== Standard operators
+===== Standard operators
 
 Anchoring::
 +
@@ -200,7 +200,7 @@ For string `"abcd"`:
 
 --
 
-===== Optional operators
+====== Optional operators
 
 These operators are available by default as the `flags` parameter defaults to `ALL`.
 Different flag combinations (concatened with `"\"`) can be used to enable/disable

docs/reference/query-dsl/script-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-script-query]]
-== Script Query
+=== Script Query
 
 A query allowing to define
 <<modules-scripting,scripts>> as filters. For
@@ -20,7 +20,7 @@ example:
 ----------------------------------------------
 
 [float]
-=== Custom Parameters
+==== Custom Parameters
 
 Scripts are compiled and cached for faster execution. If the same script
 can be used, just with different parameters provider, it is preferable

docs/reference/query-dsl/simple-query-string-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-simple-query-string-query]]
-== Simple Query String Query
+=== Simple Query String Query
 
 A query that uses the SimpleQueryParser to parse its context. Unlike the
 regular `query_string` query, the `simple_query_string` query will never
@@ -57,7 +57,7 @@ Defaults to `ROOT`.
 |=======================================================================
 
 [float]
-==== Simple Query String Syntax
+===== Simple Query String Syntax
 The `simple_query_string` supports the following special characters:
 
 * `+` signifies AND operation
@@ -73,7 +73,7 @@ In order to search for any of these special characters, they will need to
 be escaped with `\`.
 
 [float]
-=== Default Field
+==== Default Field
 When not explicitly specifying the field to search on in the query
 string syntax, the `index.query.default_field` will be used to derive
 which field to search on. It defaults to `_all` field.
@@ -82,7 +82,7 @@ So, if `_all` field is disabled, it might make sense to change it to set
 a different default field.
 
 [float]
-=== Multi Field
+==== Multi Field
 The fields parameter can also include pattern based field names,
 allowing to automatically expand to the relevant fields (dynamically
 introduced fields included). For example:
@@ -98,7 +98,7 @@ introduced fields included). For example:
 --------------------------------------------------
 
 [float]
-=== Flags
+==== Flags
 `simple_query_string` support multiple flags to specify which parsing features
 should be enabled. It is specified as a `|`-delimited string with the
 `flags` parameter:

docs/reference/query-dsl/span-containing-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-span-containing-query]]
-== Span Containing Query
+=== Span Containing Query
 
 Returns matches which enclose another span query. The span containing
 query maps to Lucene `SpanContainingQuery`. Here is an example:

docs/reference/query-dsl/span-first-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-span-first-query]]
-== Span First Query
+=== Span First Query
 
 Matches spans near the beginning of a field. The span first query maps
 to Lucene `SpanFirstQuery`. Here is an example:

docs/reference/query-dsl/span-multi-term-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-span-multi-term-query]]
-== Span Multi Term Query
+=== Span Multi Term Query
 
 The `span_multi` query allows you to wrap a `multi term query` (one of wildcard,
 fuzzy, prefix, term, range or regexp query) as a `span query`, so

docs/reference/query-dsl/span-near-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-span-near-query]]
-== Span Near Query
+=== Span Near Query
 
 Matches spans which are near one another. One can specify _slop_, the
 maximum number of intervening unmatched positions, as well as whether

docs/reference/query-dsl/span-not-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-span-not-query]]
-== Span Not Query
+=== Span Not Query
 
 Removes matches which overlap with another span query. The span not
 query maps to Lucene `SpanNotQuery`. Here is an example:

docs/reference/query-dsl/span-or-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-span-or-query]]
-== Span Or Query
+=== Span Or Query
 
 Matches the union of its span clauses. The span or query maps to Lucene
 `SpanOrQuery`. Here is an example:

docs/reference/query-dsl/span-queries.asciidoc

@@ -0,0 +1,65 @@
+[[span-queries]]
+== Span queries
+
+Span queries are low-level positional queries which provide expert control
+over the order and proximity of the specified terms. These are typically used
+to implement very specific queries on legal documents or patents.
+
+Span queries cannot be mixed with non-span queries (with the exception of the `span_multi` query).
+
+The queries in this group are:
+
+<<query-dsl-span-term-query,`span_term` query>>::
+
+The equivalent of the <<query-dsl-term-query,`term` query>> but for use with
+other span queries.
+
+<<query-dsl-span-multi-term-query,`span_multi` query>>::
+
+Wraps a <<query-dsl-term-query,`term`>>, <<query-dsl-range-query,`range`>>,
+<<query-dsl-prefix-query,`prefix`>>, <<query-dsl-wildcard-query,`wildcard`>>,
+<<query-dsl-regexp-query,`regexp`>>, or <<query-dsl-fuzzy-query,`fuzzy`>> query.
+
+<<query-dsl-span-first-query,`span_first` query>>::
+
+Accepts another span query whose matches must appear within the first N
+positions of the field.
+
+<<query-dsl-span-near-query,`span_near` query>>::
+
+Accepts multiple span queries whose matches must be within the specified distance of each other, and possibly in the same order.
+
+<<query-dsl-span-or-query,`span_or` query>>::
+
+Combines multiple span queries -- returns documents which match any of the
+specified queries.
+
+<<query-dsl-span-not-query,`span_not` query>>::
+
+Wraps another span query, and excludes any documents which match that query.
+
+<<query-dsl-span-containing-query,`span_containing` query>>::
+
+Accepts a list of span queries, but only returns those spans which also match a second span query.
+
+<<query-dsl-span-within-query,`span_within` query>>::
+
+The result from a single span query is returned as long is its span falls
+within the spans returned by a list of other span queries.
+
+
+include::span-term-query.asciidoc[]
+
+include::span-multi-term-query.asciidoc[]
+
+include::span-first-query.asciidoc[]
+
+include::span-near-query.asciidoc[]
+
+include::span-or-query.asciidoc[]
+
+include::span-not-query.asciidoc[]
+
+include::span-containing-query.asciidoc[]
+
+include::span-within-query.asciidoc[]

docs/reference/query-dsl/span-term-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-span-term-query]]
-== Span Term Query
+=== Span Term Query
 
 Matches spans containing a term. The span term query maps to Lucene
 `SpanTermQuery`. Here is an example:

docs/reference/query-dsl/span-within-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-span-within-query]]
-== Span Within Query
+=== Span Within Query
 
 Returns matches which are enclosed inside another span query. The span within
 query maps to Lucene `SpanWithinQuery`. Here is an example:

docs/reference/query-dsl/special-queries.asciidoc

@@ -0,0 +1,29 @@
+[[specialized-queries]]
+
+== Specialized queries
+
+This group contains queries which do not fit into the other groups:
+
+<<query-dsl-mlt-query,`more_like_this` query>>::
+
+This query finds documents which are similar to the specified text, document,
+or collection of documents.
+
+<<query-dsl-template-query,`template` query>>::
+
+The `template` query accepts a Mustache template (either inline, indexed, or
+from a file), and a map of parameters,  and combines the two to generate the
+final query to execute.
+
+<<query-dsl-script-query,`script` query>>::
+
+This query allows a script to act as a filter.  Also see the
+<<query-dsl-function-score-query,`function_score` query>>.
+
+
+include::mlt-query.asciidoc[]
+
+include::template-query.asciidoc[]
+
+include::script-query.asciidoc[]
+

docs/reference/query-dsl/template-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-template-query]]
-== Template Query
+=== Template Query
 
 A query that accepts a query template and a map of key/value pairs to fill in
 template parameters. Templating is based on Mustache. For simple token substitution all you provide
@@ -56,7 +56,7 @@ GET /_search
 <1> New line characters (`\n`) should be escaped as `\\n` or removed,
     and quotes (`"`) should be escaped as `\\"`.
 
-=== Stored templates
+==== Stored templates
 
 You can register a template by storing it in the `config/scripts` directory, in a file using the `.mustache` extension.
 In order to execute the stored template, reference it by name in the `file`

docs/reference/query-dsl/term-level-queries.asciidoc

@@ -0,0 +1,93 @@
+[[term-level-queries]]
+== Term level queries
+
+While the <<full-text-queries,full text queries>> will analyze the query
+string before executing, the _term-level queries_ operate on the exact terms
+that are stored in the inverted index.
+
+These queries are usually used for structured data like numbers, dates, and
+enums, rather than full text fields.  Alternatively, they allow you to craft
+low-level queries, foregoing the analysis process.
+
+The queries in this group are:
+
+<<query-dsl-term-query,`term` query>>::
+
+    Find documents which contain the exact term specified in the field
+    specified.
+
+<<query-dsl-terms-query,`terms` query>>::
+
+    Find documents which contain any of the exact terms specified in the field
+    specified.
+
+<<query-dsl-range-query,`range` query>>::
+
+    Find documents where the field specified contains values (dates, numbers,
+    or strings) in the range specified.
+
+<<query-dsl-exists-query,`exists` query>>::
+
+    Find documents where the field specified contains any non-null value.
+
+<<query-dsl-missing-query,`missing` query>>::
+
+    Find documents where the field specified does is missing or contains only
+    `null` values.
+
+<<query-dsl-prefix-query,`prefix` query>>::
+
+    Find documents where the field specified contains terms which being with
+    the exact prefix specified.
+
+<<query-dsl-wildcard-query,`wildcard` query>>::
+
+    Find documents where the field specified contains terms which match the
+    pattern specified, where the pattern supports single character wildcards
+    (`?`) and multi-character wildcards (`*`)
+
+<<query-dsl-regexp-query,`regexp` query>>::
+
+    Find documents where the field specified contains terms which match the
+    <<regexp-syntax,regular expression>> specified.
+
+<<query-dsl-fuzzy-query,`fuzzy` query>>::
+
+    Find documents where the field specified contains terms which are fuzzily
+    similar to the specified term.  Fuzziness is measured as a
+    http://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance[Levenshtein edit distance]
+    of 1 or 2.
+
+<<query-dsl-type-query,`type` query>>::
+
+    Find documents of the specified type.
+
+<<query-dsl-ids-query,`ids` query>>::
+
+    Find documents with the specified type and IDs.
+
+
+include::term-query.asciidoc[]
+
+include::terms-query.asciidoc[]
+
+include::range-query.asciidoc[]
+
+include::exists-query.asciidoc[]
+
+include::missing-query.asciidoc[]
+
+include::prefix-query.asciidoc[]
+
+include::wildcard-query.asciidoc[]
+
+include::regexp-query.asciidoc[]
+
+include::fuzzy-query.asciidoc[]
+
+include::type-query.asciidoc[]
+
+include::ids-query.asciidoc[]
+
+
+

docs/reference/query-dsl/term-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-term-query]]
-== Term Query
+=== Term Query
 
 The `term` query finds documents that contain the *exact* term specified
 in the inverted index.  For instance:

docs/reference/query-dsl/terms-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-terms-query]]
-== Terms Query
+=== Terms Query
 
 Filters documents that have fields that match any of the provided terms
 (*not analyzed*). For example:
@@ -19,7 +19,8 @@ The `terms` query is also aliased with `in` as the filter name for
 simpler usage.
 
 [float]
-==== Terms lookup mechanism
+[[query-dsl-terms-lookup]]
+===== Terms lookup mechanism
 
 When it's needed to specify a `terms` filter with a lot of terms it can
 be beneficial to fetch those term values from a document in an index. A
@@ -31,21 +32,21 @@ lookup mechanism.
 The terms lookup mechanism supports the following options:
 
 [horizontal]
-`index`:: 
+`index`::
     The index to fetch the term values from. Defaults to the
     current index.
 
-`type`:: 
+`type`::
     The type to fetch the term values from.
 
-`id`:: 
+`id`::
     The id of the document to fetch the term values from.
 
-`path`:: 
+`path`::
     The field specified as path to fetch the actual values for the
     `terms` filter.
 
-`routing`:: 
+`routing`::
     A custom routing value to be used when retrieving the
     external terms doc.
 
@@ -61,7 +62,7 @@ terms filter will prefer to execute the get request on a local node if
 possible, reducing the need for networking.
 
 [float]
-==== Terms lookup twitter example
+===== Terms lookup twitter example
 
 [source,js]
 --------------------------------------------------

docs/reference/query-dsl/type-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-type-query]]
-== Type Query
+=== Type Query
 
 Filters documents matching the provided document / mapping type.
 

docs/reference/query-dsl/wildcard-query.asciidoc

@@ -1,5 +1,5 @@
 [[query-dsl-wildcard-query]]
-== Wildcard Query
+=== Wildcard Query
 
 Matches documents that have fields matching a wildcard expression (*not
 analyzed*). Supported wildcards are `*`, which matches any character