doc/api/methods/jobs.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "jobs"
   6
   7 ...
   8
   9 See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
  10
  11 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/jobs@
  12
  13 Required arguments are displayed in %{background:#ccffcc}green%.
  14
  15 h2. cancel
  16
  17 Cancel a job that is queued or running.
  18
  19 Arguments:
  20
  21 table(table table-bordered table-condensed).
  22 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  23 {background:#ccffcc}.|uuid|string||path||
  24
  25 h2(#create). create
  26
  27 Create a new Job.
  28
  29 Arguments:
  30
  31 table(table table-bordered table-condensed).
  32 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  33 {background:#ccffcc}.|job|object|See "Job resource":{{site.baseurl}}/api/schema/Job.html|request body||
  34 |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"@|
  35 |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"]@
  36 @["badtag1","badtag2"]@|
  37 |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@|
  38
  39 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.
  40
  41 fn1. See the "note about specifying Git commits on the Job resource page":{{site.baseurl}}/api/schema/Job.html#script_version for more detail.
  42
  43 h3. Reusing jobs
  44
  45 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:
  46
  47 notextile. <div class="spaced-out">
  48
  49 # If @find_or_create@ is false or omitted, create a new job and skip the rest of these steps.
  50 # Find a list of acceptable values for @script_version@.  If @minimum_script_version@ is specified, this is the set of all revisions in the Git commit graph between @minimum_script_version@ and the @script_version@ in the submitted "job object":{{site.baseurl}}/api/schema/Job.html (inclusive)[2].  If @minimum_script_version@ is not specified, only @script_version@ is added to the list.  If @exclude_script_versions@ is specified, the listed versions are excluded from the list.
  51 # Select jobs whose @script@ and @script_parameters@ attributes match those in the submitted "job object":{{site.baseurl}}/api/schema/Job.html, and whose @script_version@ attribute is in the list of acceptable versions.  Exclude jobs that failed or set @nondeterministic@ to true.
  52 # If more than one of the candidate jobs has finished, check that all such jobs actually did produce the same output.
  53 # If existing jobs exist and do not disagree with one another about the correct output, return one of the selected past jobs instead of creating a new job. If there is more than one match, which job will be returned is undefined.
  54 # If an existing job could not be chosen this way, create a new job.
  55
  56 fn1. As of this writing, versioning the runtime environment is still under development.
  57
  58 fn2. This may include parallel branches if there is more than one path between @minimum_script_version@ and the submitted job's @script_version@ in the Git commit graph.  Use @exclude_script_versions@ to blacklist specific commits.
  59
  60 </div>
  61
  62 h3. Examples
  63
  64 Run the script "crunch_scripts/hash.py" in the repository "you" using the "master" commit.  Arvados should re-use a previous job if the script_version of the previous job is the same as the current "master" commit. This works irrespective of whether the previous job was submitted using the name "master", a different branch name or tag indicating the same commit, a SHA-1 commit hash, etc.
  65
  66 <notextile><pre>
  67 {
  68   "job": {
  69     "script": "hash.py",
  70     "repository": "<b>you</b>",
  71     "script_version": "master",
  72     "script_parameters": {
  73       "input": "c1bad4b39ca5a924e481008009d94e32+210"
  74     }
  75   },
  76   "find_or_create": true
  77 }
  78 </pre></notextile>
  79
  80 Run using exactly the version "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5". Arvados should re-use a previous job if the "script_version" of that job is also "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5".
  81
  82 <notextile><pre>
  83 {
  84   "job": {
  85     "script": "hash.py",
  86     "repository": "<b>you</b>",
  87     "script_version": "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5",
  88     "script_parameters": {
  89       "input": "c1bad4b39ca5a924e481008009d94e32+210"
  90     }
  91   },
  92   "find_or_create": true
  93 }
  94 </pre></notextile>
  95
  96 Arvados should re-use a previous job if the "script_version" of the previous job is between "earlier_version_tag" and the "master" commit (inclusive), but not the commit indicated by "blacklisted_version_tag". If there are no previous jobs matching these criteria, run the job using the "master" commit.
  97
  98 <notextile><pre>
  99 {
 100   "job": {
 101     "script": "hash.py",
 102     "repository": "<b>you</b>",
 103     "script_version": "master",
 104     "script_parameters": {
 105       "input": "c1bad4b39ca5a924e481008009d94e32+210"
 106     }
 107   },
 108   "minimum_script_version": "earlier_version_tag",
 109   "exclude_script_versions": ["blacklisted_version_tag"],
 110   "find_or_create": true
 111 }
 112 </pre></notextile>
 113
 114 Run the script "crunch_scripts/monte-carlo.py" in the repository "you" using the current "master" commit. Because it is marked as "nondeterministic", this job will not be considered as a suitable candidate for future job submissions that use the "find_or_create" feature.
 115
 116 <notextile><pre>
 117 {
 118   "job": {
 119     "script": "monte-carlo.py",
 120     "repository": "<b>you</b>",
 121     "script_version": "master",
 122     "nondeterministic": true,
 123     "script_parameters": {
 124       "input": "c1bad4b39ca5a924e481008009d94e32+210"
 125     }
 126   }
 127 }
 128 </pre></notextile>
 129
 130 h2. delete
 131
 132 Delete an existing Job.
 133
 134 Arguments:
 135
 136 table(table table-bordered table-condensed).
 137 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 138 {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path||
 139
 140 h2. get
 141
 142 Gets a Job's metadata by UUID.
 143
 144 Arguments:
 145
 146 table(table table-bordered table-condensed).
 147 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 148 {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path||
 149
 150 h2. list
 151
 152 List jobs.
 153
 154 Arguments:
 155
 156 table(table table-bordered table-condensed).
 157 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 158 |limit|integer (default 100)|Maximum number of jobs to return.|query||
 159 |order|string|Order in which to return matching jobs.|query||
 160 |filters|array|Conditions for filtering jobs.|query||
 161
 162 h2. log_tail_follow
 163
 164 log_tail_follow jobs
 165
 166 Arguments:
 167
 168 table(table table-bordered table-condensed).
 169 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 170 {background:#ccffcc}.|uuid|string||path||
 171 |buffer_size|integer (default 8192)||query||
 172
 173 h2. queue
 174
 175 Get the current job queue.
 176
 177 Arguments:
 178
 179 table(table table-bordered table-condensed).
 180 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 181 |order|string||query||
 182 |filters|array||query||
 183
 184 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.
 185
 186 h2. update
 187
 188 Update attributes of an existing Job.
 189
 190 Arguments:
 191
 192 table(table table-bordered table-condensed).
 193 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 194 {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path||
 195 |job|object||query||