doc/api/Jobs.textile

   1 ---
   2 layout: default
   3 navsection: api
   4 title: "Resource: Jobs"
   5 navorder: 10
   6 ---
   7
   8 h1. Jobs
   9
  10 Applications submit compute jobs when:
  11 * Provenance is important, i.e., it is worth recording how the output was produced; or
  12 * Computation time is significant; or
  13 * The job management features are convenient (failure detection/recovery, regression testing, etc).
  14
  15 h2. Methods
  16
  17 See "REST methods for working with Arvados resources":methods.html
  18
  19 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/jobs@
  20
  21 h3. Additional parameters for "Create" method
  22
  23 table(table table-bordered table-condensed).
  24 |*Parameter name*|*Type*|*Description*|
  25 |allow_duplicate|boolean|If true, a new job is submitted even if an identical job has already been submitted (and has not failed). If false or not supplied, a new job will _not_ be submitted and the existing job will be returned in the API response.|
  26
  27 h3. Queue
  28
  29 <pre>
  30 GET https://{{ site.arvados_api_host }}/arvados/v1/jobs/queue
  31
  32 POST https://{{ site.arvados_api_host }}/arvados/v1/jobs/queue
  33 _method=GET
  34 where[owner_uuid]=xyzzy-tpzed-a4lcehql0dv2u25
  35 </pre>
  36
  37 &rarr; Job resource list
  38
  39 This method is equivalent to the "index method":methods.html#index, 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.
  40
  41 h2. Resource
  42
  43 Each job has, in addition to the usual "attributes of Arvados resources":resources.html:
  44
  45 table(table table-bordered table-condensed).
  46 |*Property name*|*Type*|*Description*|*Notes*|
  47 |submit_id|string|Unique ID provided by client when job was submitted|Optional. Can be used by client to ensure idempotence|
  48 |priority|string|||
  49 |resource_limits{}|list|Constraints that must be satisfied by the job/task scheduler in order to run the job.|See below.|
  50 |script_name|string|Name of MapReduce script||
  51 |script_parameters{}|list|Parameters passed to MapReduce script||
  52 |script_version|string|git commit/tree used when running the job|If the job has not started, this can be a tag/branch instead of an unambiguous commit id.|
  53 |cancelled_by_client|string|API client ID|Is null if job has not been cancelled|
  54 |cancelled_by_user|string|Authenticated user ID|Is null if job has not been cancelled|
  55 |cancelled_at|string|When job was cancelled|Is null if job has not been cancelled|
  56 |started_at|datetime|When job started running|Is null if job has not [yet] started|
  57 |finished_at|datetime|When job finished running|Is null if job has not [yet] finished|
  58 |running|boolean|Whether the job is running||
  59 |success|boolean|Whether the job indicated successful completion|Is null if job has not finished|
  60 |is_locked_by_uuid|string|UUID of the user who has locked this job|Is null if job is not locked. The system user locks the job when starting the job, in order to prevent job attributes from being altered.|
  61
  62 h3. Resource limits
  63
  64 table(table table-bordered table-condensed).
  65 |*Key*|*Type*|*Description*|*Implemented*|
  66 |min_nodes|integer||&#x2713;|
  67 |max_nodes|integer|||
  68 |max_tasks_per_node|integer|Maximum simultaneous tasks on a single node|&#x2713;|
  69 |min_ram_per_task|integer|Minimum real memory (KiB) per task||
  70 |min_ram_per_node|integer|Minimum real memory (KiB) per node||