One UQL command-line sentence is generally executed in a real-time fasion, but it can also be running as backgroud task. Ultipa's task mechanism helps users to control the running status of the engine and make real-time adjustments to the computing resources.

Non-Algorithm Background Task

When a UQL sentence is expected to run for a considerable amount of time or take up substantial resources, it's suggested to run it as background task.

Syntax: use the prefix keyword exec task:

exec task <non-algo-uql>

Example:

exec task n().e().n() as p return p{*}

Show Background Task

Returned table name: _top
Returned table header: process_id | process_uql | duration (the id, UQL statement and duration (second) of the task)

Syntax:

// To show all non-algorithm background tasks in the current Ultipa instance
top()

Stop Background Task

Syntax:

// To kill all non-algorithm background tasks in the current Ultipa instance
kill("*")

// To kill a certain non-algorithm background task in the current Ultipa instance
kill(<process_id>)

Algorithm Background Task

When the algorithm involves writing disk operation, i.e. uses the write() parameter, to faciliate the observation of algorithm's running state and management of the algorithm background tasks, UQL supports various operations on algorithm background tasks in different status, as listed below:

Please refer to the the algorithm handbook Ultipa Graph Analytics & Algorithms for the usage of write().

Show Background Task

Returned table name: _task
Returned table header: id | name | params | start | egnineTime | totalTime | result | status (the id, name, parameters, start time, engine duration (second), total duration (second), result and current status of the algorithm background task)

Syntax:

// To show all algorithm background tasks in the current graphset
show().task()
            
// To show a certain algorithm background task in the current graphset
show().task(<id>)
            
// To show all tasks of a certain algorithm in the current graphset
show().task("<taskName>", "*")

// To show all algorithm background tasks of a certain status in the current graphset
show().task("*", "<status>")

// To show all tasks of a certain algorithm and status in the current graphset
show().task("<taskName>", "<status>")

Example: Show all algorithm background tasks of "khop_all"

show().task("khop_all", "*")

Exmaple: Show all algorithm background tasks that are computing

show().task("*", "computing")

Clear Background Task

Syntax:

// To clear all algorithm background tasks in the current graphset (excluding those status are computing and writing)
clear().task("*")
            
// To clear a certain algorithm background task in the current graphset (excluding those status are computing and writing)
clear().task(<id>)
            
// To clear all tasks of a certain algorithm in the current graphset (excluding those status are computing and writing)
clear().task("<taskName>", "*")

// To clear all algorithm background tasks of a certain status in the current graphset (excluding those status are computing and writing)
clear().task("*", "<status>")

// To clear all tasks of a certain algorithm and status in the current graphset (excluding those status are computing and writing)
clear().task("<taskName>", "<status>")

Example: Clear all algorithm background tasks

clear().task("*")

Example: Clear algorithm background task with id = 12

clearTask().id(12)

Example: Clear all "khop_all" background tasks that are pending

clear().task("khop_all", "pending")

Stop Background Task

Syntax:

// To stop all algorithm background tasks that are computing or writing in the current graphset
stop().task("*")
            
// To stop a certain algorithm background task that is computing or writing in the current graphset
stop().task(<id>)

View Statistics

Returned table name: _statistic
Returned table header: cpuUsage | memUsage | expiredDate | cpuCores | company | severType (the CPU usage, memory usage in MB, expiration date, number of CPU cores, company name and server type of the current Ultipa instance)

Syntax:

// To check various system-wide statistical data in the current Ultipa instance
stat()