Distributed Tasks - Ocient Documentation

You can manage distributed tasks in the System. These tasks are processes that execute in the background to keep the system running smoothly and efficiently. These DDL commands create tasks to rebuild damaged or missing segment data and check data integrity. For information on managing tasks, see Manage Distributed Tasks.

CREATE TASK

Launches a new task. Privileges To create any task, you must have the System Administrator role, which has the UPDATE privileges on the system. Syntax

SQL

CREATE TASK [ task_name ]
    TYPE { rebuild | check_disk | rebalance }
    [ LOCATION { SYSTEM | CLUSTER cluster_name | NODE node_name } ]
    [ OPTIONS task_option_map [, ... ] ]

To create a task, you must specify a task type TYPE:

rebuild — Reconstruct data segments by using erasure-coded data in the same segment group.
check_disk — Verify segments on a node by computing checksums.
rebalance — Distribute data evenly across disks in the system.

You can also optionally specify a location using the LOCATION keyword to execute the task. Supported values include:

SYSTEM — Targets all segments in the system. If you do not specify the LOCATION keyword, SYSTEM is the default value.
CLUSTER — Targets a specific cluster.
NODE — Targets a specific node.

Parameter	Data Type	Description
`task_name`	String	Optional. The identifier for the task.
`TYPE`	String	Required. Specifies the type of the distributed task to create. Supported tasks are: `rebuild` — Rebuild task `check_disk` — Check disk task `rebalance` — Rebalance task Task names are case sensitive.
`node_name`	String	This argument is required only if your task targets a node with the `LOCATION NODE` keywords. The name of a specific node for the task to target.
`cluster_name`	String	This argument is required only if your task targets a cluster with the `LOCATION CLUSTER` keywords. The name of a specific cluster for the task to target.
`task_option_map`	Key-value pairs	Optional. A comma-separated list of task-specific options in key-value pair format `key = value`.

`rebuild` Task

Performing a rebuild segment operation reconstructs data segments by using erasure-coded data in the same segment group. This task allows the system to restore segments that are in the damaged DAMAGED or missing MISSING status to full performance. For details on rebuild tasks, see Guide to Rebuilding Segments.

The rebuild task supports only the SYSTEM and CLUSTER locations. If you attempt the rebuild task on the node, the system returns an error.To rebuild a single node, use the cluster location with the LOCATION CLUSTER keywords. Include the name of the node you want to rebuild as one of the key-value options.

rebuild Options (task_option_map) The rebuild task supports these options. You must specify these options as a comma-separated list of key-value pairs.

Option Key	Value Type	Description
`node`	String	Limits the rebuild operation to only segments on the specified node.
`segment_groups`	List	Limits the rebuild operation to the specified segment group identifiers. Specify this option as a bracketed list, e.g., `[ id1, id2, ... ]`.
`table_id`	String	Limits the rebuild to segment groups belonging to a specific table identifier.

Examples Rebuild All Segments on the System This example performs a system-wide rebuild task.

SQL

CREATE TASK TYPE rebuild LOCATION SYSTEM;

Rebuild Segments on the Specific Table This example rebuilds all segments on a system for the specified table with the table identifier 529a2e9d-d06c-46cd-a93b-624d3bed1c08.

SQL

CREATE TASK TYPE rebuild OPTIONS table_id = '529a2e9d-d06c-46cd-a93b-624d3bed1c08';

Rebuild Segments on the Specific Cluster This example rebuilds segments on the Foundation cluster my_lts_cluster1.

SQL

CREATE TASK TYPE rebuild LOCATION CLUSTER my_lts_cluster1;

Rebuild Segments on the Specific Node This example rebuilds segments on the Foundation Node my_node1 in the Foundation Cluster my_lts_cluster1.

SQL

CREATE TASK TYPE rebuild LOCATION CLUSTER my_lts_cluster1 OPTIONS node = 'my_node1';

Rebuild the Specific Segment Group This example rebuilds segments in the segment group with the identifier 53 in the Foundation Cluster my_lts_cluster1.

SQL

CREATE TASK TYPE rebuild LOCATION CLUSTER my_lts_cluster1 OPTIONS segment_groups = [ 53 ];

Create a Named Task This example creates the rebuild task named my_rebuild_task in the Foundation Cluster my_lts_cluster1.

SQL

CREATE TASK my_rebuild_task TYPE rebuild LOCATION CLUSTER my_lts_cluster1;

`check_disk` Task

The check_disk task verifies the integrity of data segments on storage nodes by computing checksums. The task compares stored checksums with recomputed ones to detect disk corruption. check_disk Options (task_option_map) The check_disk task supports these options. You must specify these options as a comma-separated list of key-value pairs.

Option Key	Value Type	Description
`fix`	Boolean	If you set this option value to `true`, the task modifies the storage cluster state based on the checksum result. For example, if the task finds a segment that fails the checksum, the task sets its segment state to `DAMAGED`. Otherwise, the task reports any segments that fail the checksum, but it does not alter segment states. The default value is `false`.
`sample`	Boolean	If you set this option value to `true`, the task checks only a sample of data in each segment. The default value is `false`.
`only_unhealthy`	Boolean	If you set this option value to `true`, the task checks only segments that are not in the `INTACT` state. The default value is `false`.
`storage_ids`	List	This option limits the `check_disk` task to only a specific list of storage identifiers. Specify these storage identifiers as a bracketed list, e.g., `[ 'id1', 'id2', ... ]`.

