Merge pull request #2351 from crate/m/doc-job-context

update job context documentation

docs/sql/kill.txt

@@ -6,35 +6,34 @@ Kill Jobs
 =========
 
 Each executed sql statement results in a corresponding job.
-Jobs that are currently executing are logged in the system table ``sys.jobs``
+Jobs that are currently executed are listed in the ``sys.jobs`` system table
 (see :ref:`jobs_operations_logs`).
 
-To obtain the `UUID`_ of a job, stats needs to be enabled (see
-:ref:`conf_collecting_stats`). Job logging can be disabled by
+To obtain the `UUID`_ of a job you need to enable stats
+(see :ref:`conf_collecting_stats`). The job logging can be prevented by
 setting the queue size to zero.
 
 Killing an active job forces Crate to stop its execution on the cluster
 immediately. There are two different SQL commands available for killing jobs.
 
-The ``KILL ALL`` statement stops every single job on each node that is running.
-It returns the total number of contexts of all jobs that have been killed.
-A job can have contexts on multiple nodes.
+The ``KILL ALL`` statement stops on each node every single job that is currently
+running. It returns the total number of contexts of all jobs of that have been
+killed (see :ref:`sql_kill`).
 
 ::
 
     cr> kill all;
     KILL OK, ... rows affected (... sec)
 
-``KILL job_id`` kills one single job with the specified ``job_id``. Like
-``KILL ALL`` it returns the total number of contexts of that job killed on all
-nodes. Like ``KILL ALL`` it returns the number of jobs that have been
-killed per node.
+Like ``KILL ALL`` the ``KILL job_id`` statement only kills one single job with
+the specified ``job_id``. As same as ``KILL ALL`` it returns the number of
+distinct jobs that have been killed on each node in the cluster.
 
 ::
 
     cr> kill '175011ce-9bbc-45f2-a86a-5b7f993a93a6';
     KILL OK, ... rows affected (... sec)
 
-See :ref:`sql_kill` for detailed syntax information on ``KILL`` statements.
+See :ref:`sql_kill` for detailed syntax information on the ``KILL`` statements.
 
 .. _`UUID`: http://en.wikipedia.org/wiki/Universally_unique_identifier

docs/sql/reference/kill.txt

@@ -20,31 +20,32 @@ Synopsis
 Description
 ===========
 
-The ``KILL ALL`` statement kills all active jobs within the crate cluster.
-The statement ``KILL job_id`` kills the job with a specified ``job_id``.
+A job context contains the job that is provided to the current running tasks.
+Therefore a job can have contexts on multiple nodes. The ``KILL ALL`` statement
+will kill all active job contexts within the Crate cluster. The statement
+``KILL job_id`` kills a specific job with its specified ``job_id``.
 
 Be aware that Crate doesn't have transactions. If an operation which modifies
-data is killed, it won't rollback. For example if a update operation is killed
+data is killed it won't rollback. For example if a update operation is killed
 it is likely that it updated some documents before being killed. This might
 leave the data in an inconsistent state. So take care when using ``KILL``.
 
+In addition to that certain fast running operations have a small time frame in
+which they can be killed. For example if you delete a single document by id it
+could be that the document is deleted before the ``KILL`` command is being
+processed, but the client might still get an error that the operation has been
+killed because the ``KILL`` command is processed before the final result is
+sent to the client.
 
-Certain fast running operations have a small time frame in which they can be
-killed. For example if you delete a single document by id, the document
-could be deleted before the ``KILL`` command is processed, but the client might
-receive an error that the operation has been killed because the ``KILL`` command
-processed before the final result is sent to the client.
-
-``KILL ALL`` and ``KILL job_id`` return the number of contexts killed per node.
-For example if the only active query was ``select * from t`` and that query is
-being executed on 3 nodes, then ``KILL ALL`` will return 3.
+``KILL ALL`` and ``KILL job_id`` return the number of distinct job contexts
+that have been killed per node. For example if the only active query was
+``select * from t`` and that query is being executed on 3 nodes then
+``KILL ALL`` will return 3.
 
 Parameters
 ==========
 
-:job_id: The `UUID`_ of the currently active job that needs to be killed given
-as
+:job_id: The `UUID`_ of the currently active job that needs to be killed given as
     a string literal.
 
-
 .. _`UUID`: http://en.wikipedia.org/wiki/Universally_unique_identifier