X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/ebc3fddd97628a50148ed90531b0a18d1cc867f9..refs/heads/8872-node-manager-create-search-handling-wip:/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 879feb43af..90a3c4c722 100644 --- a/doc/api/methods/jobs.html.textile.liquid +++ b/doc/api/methods/jobs.html.textile.liquid @@ -34,7 +34,7 @@ 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|Conditions to find Jobs to reuse.|query|| +|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. @@ -45,9 +45,9 @@ h3. Specialized filters Special filter operations are available for specific Job columns. -* @script_version@ @in git@ @REFSPEC@
Resolve @REFSPEC@ to a list of git commits, and match jobs with a @script_version@ in that list. The create method will find commits between @REFSPEC@ and the submitted job's @script_version@; the list method will search 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@ @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@
Resolve @REFSPEC@ to a list of git commits, and match jobs with a @script_version@ not in that list. +* @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. @@ -60,8 +60,8 @@ Because Arvados records the exact version of the script, input parameters, and r notextile.
# If @find_or_create@ is false or omitted, create a new job and skip the rest of these steps. -# If @filters@ are specified, find jobs that match those filters. Filters *must* be specified to limit the @repository@ and @script@ attributes. An error is returned if they are missing. -# If @filters@ are not specified, find jobs with the same @repository@ and @script@, with a @script_version@ between @minimum_script_version@ and @script_version@ (excluding @excluded_script_versions@), and a @docker_image_locator@ with the latest Collection that matches the submitted job's @docker_image@ constraint. +# If @filters@ are specified, find jobs that match those filters. If any filters are given, there must be at least one filter on the @repository@ attribute and one on the @script@ attribute: otherwise an error is returned. +# If @filters@ are not specified, find jobs with the same @repository@ and @script@, with a @script_version@ between @minimum_script_version@ and @script_version@ inclusively (excluding @excluded_script_versions@), and a @docker_image_locator@ with the latest Collection that matches the submitted job's @docker_image@ constraint. If the submitted job includes an @arvados_sdk_version@ constraint, jobs must have an @arvados_sdk_version@ between that refspec and HEAD to be found. *This form is deprecated: use filters instead.* # If the found jobs include a completed job, and all found completed jobs have consistent output, return one of them. Which specific job is returned is undefined. # If the found jobs only include incomplete jobs, return one of them. Which specific job is returned is undefined. # If no job has been returned so far, create and return a new job. @@ -76,7 +76,7 @@ Run the script "crunch_scripts/hash.py" in the repository "you" using the "maste { "job": { "script": "hash.py", - "repository": "you", + "repository": "you/you", "script_version": "master", "script_parameters": { "input": "c1bad4b39ca5a924e481008009d94e32+210" @@ -92,7 +92,7 @@ Run using exactly the version "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5". Arvado { "job": { "script": "hash.py", - "repository": "you", + "repository": "you/you", "script_version": "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5", "script_parameters": { "input": "c1bad4b39ca5a924e481008009d94e32+210" @@ -108,7 +108,7 @@ Arvados should re-use a previous job if the "script_version" of the previous job { "job": { "script": "hash.py", - "repository": "you", + "repository": "you/you", "script_version": "master", "script_parameters": { "input": "c1bad4b39ca5a924e481008009d94e32+210" @@ -120,13 +120,33 @@ Arvados should re-use a previous job if the "script_version" of the previous job } -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. +The same behavior, using filters: + +
+{
+  "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
+}
+
 + +Run the script "crunch_scripts/monte-carlo.py" in the repository "you/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. 
 {
   "job": {
     "script": "monte-carlo.py",
-    "repository": "you",
+    "repository": "you/you",
     "script_version": "master",
     "nondeterministic": true,
     "script_parameters": {