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
  10
  11 Required arguments are displayed in %{background:#ccffcc}green%.
  12
  13
  14 h2. cancel
  15
  16 cancel jobs
  17
  18 Arguments:
  19
  20 table(table table-bordered table-condensed).
  21 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  22 {background:#ccffcc}.|uuid|string||path||
  23
  24 h2(#create). create
  25
  26 Create a new Job.
  27
  28 Arguments:
  29
  30 table(table table-bordered table-condensed).
  31 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  32 {background:#ccffcc}.|job|object|See "Job resource":{{site.baseurl}}/schema/Job.html|request body||
  33 |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@|
  34 |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"]@|
  35 |no_reuse               |boolean    |Disable implicit "find or create" feature: run a new job, even if a job is available with identical script, version, and parameters.|query|@false@|
  36
  37 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.
  38
  39 h3. Reusing jobs
  40
  41 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:
  42
  43 notextile. <div class="spaced-out">
  44
  45 # If 'nondeterministic' or 'no_reuse' are true, always create a new job.
  46 # 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 'script_version' (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.
  47 # Select jobs have the same 'script' and 'script_parameters' attributes, and where the 'script_version' attribute is in the list of acceptable versions.  Exclude jobs that failed or set 'nondeterministic' to true.
  48 # If there is more than one candidate job, check that all selected past jobs actually did produce the same output.
  49 # If everything passed, re-use one of the selected past jobs (if there is more than one match, which job will be returned is undefined).  Otherwise create a new job.
  50
  51 fn1. As of this writing, versioning the runtime environment is still under development.
  52
  53 fn2. This may include parallel branches if there is more than one path between 'minimum_script_version' and 'script_version' in the Git commit graph.  Use 'exclude_script_versions' to blacklist specific versions.
  54
  55 </div>
  56
  57 h3. Examples
  58
  59 Run the script "crunch_scripts/hash.py" in the repository "you" using the "master" branch head.  Arvados is allowed to re-use a previous job if the script_version of the past job is the same as the "master" branch head (i.e., there have not been any subsequent commits to "master").
  60
  61 <notextile><pre>
  62 {
  63   "job": {
  64     "script": "hash.py",
  65     "repository": "<b>you</b>",
  66     "script_version": "master",
  67     "script_parameters": {
  68       "input": "c1bad4b39ca5a924e481008009d94e32+210"
  69     }
  70   }
  71 }
  72 </pre></notextile>
  73
  74 Run using exactly the version "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5". Arvados is allowed to re-use a previous job if the "script_version" of that job is also "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5".
  75
  76 <notextile><pre>
  77 {
  78   "job": {
  79     "script": "hash.py",
  80     "repository": "<b>you</b>",
  81     "script_version": "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5",
  82     "script_parameters": {
  83       "input": "c1bad4b39ca5a924e481008009d94e32+210"
  84     }
  85   }
  86 }
  87 </pre></notextile>
  88
  89 Arvados is allowed to re-use a previous job if the "script_version" of the past job is between "earlier_version_tag" and the head of the "master" branch (inclusive), but not "blacklisted_version_tag".  If there are no previous jobs, run the job using the head of the "master" branch as specified in "script_version".
  90
  91 <notextile><pre>
  92 {
  93   "job": {
  94     "script": "hash.py",
  95     "repository": "<b>you</b>",
  96     "script_version": "master",
  97     "script_parameters": {
  98       "input": "c1bad4b39ca5a924e481008009d94e32+210"
  99     }
 100   },
 101   "minimum_script_version": "earlier_version_tag",
 102   "exclude_script_versions": ["blacklisted_version_tag"]
 103 }
 104 </pre></notextile>
 105
 106 Run the script "crunch_scripts/monte-carlo.py" in the repository "you" using the "master" branch head.  Because it is marked as "nondeterministic", never re-use previous jobs, and never re-use this job.
 107
 108 <notextile><pre>
 109 {
 110   "job": {
 111     "script": "monte-carlo.py",
 112     "repository": "<b>you</b>",
 113     "script_version": "master",
 114     "nondeterministic": true,
 115     "script_parameters": {
 116       "input": "c1bad4b39ca5a924e481008009d94e32+210"
 117     }
 118   }
 119 }
 120 </pre></notextile>
 121
 122 h2. delete
 123
 124 Delete an existing Job.
 125
 126 Arguments:
 127
 128 table(table table-bordered table-condensed).
 129 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 130 {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path||
 131
 132 h2. destroy
 133
 134 destroy jobs
 135
 136 Arguments:
 137
 138 table(table table-bordered table-condensed).
 139 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 140 {background:#ccffcc}.|uuid|string||path||
 141
 142 h2. get
 143
 144 Gets a Job's metadata by UUID.
 145
 146 Arguments:
 147
 148 table(table table-bordered table-condensed).
 149 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 150 {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path||
 151
 152 h2. index
 153
 154 index jobs
 155
 156 Arguments:
 157
 158 table(table table-bordered table-condensed).
 159 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 160 |order|string||query||
 161 |where|object||query||
 162
 163 h2. list
 164
 165 List jobs.
 166
 167 Arguments:
 168
 169 table(table table-bordered table-condensed).
 170 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 171 |limit|integer (default 100)|Maximum number of jobs to return.|query||
 172 |order|string|Order in which to return matching jobs.|query||
 173 |pageToken|string|Page token.|query||
 174 |q|string|Query string for searching jobs.|query||
 175 |where|object|Conditions for filtering jobs.|query||
 176
 177 h2. log_tail_follow
 178
 179 log_tail_follow jobs
 180
 181 Arguments:
 182
 183 table(table table-bordered table-condensed).
 184 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 185 {background:#ccffcc}.|uuid|string||path||
 186 |buffer_size|integer (default 8192)||query||
 187
 188 h2. queue
 189
 190 queue jobs
 191
 192 Arguments:
 193
 194 table(table table-bordered table-condensed).
 195 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 196 |order|string||query||
 197 |where|object||query||
 198
 199 h2. show
 200
 201 show jobs
 202
 203 Arguments:
 204
 205 table(table table-bordered table-condensed).
 206 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 207 {background:#ccffcc}.|uuid|string||path||
 208
 209 h2. update
 210
 211 Update attributes of an existing Job.
 212
 213 Arguments:
 214
 215 table(table table-bordered table-condensed).
 216 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 217 {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path||
 218 |job|object||query||