merge upstream, fix build error

Author: medcl

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,8 @@
+<!--
 Thanks for the Pull Request!  We really appreciate your help and contribution!
 
 Before you submit the PR, have you signed Contributor License Agreement: https://www.elastic.co/contributor-agreement/ ?
 
 PR's (no matter how small) cannot be merged until the CLA has been signed.  
 It only needs to be signed once, however. Thanks!
+-->

010_Intro/15_API.asciidoc

@@ -1,6 +1,6 @@
 === Talking to Elasticsearch
 
-How you talk to Elasticsearch depends on((("Elasticsearch", "talking to"))) whether you are using Java.
+How you talk to Elasticsearch depends on((("Elasticsearch", "talking to"))) whether you are using Java or not.
 
 ==== Java API
 

010_Intro/25_Tutorial_Indexing.asciidoc

@@ -16,7 +16,7 @@ So, sit back and enjoy a whirlwind tour of what Elasticsearch is capable of.
 We happen((("employee directory, building (example)"))) to work for _Megacorp_, and as part of HR's new _"We love our
 drones!"_ initiative, we have been tasked with creating an employee directory.
 The directory is supposed to foster employer empathy and
-real-time, synergistic, dynamic collaboration, so it has a few 
+real-time, synergistic, dynamic collaboration, so it has a few
 business requirements:
 
 * Enable data to contain multi value tags, numbers, and full text.
@@ -34,17 +34,10 @@ of an _employee document_: a single document represents a single
 employee.  The act of storing data in Elasticsearch is called _indexing_, but
 before we can index a document, we need to decide _where_ to store it.
 
-In Elasticsearch, a document belongs to a _type_, and those((("types"))) types live inside
-an _index_. ((("indices")))You can draw some (rough) parallels to a traditional relational database:
 
