Improved language about git revisions a bit based on review feeback.
[arvados.git] / 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||query||
33
34 Attributes of 'job' parameter:
35
36 table(table table-bordered table-condensed).
37 |_. Attribute               |_. Type|_. Accepted values                            |_. Description|
38 {background:#ccffcc}.|script                 |string     |filename                                      |The actual script that will be run by crunch.  Must be the name of an executable file in the crunch_scripts/ directory at the git revision specified by script_version.|
39 {background:#ccffcc}.|script_version         |string     |git branch, tag, or commit hash               |The version of code to run, which must be available in the specified repository.|
40 {background:#ccffcc}.|repository             |string     |name of git repository hosted by Arvados      |The repository to search for script_version.|
41 {background:#ccffcc}.|script_parameters      |object     |any JSON object                               |The input parameters for the job, with the parameter names as keys mapping to parameter values.|
42 |minimum_script_version |string     |git branch, tag, or commit hash              |The minimum acceptable script version (earliest ancestor) to consider when deciding whether to re-use a past job.|
43 |exclude_script_versions|array of strings|git branch, tag, or commit hash|Script versions to exclude when deciding whether to re-use a past job.|
44 |nondeterministic       |boolean    |                                              |If true, never re-use a past job, and flag this job so it will never be considered for re-use.|
45 |no_reuse               |boolean    |                                              |If true, do not re-use a past job, but this job may be re-used.|
46
47 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.
48
49 h3. Reusing jobs
50
51 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:
52
53 notextile. <div class="spaced-out">
54
55 # If 'nondeterministic' or 'no_reuse' are true, always create a new job.
56 # 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.
57 # 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.
58 # If there is more than one candidate job, check that all selected past jobs actually did produce the same output.
59 # 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.
60
61 fn1. As of this writing, versioning the runtime environment is still under development.
62
63 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.
64
65 </div>
66
67 h3. Examples
68
69 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").
70
71 <notextile><pre>
72 {
73   "script": "hash.py",
74   "repository": "<b>you</b>",
75   "script_version": "master",
76   "script_parameters": {
77     "input": "c1bad4b39ca5a924e481008009d94e32+210"
78   }
79 }
80 </pre></notextile>
81
82 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".
83
84 <notextile><pre>
85 {
86   "script": "hash.py",
87   "repository": "<b>you</b>",
88   "script_version": "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5",
89   "script_parameters": {
90     "input": "c1bad4b39ca5a924e481008009d94e32+210"
91   }
92 }
93 </pre></notextile>
94
95 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".
96
97 <notextile><pre>
98 {
99   "script": "hash.py",
100   "repository": "<b>you</b>",
101   "minimum_script_version": "earlier_version_tag",
102   "script_version": "master",
103   "exclude_script_versions": ["blacklisted_version_tag"],
104   "script_parameters": {
105     "input": "c1bad4b39ca5a924e481008009d94e32+210"
106   }
107 }
108 </pre></notextile>
109
110 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.
111
112 <notextile><pre>
113 {
114   "script": "monte-carlo.py",
115   "repository": "<b>you</b>",
116   "script_version": "master",
117   "nondeterministic": true,
118   "script_parameters": {
119     "input": "c1bad4b39ca5a924e481008009d94e32+210"
120   }
121 }
122 </pre></notextile>
123
124 h2. delete
125
126 Delete an existing Job.
127
128 Arguments:
129
130 table(table table-bordered table-condensed).
131 |_. Argument |_. Type |_. Description |_. Location |_. Example |
132 {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path||
133
134 h2. destroy
135
136 destroy jobs
137
138 Arguments:
139
140 table(table table-bordered table-condensed).
141 |_. Argument |_. Type |_. Description |_. Location |_. Example |
142 {background:#ccffcc}.|uuid|string||path||
143
144 h2. get
145
146 Gets a Job's metadata by UUID.
147
148 Arguments:
149
150 table(table table-bordered table-condensed).
151 |_. Argument |_. Type |_. Description |_. Location |_. Example |
152 {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path||
153
154 h2. index
155
156 index jobs
157
158 Arguments:
159
160 table(table table-bordered table-condensed).
161 |_. Argument |_. Type |_. Description |_. Location |_. Example |
162 |order|string||query||
163 |where|object||query||
164
165 h2. list
166
167 List jobs.
168
169 Arguments:
170
171 table(table table-bordered table-condensed).
172 |_. Argument |_. Type |_. Description |_. Location |_. Example |
173 |limit|integer (default 100)|Maximum number of jobs to return.|query||
174 |order|string|Order in which to return matching jobs.|query||
175 |pageToken|string|Page token.|query||
176 |q|string|Query string for searching jobs.|query||
177 |where|object|Conditions for filtering jobs.|query||
178
179 h2. log_tail_follow
180
181 log_tail_follow jobs
182
183 Arguments:
184
185 table(table table-bordered table-condensed).
186 |_. Argument |_. Type |_. Description |_. Location |_. Example |
187 {background:#ccffcc}.|uuid|string||path||
188 |buffer_size|integer (default 8192)||query||
189
190 h2. queue
191
192 queue jobs
193
194 Arguments:
195
196 table(table table-bordered table-condensed).
197 |_. Argument |_. Type |_. Description |_. Location |_. Example |
198 |order|string||query||
199 |where|object||query||
200
201 h2. show
202
203 show jobs
204
205 Arguments:
206
207 table(table table-bordered table-condensed).
208 |_. Argument |_. Type |_. Description |_. Location |_. Example |
209 {background:#ccffcc}.|uuid|string||path||
210
211 h2. update
212
213 Update attributes of an existing Job.
214
215 Arguments:
216
217 table(table table-bordered table-condensed).
218 |_. Argument |_. Type |_. Description |_. Location |_. Example |
219 {background:#ccffcc}.|uuid|string|The UUID of the Job in question.|path||
220 |job|object||query||