jobs

Creates, updates, deletes, gets or lists a jobs resource.

Overview

Name	jobs
Type	Resource
Id	aws.batch.jobs

Fields

The following fields are returned by SELECT queries:

describe_jobs

Name	Datatype	Description
jobs	array	The list of jobs.

list_jobs

Name	Datatype	Description
array_properties	object	The array properties of the job, if it's an array job.
capacity_usage	array	The configured capacity usage information for this job, including the unit of measure and quantity of resources.
container	object	An object that represents the details of the container that's associated with the job.
created_at	integer (int64)	The Unix timestamp (in milliseconds) for when the job was created. For non-array jobs and parent array jobs, this is when the job entered the SUBMITTED state (at the time SubmitJob was called). For array child jobs, this is when the child job was spawned by its parent and entered the PENDING state.
job_arn	string	The Amazon Resource Name (ARN) of the job.
job_definition	string	The Amazon Resource Name (ARN) of the job definition.
job_id	string	The job ID.
job_name	string	The job name.
node_properties	object	The node properties for a single node in a job summary list. This isn't applicable to jobs that are running on Fargate resources.
scheduled_at	integer (int64)	The Unix timestamp (in milliseconds) for when the job was scheduled for execution. For more information on job statues, see Service job status in the Batch User Guide.
share_identifier	string	The share identifier for the fairshare scheduling queue that this job is associated with.
started_at	integer (int64)	The Unix timestamp for when the job was started. More specifically, it's when the job transitioned from the STARTING state to the RUNNING state.
status	string	The current status for the job. (SUBMITTED, PENDING, RUNNABLE, STARTING, RUNNING, SUCCEEDED, FAILED)
status_reason	string	A short, human-readable string to provide more details for the current status of the job.
stopped_at	integer (int64)	The Unix timestamp for when the job was stopped. More specifically, it's when the job transitioned from the RUNNING state to a terminal state, such as SUCCEEDED or FAILED.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_jobs	select	region		Describes a list of Batch jobs.
list_jobs	select	region		Returns a list of Batch jobs. You must specify only one of the following items: A job queue ID to return a list of jobs in that job queue A multi-node parallel job ID to return a list of nodes for that job An array job ID to return a list of the children for that job
terminate_job	delete	region		Terminates a job in a job queue. Jobs that are in the STARTING or RUNNING state are terminated, which causes them to transition to FAILED. Jobs that have not progressed to the STARTING state are cancelled.
cancel_job	exec	region, jobId, reason		Cancels a job in an Batch job queue. Jobs that are in a SUBMITTED, PENDING, or RUNNABLE state are cancelled and the job status is updated to FAILED. A PENDING job is canceled after all dependency jobs are completed. Therefore, it may take longer than expected to cancel a job in PENDING status. When you try to cancel an array parent job in PENDING, Batch attempts to cancel all child jobs. The array parent job is canceled when all child jobs are completed. Jobs that progressed to the STARTING or RUNNING state aren't canceled. However, the API operation still succeeds, even if no job is canceled. These jobs must be terminated with the TerminateJob operation.
submit_job	exec	region, jobName, jobQueue, jobDefinition		Submits an Batch job from a job definition. Parameters that are specified during SubmitJob override parameters defined in the job definition. vCPU and memory requirements that are specified in the resourceRequirements objects in the job definition are the exception. They can't be overridden this way using the memory and vcpus parameters. Rather, you must specify updates to job definition parameters in a resourceRequirements object that's included in the containerOverrides parameter. Job queues with a scheduling policy are limited to 500 active share identifiers at a time. Jobs that run on Fargate resources can't be guaranteed to run for more than 14 days. This is because, after 14 days, Fargate resources might become unavailable and job might be terminated.
submit_service_job	exec	region, jobName, jobQueue, serviceRequestPayload, serviceJobType		Submits a service job to a specified job queue to run on SageMaker AI. A service job is a unit of work that you submit to Batch for execution on SageMaker AI.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_jobs

Describes a list of Batch jobs.

SELECT
jobs
FROM aws.batch.jobs
WHERE region = '{{ region }}' -- required
;

list_jobs

