anchor.diff:  You can fetch the status of all running update-by-query requests with the
   <<tasks,Task API>>:
   
  +[source,java]
  +--------------------------------------------------
  +ListTasksResponse tasksList = client.admin().cluster().prepareListTasks()
  +        .setActions(UpdateByQueryAction.NAME).setDetailed(true).get();
  +
  +for (TaskInfo info: tasksList.getTasks()) {
  +    TaskId taskId = info.getTaskId();
  +    BulkByScrollTask.Status status = (BulkByScrollTask.Status) info.getStatus();
  +    // do stuff
  +}
  +
  +--------------------------------------------------
  +
  +With the `TaskId` shown above you can look up the task directly:
  +
   // provide API Example
  -
  -[source,java]
  ---------------------------------------------------
  -
  ---------------------------------------------------
  -// CONSOLE
  -
  -The responses looks like:
  -
  -[source,java]
  ---------------------------------------------------
  -{
  -  "nodes" : {
  -    "r1A2WoRbTwKZ516z6NEs5A" : {
  -      "name" : "Tyrannus",
  -      "transport_address" : "127.0.0.1:9300",
  -      "host" : "127.0.0.1",
  -      "ip" : "127.0.0.1:9300",
  -      "attributes" : {
  -        "testattr" : "test",
  -        "portsfile" : "true"
  -      },
  -      "tasks" : {
  -        "r1A2WoRbTwKZ516z6NEs5A:36619" : {
  -          "node" : "r1A2WoRbTwKZ516z6NEs5A",
  -          "id" : 36619,
  -          "type" : "transport",
  -          "action" : "indices:data/write/update/byquery",
  -          "status" : {    <1>
  -            "total" : 6154,
  -            "updated" : 3500,
  -            "created" : 0,
  -            "deleted" : 0,
  -            "batches" : 4,
  -            "version_conflicts" : 0,
  -            "noops" : 0,
  -            "retries": {
  -              "bulk": 0,
  -              "search": 0
  -            }
  -            "throttled_millis": 0
  -          },
  -          "description" : ""
  -        }
  -      }
  -    }
  -  }
  -}
  ---------------------------------------------------
  -
  -<1> this object contains the actual status. It is just like the response json
  -with the important addition of the `total` field. `total` is the total number
  -of operations that the reindex expects to perform. You can estimate the
  -progress by adding the `updated`, `created`, and `deleted` fields. The request
  -will finish when their sum is equal to the `total` field.
  -
  -With the task id you can look up the task directly:
  -
  -// provide API Example
  -[source,java]
  ---------------------------------------------------
  -
  ---------------------------------------------------
  -// CONSOLE
  -// TEST[catch:missing]
  -
  -The advantage of this API is that it integrates with `wait_for_completion=false`
  -to transparently return the status of completed tasks. If the task is completed
  -and `wait_for_completion=false` was set on it them it'll come back with a
  -`results` or an `error` field. The cost of this feature is the document that
  -`wait_for_completion=false` creates at `.tasks/task/${taskId}`. It is up to
  -you to delete that document.
  +[source,java]
  +--------------------------------------------------
  +GetTaskResponse get = client.admin().cluster().prepareGetTask(taskId).get();
  +--------------------------------------------------
   
   [float]
   [[docs-update-by-query-cancel-task-api]]
  
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: 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
  <<picking-up-a-new-property,picking up a new property>> or another online
  mapping change.
  
  