anchor.diff:  experimental[The update-by-query API is new and should still be considered experimental.  The API may change in ways that are not backwards compatible]
   
   The simplest usage of `updateByQuery` updates each
  -document in an index without changing the source. This usage enables 
  +document in an index without changing the source. This usage enables
   <<picking-up-a-new-property,picking up a new property>> or another online
   mapping change.
   
  
positive.code: The value of `requests_per_second` can be changed on a running update by query
  using the `_rethrottle` API:
  
  // provide API Example
  [source,java]
  --------------------------------------------------
  
  --------------------------------------------------
  // CONSOLE
  
  The `task_id` can be found using the tasks API above.
  
  Just like when setting it on the `updateByQuery` API `requests_per_second`
  can be either `unlimited` to disable throttling or any decimal number like `1.7`
  or `12` to throttle to that level. Rethrottling that speeds up the query takes
  effect immediately but rethrotting that slows down the query will take effect
  on after completing the current batch. This prevents scroll timeouts.
  
  
  [float]
  [[picking-up-a-new-property]]
  === Pick up a new property
  
  Say you created an index without dynamic mapping, filled it with data, and then
  added a mapping value to pick up more fields from the data:
  
  [source,java]
  --------------------------------------------------
  PUT test
  {
    "mappings": {
      "test": {
        "dynamic": false,   <1>
        "properties": {
          "text": {"type": "text"}
        }
      }
    }
  }
  
  POST test/test?refresh
  {
    "text": "words words",
    "flag": "bar"
  }
  POST test/test?refresh
  {
    "text": "words words",
    "flag": "foo"
  }
  PUT test/_mapping/test   <2>
  {
    "properties": {
      "text": {"type": "text"},
      "flag": {"type": "text", "analyzer": "keyword"}
    }
  }
  --------------------------------------------------
  // CONSOLE
  
  <1> This means that new fields won't be indexed, just stored in `_source`.
  
  <2> This updates the mapping to add the new `flag` field. To pick up the new
  field you have to reindex all documents with it.
  
  Searching for the data won't find anything:
  
  // provide API Example
  [source,java]
  --------------------------------------------------
  
  {
    "query": {
      "match": {
        "flag": "foo"
      }
    }
  }
  --------------------------------------------------
  // CONSOLE
  // TEST[continued]
  
  [source,java]
  --------------------------------------------------
  {
    "hits" : {
      "total" : 0
    }
  }
  --------------------------------------------------
  // TESTRESPONSE
  
  But you can issue an `updateByQuery` request to pick up the new mapping:
  
  // provide API Example
  [source,java]
  --------------------------------------------------
  
  {
    "query": {
      "match": {
        "flag": "foo"
      }
    }
  }
  --------------------------------------------------
  // CONSOLE
  // TEST[continued]
  
  [source,java]
  --------------------------------------------------
  {
    "hits" : {
      "total" : 1
    }
  }
  --------------------------------------------------
  // TESTRESPONSE
  
  You can do the exact same thing when adding a field to a multifield.
  
negative.code: --------------------------------------------------
  UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
  
  updateByQuery.source("source_index").abortOnVersionConflict(false);
  
  BulkIndexByScrollResponse response = updateByQuery.get();
  --------------------------------------------------
  
  Calls to the `updateByQuery` API start by getting a snapshot of the index, indexing
  any documents found using the `internal` versioning.
  
  NOTE: Version conflicts happen when a document changes between the time of the
  snapshot and the time the index request processes.
  
  When the versions match, `updateByQuery` updates the document
  and increments the version number.
  
  All update and query failures cause `updateByQuery` to abort. These failures are
  available from the `BulkIndexByScrollResponse#getIndexingFailures` method. Any
  successful updates remain and are not rolled back. While the first failure
  causes the abort, the response contains all of the failures generated by the
  failed bulk request.
  
  To prevent version conflicts from causing `updateByQuery` to abort, set
  `abortOnVersionConflict(false)`. The first example does this because it is
  trying to pick up an online mapping change and a version conflict means that
  the conflicting document was updated between the start of the `updateByQuery`
  and the time when it attempted to update the document. This is fine because
  that update will have picked up the online mapping update.
  
  Back to the API, `UpdateByQueryRequestBuilder` supports filtering the documents
  that are updated, limiting the total number updated, and updating documents
  with a script:
  
  [source,java]
  --------------------------------------------------
  UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
  
  updateByQuery.source("source_index")
          .filter(termQuery("level", "awesome"))
          .size(1000)
          .script(new Script("ctx._source.awesome = 'absolutely'", ScriptType.INLINE, "painless", emptyMap()));
  
  BulkIndexByScrollResponse response = updateByQuery.get();
  --------------------------------------------------
  
  `UpdateByQueryRequestBuilder` also allows you direct access to the query used
  to select the documents which you can use to change the default scroll size or
  otherwise modify the request for matching documents.
  
  [source,java]
  --------------------------------------------------
  UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
  
  updateByQuery.source("source_index")
          .source().setSize(500);
  
  BulkIndexByScrollResponse response = updateByQuery.get();
  --------------------------------------------------
  
  You can also combine `size` with sorting to limit the documents updated:
  
  [source,java]
  --------------------------------------------------
  UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
  
  updateByQuery.source("source_index").size(100)
          .source().addSort("cat", SortOrder.DESC);
  
  BulkIndexByScrollResponse response = updateByQuery.get();
  --------------------------------------------------
  
  In addition to changing the `_source` of the document (see above) the script
  can change the update action similarly to the Update API:
  
  [source,java]
  --------------------------------------------------
  UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
  
  updateByQuery.source("source_index")
          .script(new Script(
              "if (ctx._source.awesome == 'absolutely) {"
            + "  ctx.op='noop'
            + "} else if (ctx._source.awesome == 'lame') {"
            + "  ctx.op='delete'"
            + "} else {"
            + "ctx._source.awesome = 'absolutely'}", ScriptType.INLINE, "painless", emptyMap()));
  
  BulkIndexByScrollResponse response = updateByQuery.get();
  --------------------------------------------------
  
  Just as in <<docs-update,Update API>> you can set `ctx.op` to change the
  operation that is executed:
  