change taskId to nodeId:taskId to be more accurate in DeleteByQuery Documentation

[diaojinggang]

Most APIs locate a task by nodeId:taskId.

It is very confusing as examples like the following are not working because the taskId here actually means nodeId:taskId

GET /_tasks/taskId

Another change gives developers a better understanding of wait_for_completion parameter and how to delete a task document after completion.

[elasticmachine]

Pinging @elastic/es-distributed

[nik9000]

The task id is made up of a node id and a number so I'm fairly sure the docs are right as they stand.

[diaojinggang]

@nik9000 @elastic/es-distributed Thanks for the clarification. I didn't see "The task id is made up of a node id and a number" this definition anywhere before I struggled and understood it myself.

I will give you a confusing example:

GET http://localhost:9200/_tasks?detailed=false&actions=*/delete/byquery

//response
{
    "nodes": {
        "NCvmGYS-RsW2X8JxEYumgA": {
            "name": "NCvmGYS",
            "transport_address": "127.0.0.1:9300",
            "host": "127.0.0.1",
            "ip": "127.0.0.1:9300",
            "roles": [
                "master",
                "data",
                "ingest"
            ],
            "tasks": {
                "NCvmGYS-RsW2X8JxEYumgA:1204320": {
                    "node": "NCvmGYS-RsW2X8JxEYumgA",
                    "id": 1204320,
                    "type": "transport",
                    "action": "indices:data/write/delete/byquery",
                    "start_time_in_millis": 1528310404882,
                    "running_time_in_nanos": 24218556132,
                    "cancellable": true
                }
            }
        }
    }
}

I think people would assume taskId is 1204320 instead of NCvmGYS-RsW2X8JxEYumgA:1204320 when they see this response.

Another example:

GET http://localhost:9200/_tasks/NCvmGYS-RsW2X8JxEYumgA:1204320

//returns
{
    "completed": false,
    "task": {
        "node": "NCvmGYS-RsW2X8JxEYumgA",
        "id": 1204320,
        "type": "transport",
        "action": "indices:data/write/delete/byquery",
        "status": {
            "total": 398000,
            "updated": 0,
            "created": 0,
            "deleted": 1000,
            "batches": 1,
            "version_conflicts": 0,
            "noops": 0,
            "retries": {
                "bulk": 0,
                "search": 0
            },
            "throttled_millis": 0,
            "requests_per_second": 1,
            "throttled_until_millis": 959645
        },
        "description": "delete-by-query [twitter]",
        "start_time_in_millis": 1528310404882,
        "running_time_in_nanos": 40476365565,
        "cancellable": true
    }
}

Still some people woud think taskId is 1204320 because the key for 1204320 is called "id".

If you think my argument is not strong enough, please close this pr on my behalf. Thanks.

[nik9000]

@imotov, what do you think of node and id from the tasks list so this is less confusing?

[imotov]

@nik9000 In my opinion task id is the whole thing - NCvmGYS-RsW2X8JxEYumgA:1204320, which currently happened to be a string that consists of node_id and task_sequence_number (for the lack of a better name) on the node separated by :. However, I think users shouldn't rely on this fact since it might change in the future and we shouldn't reflect this fact in the documentation.

[nik9000]

I've opened the issue #31253 to track removing the bits of the list tasks API that imply some contract about the shape of task ids. I'd like to do that instead of this so I'm closing this PR.