Manage background jobs

There are many types of background jobs performed in the DBMS, many of which are triggered as system jobs by the DBMS itself without any user action. For example, important background jobs include checkpoint or index population. The former is triggered by the DBMS, and the latter can be a result of a user creating or modifying an index definition.

Background jobs are of the following types:

  • IMMEDIATE - a one-time action, triggered and run in the background.

  • DELAYED - a one-time action, run in the background at a given point in the future.

  • PERIODIC - a recurring action, run in the background at a given time interval.

The DBMS provides a way to show active and failed background jobs. Active jobs are those that are currently running, or are scheduled to be delayed or periodic jobs. If a background job fails, or fails to start, the details of the failure are stored in the failed jobs list. Please note that only the last 100 jobs are stored in the failed jobs list, and that this list is not persistent, so it is cleared with a DBMS restart.

Additionally, it should be noted that a single periodic job can contribute multiple times to the failed jobs list.

Listing active background jobs

An administrator can list background jobs active on an instance:

Syntax:

CALL dbms.scheduler.jobs()

Returns:

Name Type

jobId

ID of the job. Can be used to keep track of an active job, and to link a job to a failed job run.

String

group

A job is a member of a job group. For example, INDEX_POPULATION, LOG_ROTATION or RAFT_SERVER.

String

submitted

A timestamp for when the job was submitted, in ISO-8601 format.

String

database

Jobs can have either a database or a DBMS scope:

  • For database, this column will display the name of the database.

  • For DBMS, this column will be blank.

String

submitter

Jobs are either triggered as a result of user action, or as a system job by the DBMS itself. This column will contain a username for jobs triggered by users, or is otherwise blank.

String

description

A short description of a job that, unlike currentStateDescription, does not change during the running of the job.

String

type

Type of the job. The values can be IMMEDIATE, DELAYED or PERIODIC.

String

scheduledAt

A timestamp for when a DELAYED or PERIODIC job will be run, in ISO-8601 format. This column is not applicable to IMMEDIATE jobs, and will be blank for that job type.

String

period

A period of a PERIODIC job, in format hh:mm:ss.sss.

String

state

A state of the job. Since this procedure lists only active jobs, they can be either in SCHEDULED or EXECUTING state. SCHEDULED state is applicable only to DELAYED or PERIODIC jobs, and means that the job is scheduled for a given time in the future.

String

currentStateDescription

If a job supports reposting its progress, the progress will be reported in this column in a free-form format, specific for each job.

String

Listing failed job executions

An administrator can list job executions failed on an instance:

Syntax:

CALL dbms.scheduler.failedJobs()

Returns:

Name Type

jobId

ID of the failed job.

String

group

A job is a member of a job group. For example, INDEX_POPULATION, LOG_ROTATION or RAFT_SERVER.

String

database

Jobs can have either a database or a DBMS scope:

  • For database, this column will display the name of the database.

  • For DBMS, this column will be blank.

String

submitter

Jobs are either triggered as a result of user action, or as a system job by the DBMS itself. This column will contain a username for jobs triggered by users, or is otherwise blank.

String

description

A short description of a job that, unlike currentStateDescription, does not change during the running of the job.

String

type

Type of the job. The values can be IMMEDIATE, DELAYED or PERIODIC.

String

submitted

A timestamp for when the job was submitted, in ISO-8601 format.

String

executionStart

A timestamp for when the failed execution started, in ISO-8601 format.

String

failureTime

A timestamp for when the execution failed, in ISO-8601 format.

String

failureDescription

A short description of the failure. If the failure description is insufficient, more information can be found in logs.

String