Returns a list of Batch jobs. You must specify only one of the following items: A job queue ID to return a list of jobs in that job queue A multi-node parallel job ID to return a list of nodes for that job An array job ID to return a list of the children for that job

SELECT
array_properties,
capacity_usage,
container,
created_at,
job_arn,
job_definition,
job_id,
job_name,
node_properties,
scheduled_at,
share_identifier,
started_at,
status,
status_reason,
stopped_at
FROM aws.batch.jobs
WHERE region = '{{ region }}' -- required
;

DELETE examples

terminate_job

Terminates a job in a job queue. Jobs that are in the STARTING or RUNNING state are terminated, which causes them to transition to FAILED. Jobs that have not progressed to the STARTING state are cancelled.

DELETE FROM aws.batch.jobs
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

cancel_job

Cancels a job in an Batch job queue. Jobs that are in a SUBMITTED, PENDING, or RUNNABLE state are cancelled and the job status is updated to FAILED. A PENDING job is canceled after all dependency jobs are completed. Therefore, it may take longer than expected to cancel a job in PENDING status. When you try to cancel an array parent job in PENDING, Batch attempts to cancel all child jobs. The array parent job is canceled when all child jobs are completed. Jobs that progressed to the STARTING or RUNNING state aren't canceled. However, the API operation still succeeds, even if no job is canceled. These jobs must be terminated with the TerminateJob operation.

EXEC aws.batch.jobs.cancel_job 
@region='{{ region }}' --required 
@@json=
'{
"jobId": "{{ jobId }}", 
"reason": "{{ reason }}"
}'
;

submit_job

Submits an Batch job from a job definition. Parameters that are specified during SubmitJob override parameters defined in the job definition. vCPU and memory requirements that are specified in the resourceRequirements objects in the job definition are the exception. They can't be overridden this way using the memory and vcpus parameters. Rather, you must specify updates to job definition parameters in a resourceRequirements object that's included in the containerOverrides parameter. Job queues with a scheduling policy are limited to 500 active share identifiers at a time. Jobs that run on Fargate resources can't be guaranteed to run for more than 14 days. This is because, after 14 days, Fargate resources might become unavailable and job might be terminated.

EXEC aws.batch.jobs.submit_job 
@region='{{ region }}' --required 
@@json=
'{
"jobName": "{{ jobName }}", 
"jobQueue": "{{ jobQueue }}", 
"shareIdentifier": "{{ shareIdentifier }}", 
"schedulingPriorityOverride": {{ schedulingPriorityOverride }}, 
"arrayProperties": "{{ arrayProperties }}", 
"dependsOn": "{{ dependsOn }}", 
"jobDefinition": "{{ jobDefinition }}", 
"parameters": "{{ parameters }}", 
"containerOverrides": "{{ containerOverrides }}", 
"nodeOverrides": "{{ nodeOverrides }}", 
"retryStrategy": "{{ retryStrategy }}", 
"propagateTags": {{ propagateTags }}, 
"timeout": "{{ timeout }}", 
"tags": "{{ tags }}", 
"eksPropertiesOverride": "{{ eksPropertiesOverride }}", 
"ecsPropertiesOverride": "{{ ecsPropertiesOverride }}", 
"consumableResourcePropertiesOverride": "{{ consumableResourcePropertiesOverride }}"
}'
;

submit_service_job

Submits a service job to a specified job queue to run on SageMaker AI. A service job is a unit of work that you submit to Batch for execution on SageMaker AI.

EXEC aws.batch.jobs.submit_service_job 
@region='{{ region }}' --required 
@@json=
'{
"jobName": "{{ jobName }}", 
"jobQueue": "{{ jobQueue }}", 
"retryStrategy": "{{ retryStrategy }}", 
"schedulingPriority": {{ schedulingPriority }}, 
"serviceRequestPayload": "{{ serviceRequestPayload }}", 
"serviceJobType": "{{ serviceJobType }}", 
"shareIdentifier": "{{ shareIdentifier }}", 
"quotaShareName": "{{ quotaShareName }}", 
"preemptionConfiguration": "{{ preemptionConfiguration }}", 
"timeoutConfig": "{{ timeoutConfig }}", 
"tags": "{{ tags }}", 
"clientToken": "{{ clientToken }}"
}'
;