Examples Perform Checksum on the Specific Node This example computes the checksum on all segments on storage node my_node1.

SQL

CREATE TASK TYPE check_disk LOCATION NODE 'my_node1';

Perform a Checksum on the Specific Cluster This example computes a checksum for a sample of blocks in each segment of the storage cluster my_lts_cluster1 using the sample = true key-value pair.

SQL

CREATE TASK TYPE check_disk LOCATION CLUSTER my_lts_cluster1 OPTIONS sample = true;

Compute Checksum on the Specific Storage Identifier This example computes a checksum for the segment with the storage identifier 529a2e9d-d06c-46cd-a93b-624d3bed1c08 on the storage node my_node1.

SQL

CREATE TASK TYPE check_disk LOCATION NODE 'my_node1' OPTIONS storage_ids = [ '529a2e9d-d06c-46cd-a93b-624d3bed1c08' ];

`rebalance` Task

Rebalancing evenly distributes data across disks in the system. Execute this task if data is not properly balanced across the system, such as after adding nodes or drives. For details on performing a rebalance task, see Expand and Rebalance System.

The rebalance task supports only SYSTEM and CLUSTER locations. If you attempt the rebalance task on a node, the system returns an error.

Example This example performs a rebalance task across all foundation clusters.

SQL

CREATE TASK TYPE rebalance;

CANCEL TASK

Cancels a running task. Privileges To cancel a task, you must be assigned the System Administrator role. Syntax

SQL

CANCEL TASK ('task_name' | 'task_id')

Parameter	Data Type	Description
`task_name`	string	The name specified on task creation. This applies only if an optional name was created for the task.
`task_id`	string	The unique identifier for the task in the system tables. For rebuild tasks, you can find the unique identifier in the sys.result_cache table. For check disk tasks, you can find the unique identifier in the sys.subtasks table.

Example Cancel a task named my_task.

SQL

CANCEL TASK 'my_task';

DROP TASK

Drops orphaned or completed tasks from the system. The task identifier must be a task Universally Unique IDentifier (UUID). The statement does not accept task names because names are not globally unique. A name becomes reusable after its prior task reaches a terminal status, which makes name-based lookup ambiguous. The terminal task statuses are FAILED, CANCELLED, INVALID, COMPLETE, and QUIESCED. By default, when you do not specify any optional keywords, the DROP TASK SQL statement drops a single leaf task. The database throws an error if the task has children or is not in a terminal status. Privileges To drop a task, you must be assigned the System Administrator role. If you have the System Administrator role, you can drop any task. If you are not an administrator, you can drop COALESCE tasks for which you have CREATE privileges or pipeline tasks for which you have EXECUTE privileges. Syntax

SQL

DROP TASK [ IF EXISTS ] uuid [ CASCADE ] [ FORCE ]

Parameter	Data Type	Description
`uuid`	string	The task UUID, which is the unique identifier for the task in the system tables. The statement does not accept task names.

The optional keywords are:

IF EXISTS — Prevents the statement from returning an error when the task is not found.
CASCADE — Drops the entire subtree rooted at the specified task. All tasks in the subtree must be in a terminal status.
FORCE — Skips the terminal-status checks. You can combine the FORCE with CASCADE keywords to force the drop of an entire subtree regardless of task status.

Generally, terminal tasks automatically roll off the system, so executing the DROP TASK SQL statement is not necessary. However, the FORCE and CASCADE keywords can help you drop orphaned tasks from the system in the event of an internal lockup. Be aware that this statement can unintentionally delete the state of in-progress tasks.

Examples Drop a Single Leaf Task This example drops a single leaf task using its UUID.

SQL

DROP TASK '529a2e9d-d06c-46cd-a93b-624d3bed1c08';

Drop a Task Only If It Exists This example drops a task and does not return an error if the system cannot find it.

SQL

DROP TASK IF EXISTS '529a2e9d-d06c-46cd-a93b-624d3bed1c08';

Drop a Task and Its Subtree This example drops the specified task and all tasks in its subtree. All tasks in the subtree must be in a terminal status.

SQL

DROP TASK '529a2e9d-d06c-46cd-a93b-624d3bed1c08' CASCADE;

Force the Drop of a Task Subtree This example drops the specified task and its entire subtree, regardless of the task status.

SQL

DROP TASK '529a2e9d-d06c-46cd-a93b-624d3bed1c08' CASCADE FORCE;

System Catalog Guide to Rebuilding Segments

​CREATE TASK

​rebuild Task

​check_disk Task

​rebalance Task

​CANCEL TASK

​DROP TASK

​Related Links

CREATE TASK

`rebuild` Task

`check_disk` Task

`rebalance` Task

CANCEL TASK

DROP TASK

Related Links