X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/3e7478a9a822686e1b5291fb0909a2ee2fcfeace..c806ef1:/doc/api/methods/jobs.html.textile.liquid diff --git a/doc/api/methods/jobs.html.textile.liquid b/doc/api/methods/jobs.html.textile.liquid index a5a3b475ed..539a4a0d3c 100644 --- a/doc/api/methods/jobs.html.textile.liquid +++ b/doc/api/methods/jobs.html.textile.liquid @@ -6,14 +6,15 @@ title: "jobs" ... +See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html +API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/jobs@ Required arguments are displayed in %{background:#ccffcc}green%. - h2. cancel -cancel jobs +Cancel a job that is queued or running. Arguments: @@ -29,29 +30,41 @@ Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|job|object|See "Job resource":{{site.baseurl}}/schema/Job.html|request body|| -|minimum_script_version |string |Git branch, tag, or commit hash specifying the minimum acceptable script version (earliest ancestor) to consider when deciding whether to re-use a past job.|query|@c3e86c9@| -|exclude_script_versions|array of strings|Git commit branches, tags, or hashes to exclude when deciding whether to re-use a past job.|query|@["8f03c71","8f03c71"]@| +{background:#ccffcc}.|job|object|See "Job resource":{{site.baseurl}}/api/schema/Job.html|request body|| +|minimum_script_version |string |Git branch, tag, or commit hash specifying the minimum acceptable script version (earliest ancestor) to consider when deciding whether to re-use a past job.[1]|query|@"c3e86c9"@| +|exclude_script_versions|array of strings|Git commit branches, tags, or hashes to exclude when deciding whether to re-use a past job.|query|@["8f03c71","8f03c71"]@ +@["badtag1","badtag2"]@| +|filters|array|Conditions to find Jobs to reuse.|query|| |find_or_create |boolean |Before creating, look for an existing job that has identical script, script_version, and script_parameters to those in the present job, has nondeterministic=false, and did not fail (it could be queued, running, or completed). If such a job exists, respond with the existing job instead of submitting a new one.|query|@false@| -When a job is executed, the 'script_version' field is resolved to an exact Git revision and the Git hash for that revision is recorded in 'script_version'. If 'script_version' can't be resolved, the job submission will be rejected. +When a job is submitted to the queue using the **create** method, the @script_version@ attribute is updated to a full 40-character Git commit hash based on the current content of the specified repository. If @script_version@ cannot be resolved, the job submission is rejected. -h3. Reusing jobs +fn1. See the "note about specifying Git commits on the Job resource page":{{site.baseurl}}/api/schema/Job.html#script_version for more detail. -Because Arvados records the exact version of the script, input parameters, and runtime environment [1] that was used to run the job, if the script is deterministic (meaning that the same code version is guaranteed to produce the same outputs from the same inputs) then it is possible to re-use the results of past jobs, and avoid re-running the computation to save time. Arvados uses the following algorithm to determine if a past job can be re-used: +h3. Specialized filters -notextile.
+{ + "job": { + "script": "hash.py", + "repository": "you", + "script_version": "master", + "script_parameters": { + "input": "c1bad4b39ca5a924e481008009d94e32+210" + } + }, + "filters": [["script", "=", "hash.py"], + ["repository", "=", "you"], + ["script_version", "in git", "earlier_version_tag"], + ["script_version", "not in git", "blacklisted_version_tag"]], + "find_or_create": true +} +
@@ -133,16 +166,6 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path|| -h2. destroy - -destroy jobs - -Arguments: - -table(table table-bordered table-condensed). -|_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string||path|| - h2. get Gets a Job's metadata by UUID. @@ -153,17 +176,6 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path|| -h2. index - -index jobs - -Arguments: - -table(table table-bordered table-condensed). -|_. Argument |_. Type |_. Description |_. Location |_. Example | -|order|string||query|| -|where|object||query|| - h2. list List jobs. @@ -174,9 +186,9 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | |limit|integer (default 100)|Maximum number of jobs to return.|query|| |order|string|Order in which to return matching jobs.|query|| -|pageToken|string|Page token.|query|| -|q|string|Query string for searching jobs.|query|| -|where|object|Conditions for filtering jobs.|query|| +|filters|array|Conditions for filtering jobs.|query|| + +See the create method documentation for more information about Job-specific filters. h2. log_tail_follow @@ -191,24 +203,16 @@ table(table table-bordered table-condensed). h2. queue -queue jobs +Get the current job queue. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | |order|string||query|| -|where|object||query|| - -h2. show +|filters|array||query|| -show jobs - -Arguments: - -table(table table-bordered table-condensed). -|_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string||path|| +This method is equivalent to the "list method":#list, except that the results are restricted to queued jobs (i.e., jobs that have not yet been started or cancelled) and order defaults to queue priority. h2. update