anchor.diff:  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.
  +[source,java]
  +--------------------------------------------------
  +RethrottleAction.INSTANCE.newRequestBuilder(client).setTaskId(taskId).setRequestsPerSecond(2.0f).get();
  +--------------------------------------------------
  +
  +The `taskId` 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
  +can be either `Float.POSITIVE_INFINITY` to disable throttling or any positive
  +float 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.
  
positive.code: --------------------------------------------------
  UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
  
  updateByQuery.source("cool_things")
          .filter(termQuery("level", "awesome"))
          .script(new Script("ctx._source.awesome = \"absolutely\""));
  
  BulkIndexByScrollResponse response = updateByQuery.get();
  --------------------------------------------------
  
  The `updatebyQuery` API returns a JSON object similar to the following example:
  
  [source,java]
  --------------------------------------------------
  {
    "took" : 147,
    "timed_out": false,
    "updated": 120,
    "deleted": 0,
    "batches": 1,
    "version_conflicts": 0,
    "noops": 0,
    "retries": {
      "bulk": 0,
      "search": 0
    },
    "throttled_millis": 0,
    "requests_per_second": "unlimited",
    "throttled_until_millis": 0,
    "total": 120,
    "failures" : [ ]
  }
  --------------------------------------------------
  // TESTRESPONSE[s/"took" : 147/"took" : "$body.took"/]
  
  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
  listed in the `failures` section of the JSON response object. Any successful updates 
  remain and are not rolled back. While the first failure causes the abort, the JSON
  response object contains all of the failures generated by the failed bulk request.
  
  To prevent version conflicts from causing `updateByQuery` to abort, 
  set `conflicts=proceed` on the URL or `"conflicts": "proceed"`
  in the request body. 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 format, you can limit `updateByQuery` to a single type. This
  will only update `tweet` documents from the `twitter` index:
  
  // provide API Example
  
  [source,java]
  --------------------------------------------------
  
  --------------------------------------------------
  // CONSOLE
  // TEST[setup:twitter]
  
  You can also limit `updateByQuery` using the
  <<query-dsl,Query DSL>>. This example updates all documents from the
  `twitter` index for the user `kimchy`:
  
  
  // provide API Example
  
  [source,java]
  --------------------------------------------------
  
  {
    "query": { <1>
      "term": {
        "user": "kimchy"
      }
    }
  }
  --------------------------------------------------
  // CONSOLE
  // TEST[setup:twitter]
  
  <1> The query must be passed as a value to the `query` key, in the same
  way as the <<search-search,Search API>>. You can also use the `q`
  parameter in the same way as the search api.
  
  So far we've only been updating documents without changing their source. That
  is genuinely useful for things like
  <<picking-up-a-new-property,picking up new properties>> but it's only half the
  fun. `updateByQuery` supports a `script` object to update the document. This
  will increment the `likes` field on all of kimchy's tweets:
  
  // provide API Example
  
  [source,java]
  --------------------------------------------------
  
  {
    "script": {
      "inline": "ctx._source.likes++"
    },
    "query": {
      "term": {
        "user": "kimchy"
      }
    }
  }
  --------------------------------------------------
  // CONSOLE
  // TEST[setup:twitter]
  
  Just as in <<docs-update,Update API>> you can set `ctx.op` to change the
  operation that is executed:
  
negative.code: 
  Any Update By Query can be canceled using the <<tasks,Task Cancel API>>:
  
  [source,java]
  --------------------------------------------------
  // Cancel all update-by-query requests
  client.admin().cluster().prepareCancelTasks().setActions(UpdateByQueryAction.NAME).get().getTasks()
  // Cancel a specific update-by-query request
  client.admin().cluster().prepareCancelTasks().setTaskId(taskId).get().getTasks()
  --------------------------------------------------
  
  The `taskId` can be found using the list tasks API above.
  
  Cancelation should happen quickly but might take a few seconds. The task status
  API above will continue to list the task until it is wakes to cancel itself.
  