X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/b91db14a4dced9d6ea124e86be3c796e6f2c8e8c..86e078ae126f6651428219c726c34da3bd7f7495:/doc/api/methods/jobs.html.textile.liquid?ds=inline
diff --git a/doc/api/methods/jobs.html.textile.liquid b/doc/api/methods/jobs.html.textile.liquid
index d75977a5f5..90a3c4c722 100644
--- a/doc/api/methods/jobs.html.textile.liquid
+++ b/doc/api/methods/jobs.html.textile.liquid
@@ -34,28 +34,37 @@ table(table table-bordered table-condensed).
|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 of arrays|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 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.
fn1. See the "note about specifying Git commits on the Job resource page":{{site.baseurl}}/api/schema/Job.html#script_version for more detail.
+h3. Specialized filters
+
+Special filter operations are available for specific Job columns.
+
+* @script_version@ @in git@ @REFSPEC@, @arvados_sdk_version@ @in git@ @REFSPEC@
Resolve @REFSPEC@ to a list of Git commits, and match jobs with a @script_version@ or @arvados_sdk_version@ in that list. When creating a job and filtering @script_version@, the search will find commits between @REFSPEC@ and the submitted job's @script_version@; all other searches will find commits between @REFSPEC@ and HEAD. This list may include parallel branches if there is more than one path between @REFSPEC@ and the end commit in the graph. Use @not in@ or @not in git@ filters (below) to blacklist specific commits.
+
+* @script_version@ @not in git@ @REFSPEC@, @arvados_sdk_version@ @not in git@ @REFSPEC@
Resolve @REFSPEC@ to a list of Git commits, and match jobs with a @script_version@ or @arvados_sdk_version@ not in that list.
+
+* @docker_image_locator@ @in docker@ @SEARCH@
@SEARCH@ can be a Docker image hash, a repository name, or a repository name and tag separated by a colon (@:@). The server will find collections that contain a Docker image that match that search criteria, then match jobs with a @docker_image_locator@ in that list.
+
+* @docker_image_locator@ @not in docker@ @SEARCH@
Negate the @in docker@ filter.
+
h3. Reusing jobs
-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:
+Because Arvados records the exact version of the script, input parameters, and runtime environment 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:
notextile.
+{ + "job": { + "script": "hash.py", + "repository": "you/you", + "script_version": "master", + "script_parameters": { + "input": "c1bad4b39ca5a924e481008009d94e32+210" + } + }, + "filters": [["script", "=", "hash.py"], + ["repository", "=", "you/you"], + ["script_version", "in git", "earlier_version_tag"], + ["script_version", "not in git", "blacklisted_version_tag"]], + "find_or_create": true +} +
{ "job": { "script": "monte-carlo.py", - "repository": "you", + "repository": "you/you", "script_version": "master", "nondeterministic": true, "script_parameters": { @@ -159,6 +188,8 @@ table(table table-bordered table-condensed). |order|string|Order in which to return matching 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 log_tail_follow jobs