-----
-Relational DB  ⇒ Databases ⇒ Tables ⇒ Rows      ⇒ Columns
-Elasticsearch  ⇒ Indices   ⇒ Types  ⇒ Documents ⇒ Fields
-----
-
-An Elasticsearch cluster can((("clusters", "indices (databases) in")))((("databases", "in clusters"))) contain multiple _indices_ (databases), which in
-turn contain multiple _types_ (tables).((("tables"))) These types hold multiple _documents_
-(rows), and ((("rows")))each document has((("fields")))((("columns"))) multiple _fields_ (columns).
+An Elasticsearch cluster can((("clusters", "indices in")))(((in clusters"))) contain multiple _indices_, which in
+turn contain multiple _types_.((("tables"))) These types hold multiple _documents_,
+and each document has((("fields"))) multiple _fields_.
 
 .Index Versus Index Versus Index
 **************************************************
@@ -108,11 +101,11 @@ information:
 
 +megacorp+::
       The index name
-      
+
 +employee+::
       The type name
-      
-+1+::          
+
++1+::
       The ID of this particular employee
 
 The request body--the JSON document--contains all the information about
@@ -147,6 +140,3 @@ PUT /megacorp/employee/3
 }
 --------------------------------------------------
 // SENSE: 010_Intro/25_Index.json
-
-
-

010_Intro/30_Tutorial_Search.asciidoc

@@ -209,15 +209,15 @@ which allows us to execute structured searches efficiently:
 GET /megacorp/employee/_search
 {
     "query" : {
-        "filtered" : {
-            "filter" : {
-                "range" : {
-                    "age" : { "gt" : 30 } <1>
+        "bool": {
+            "must": {
+                "match" : {
+                    "last_name" : "smith" <1>
                 }
             },
-            "query" : {
-                "match" : {
-                    "last_name" : "smith" <2>
+            "filter": {
+                "range" : {
+                    "age" : { "gt" : 30 } <2>
                 }
             }
         }
@@ -226,13 +226,15 @@ GET /megacorp/employee/_search
 --------------------------------------------------
 // SENSE: 010_Intro/30_Query_DSL.json
 
-<1> This portion of the query is a `range` _filter_, which((("range filters"))) will find all ages
+<1> This portion of the query is the((("match queries"))) same `match` _query_ that we used before.
+<2> This portion of the query is a `range` _filter_, which((("range filters"))) will find all ages
     older than 30&#x2014;`gt` stands for _greater than_.
-<2> This portion of the query is the((("match queries"))) same `match` _query_ that we used before.
+
 
 Don't worry about the syntax too much for now; we will cover it in great
 detail later.  Just recognize that we've added a _filter_ that performs a
-range search, and reused the same `match` query as before.  Now our results show only one employee who happens to be 32 and is named Jane Smith:
+range search, and reused the same `match` query as before.  Now our results show
+only one employee who happens to be 32 and is named Jane Smith:
 
 [source,js]
 --------------------------------------------------
@@ -446,4 +448,3 @@ HTML tags:
 
 You can read more about the highlighting of search snippets in the
 {ref}/search-request-highlighting.html[highlighting reference documentation].
-

030_Data/05_Document.asciidoc

@@ -39,26 +39,30 @@ other objects. In Elasticsearch, the term _document_ has a specific meaning. It
 to the top-level, or root object that((("root object"))) is serialized into JSON and
 stored in Elasticsearch under a unique ID.
 
+WARNING: Field names can be any valid string, but _may not_ include periods.
+
 === Document Metadata
 
 A document doesn't consist only of its data.((("documents", "metadata"))) It also has
 _metadata_—information _about_ the document.((("metadata, document"))) The three required metadata
 elements are as follows:
 
 
- `_index`::  
+ `_index`::
    Where the document lives
-   
- `_type`::   
+
+ `_type`::
    The class of object that the document represents
-   
- `_id`::     
+
+ `_id`::
    The unique identifier for the document
 
 ==== _index
 
-An _index_ is like a database in a relational database; it's the place
-we store and index related data.((("indices", "_index, in document metadata")))
+An _index_ is a collection of documents that should be grouped together for a
+common reason.  For example, you may store all your products in a `products` index,
+while all your sales transactions go in `sales`.  Although it is possible to store
+unrelated data together in a single index, it is often considered an anti-pattern.
 
 [TIP]
 ====
@@ -76,28 +80,23 @@ underscore, and cannot contain commas. Let's use `website` as our index name.
 
 ==== _type
 
-In applications, we use objects to represent _things_ such as a user, a blog
-post, a comment, or an email. Each object belongs to a _class_ that defines
-the properties or data associated with an object. Objects in the `user` class
-may have a name, a gender, an age, and an email address.
-
-In a relational database, we usually store objects of the same class in the
-same table, because they share the same data structure. For the same reason, in
-Elasticsearch we use the same _type_ for ((("types", "_type, in document metadata)))documents that represent the same
-class of _thing_, because they share the same data structure.
+Data may be grouped loosely together in an index, but often there are sub-partitions
+inside that data which may be useful to explicitly define.  For example, all your
+products may go inside a single index.  But you have different categories of products,
+such as "electronics", "kitchen" and "lawn-care".
 
-Every _type_ has its own <<mapping,mapping>> or schema ((("mapping (types)")))((("schema definition, types")))definition, which
-defines the data structure for documents of that type, much like the columns
-in a database table. Documents of all types can be stored in the same index,
-but the _mapping_ for the type tells Elasticsearch how the data in each
-document should be indexed.
+The documents all share an identical (or very similar) schema: they have a title,
+description, product code, price.  They just happen to belong to sub-categories
+under the umbrella of "Products".
 
-We show how to specify and manage mappings in <<mapping>>, but for now
-we will rely on Elasticsearch to detect our document's data structure
-automatically.
+Elasticsearch exposes a feature called _types_ which allows you to logically
+partition data inside of an index.  Documents in different types may have different
+fields, but it is best if they are highly similar.  We'll talk more about the restrictions
+and applications of types in <<mapping>>.
 
 A `_type` name can be lowercase or uppercase, but shouldn't begin with an
-underscore or contain commas.((("types", "names of")))  We will use `blog` for our type name.
+underscore or period.  It also may not contain commas,((("types", "names of")))
+and is limited to a length of 256 characters. We will use `blog` for our type name.
 
 ==== _id
 

030_Data/10_Index.asciidoc

@@ -52,7 +52,7 @@ Elasticsearch responds as follows:
 --------------------------------------------------
 
 
-The response indicates that the indexing request has been successfully created
+The response indicates that the document has been successfully created
 and includes the `_index`, `_type`, and `_id` metadata, and a new element:
 `_version`.((("version number (documents)")))
 
@@ -95,9 +95,6 @@ field has been generated for us:
 }
 --------------------------------------------------
 
-Autogenerated IDs are 20 character long, URL-safe, Base64-encoded string
-_universally unique identifiers_, or((("UUIDs (universally unique identifiers)"))) http://en.wikipedia.org/wiki/Uuid[UUIDs].
-
-
-
-
+Autogenerated IDs are 20 character long, URL-safe, Base64-encoded GUID strings.  These
+GUIDs are generated from a modified FlakeID scheme which allows multiple nodes
+to be generating unique IDs in parallel with essentially zero chance of collision.

030_Data/15_Get.asciidoc

@@ -51,7 +51,6 @@ display the response headers:
 --------------------------------------------------
 curl -i -XGET http://localhost:9200/website/blog/124?pretty
 --------------------------------------------------
-// SENSE: 030_Data/15_Get_document.json
 
 
 The response now looks like this:
@@ -94,7 +93,7 @@ filtered out the `date` field:
   "_type" :    "blog",
   "_id" :      "123",
   "_version" : 1,
-  "exists" :   true,
+  "found" :   true,
   "_source" : {
       "title": "My first blog entry" ,
       "text":  "Just trying this out..."

030_Data/30_Create.asciidoc

@@ -47,9 +47,21 @@ code, and an error message like the following:
 [source,js]
 --------------------------------------------------
 {
-  "error" : "DocumentAlreadyExistsException[[website][4] [blog][123]:
-             document already exists]",
-  "status" : 409
+   "error": {
+      "root_cause": [
+         {
+            "type": "document_already_exists_exception",
+            "reason": "[blog][123]: document already exists",
+            "shard": "0",
+            "index": "website"
+         }
+      ],
+      "type": "document_already_exists_exception",
+      "reason": "[blog][123]: document already exists",
+      "shard": "0",
+      "index": "website"
+   },
+   "status": 409
 }
 --------------------------------------------------
 // SENSE: 030_Data/30_Create_doc.json

030_Data/40_Version_control.asciidoc

@@ -154,9 +154,21 @@ code, and a body like the following:
 [source,js]
 --------------------------------------------------
 {
-  "error" : "VersionConflictEngineException[[website][2] [blog][1]:
-             version conflict, current [2], provided [1]]",
-  "status" : 409
+   "error": {
+      "root_cause": [
+         {
+            "type": "version_conflict_engine_exception",
+            "reason": "[blog][1]: version conflict, current [2], provided [1]",
+            "index": "website",
+            "shard": "3"
+         }
+      ],
+      "type": "version_conflict_engine_exception",
+      "reason": "[blog][1]: version conflict, current [2], provided [1]",
+      "index": "website",
+      "shard": "3"
+   },
+   "status": 409
 }
 --------------------------------------------------
 // SENSE: 030_Data/40_Concurrency.json

040_Distributed_CRUD/00_Intro.asciidoc

@@ -19,7 +19,7 @@ options that are discussed are for advanced users only.
 
 Read the section to gain a taste for how things work, and to know where the
 information is in case you need to refer to it in the future, but don't be
-overwhelmed by the detail.
+overwhelmed by the details.
 
 ****
 

040_Distributed_CRUD/30_Bulk_requests.asciidoc

@@ -47,6 +47,6 @@ The sequence of steps((("bulk API", "multiple document changes with")))((("docum
    the coordinating node, which collates the responses and returns them to the
    client.
 
-The `bulk` API also ((("consistency request parameter", "in bulk requests"))) the `consistency` parameter
+The `bulk` API also accepts ((("consistency request parameter", "in bulk requests"))) the `consistency` parameter
 at the top level for the whole `bulk` request, and the `routing` parameter
 in the metadata for each request.

052_Mapping_Analysis/40_Analysis.asciidoc

@@ -159,8 +159,11 @@ parameters,  and the text to analyze in the body:
 
 [source,js]
 --------------------------------------------------
-GET /_analyze?analyzer=standard
-Text to analyze
+GET /_analyze
+{
+  "analyzer": "standard",
+  "text": "Text to analyze"
+}
 --------------------------------------------------
 // SENSE: 052_Mapping_Analysis/40_Analyze.json
 

052_Mapping_Analysis/45_Mapping.asciidoc

@@ -144,10 +144,10 @@ can contain one of three values:
  `analyzed`::
    First analyze the string and then index it.  In other words, index this field as full text.
 
- `not_analyzed`::        
+ `not_analyzed`::
    Index this field, so it is searchable, but index the value exactly as specified. Do not analyze it.
 
- `no`::                  
+ `no`::
    Don't index this field at all. This field will not be searchable.
 
 The default value of `index` for a `string` field is `analyzed`.  If we
@@ -204,7 +204,7 @@ for an existing type) later, using the `/_mapping` endpoint.
 ================================================
 Although you can _add_ to an existing mapping, you can't _change_ existing
 field mappings.  If a mapping already exists for a field, data from that
-field has probably been indexed.  If you were to change the field mapping, 
+field has probably been indexed.  If you were to change the field mapping,
 the indexed data would be wrong and would not be properly searchable.
 ================================================
 
@@ -278,11 +278,17 @@ name. Compare the output of these two requests:
 
 [source,js]
 --------------------------------------------------
-GET /gb/_analyze?field=tweet
-Black-cats <1>
+GET /gb/_analyze
+{
+  "field": "tweet",
+  "text": "Black-cats" <1>
+}
 
-GET /gb/_analyze?field=tag
-Black-cats <1>
+GET /gb/_analyze
+{
+  "field": "tag",
+  "text": "Black-cats" <1>
+}
 --------------------------------------------------
 // SENSE: 052_Mapping_Analysis/45_Mapping.json
 <1> The text we want to analyze is passed in the body.

054_Query_DSL.asciidoc

@@ -6,7 +6,6 @@ include::054_Query_DSL/65_Queries_vs_filters.asciidoc[]
 
 include::054_Query_DSL/70_Important_clauses.asciidoc[]
 
-include::054_Query_DSL/75_Queries_with_filters.asciidoc[]
+include::054_Query_DSL/75_Combining_queries_together.asciidoc[]
 
 include::054_Query_DSL/80_Validating_queries.asciidoc[]
-

054_Query_DSL/60_Query_DSL.asciidoc

@@ -99,15 +99,17 @@ other to create complex queries. Clauses can be as follows:
 
 * _Compound_ clauses that are used ((("compound query clauses")))to combine other query clauses.
   For instance, a `bool` clause((("bool clause"))) allows you to combine other clauses that
-  either `must` match,  `must_not` match, or `should` match if possible:
+  either `must` match,  `must_not` match, or `should` match if possible.  They can also include non-scoring,
+  filters for structured search:
 
 [source,js]
 --------------------------------------------------
 {
     "bool": {
         "must":     { "match": { "tweet": "elasticsearch" }},
         "must_not": { "match": { "name":  "mary" }},
-        "should":   { "match": { "tweet": "full text" }}
+        "should":   { "match": { "tweet": "full text" }},
+        "filter":   { "range": { "age" : { "gt" : 30 }} }
     }
 }
 --------------------------------------------------