Task Management

Note: If you are trying to schedule tasks in Foxx you shouldconsider using the instead,which provides a more high-level API that also persists tasks across reboots.

ArangoDB can execute user-defined JavaScript functions as one-shotor periodic tasks. This functionality can be used to implement timedor recurring jobs in the database.

Tasks in ArangoDB consist of a JavaScript snippet or function that isexecuted when the task is scheduled. A task can be a one-shot task(meaning it is run once and not repeated) or a periodic task (meaningthat it is re-scheduled after each execution). Tasks can have optionalparameters, which are defined at task setup time. The parametersspecified at task setup time will be passed as arguments to thetask whenever it gets executed. Periodic Tasks have an executionfrequency that needs to be specified when the task is set up. One-shottasks have a configurable delay after which they’ll get executed.

Tasks will be executed on the server they have been set up on.Tasks will not be shipped around in a cluster. A task will beexecuted in the context of the database it was created in. However,when dropping a database, any tasks that were created in the contextof this database will remain active. It is therefore sensible tofirst unregister all active tasks for a database before dropping thedatabase.

Tasks registered in ArangoDB will be executed until the servergets shut down or restarted. After a restart of the server, anyuser-defined one-shot or periodic tasks will be lost.

ArangoDB provides the following commands for working with tasks.All commands can be accessed via the tasks module, which can beloaded like this:

Please note that the tasks module is available inside the ArangoDBserver only. It cannot be used from the ArangoShell or ArangoDB’s webinterface.

To register a task, the JavaScript snippet or function needs to bespecified in addition to the execution frequency. Optionally, a taskcan have an id and a name. If no id is specified, it will be auto-assignedfor a new task. The task id is also the means to access or unregister atask later. Task names are informational only. They can be used to makea task distinguishable from other tasks also running on the server.

The following server-side commands register a task. The command to beexecuted is a JavaScript string snippet which prints a message to theserver’s logfile:

The above has register a task with id mytask-1, which will be executedevery 15 seconds on the server. The task will write a log message wheneverit is invoked.

Tasks can also be set up using a JavaScript callback function like this:

const tasks = require("@arangodb/tasks");
tasks.register({
  name: "this is a function task",
  period: 15,
    require('console').log('hello from function task');
  }
});

It is important to note that the callback function is late bound andwill be executed in a different context than in the creation context.The callback function must therefore not access any variables definedoutside of its own scope. The callback function can still define anduse its own variables.

Registering a one-shot task works the same way, except that theperiod attribute must be omitted. If period is omitted, then thetask will be executed just once. The task invocation delay can optionallybe specified with the offset attribute:

const tasks = require("@arangodb/tasks");
  id: "mytask-once",
  offset: 10,
  command: function (params) {
    require('console').log('you will see me just once!');
  }
});

Note: When specifying an offset value of 0, ArangoDB will internally adda very small value to the offset so will be slightly greater than zero.

After a task has been registered, it can be unregistered using its id:

Note that unregistering a non-existing task will throw an exception.

To get an overview of which tasks are registered, there is the get_method. If the _get method is called without any arguments, it willreturn an array of all tasks:

const tasks = require("@arangodb/tasks");

If get is called with a task id argument, it will return informationabout this particular task: