Skip to navigation
SQL ReferenceData Definition Language (DDL) Statement Reference

Distributed Tasks

View as Markdown

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

CREATE TASK

Launches a new task.

To create a rebuild or check disk task, you must be assigned the System Administrator role.

Syntax

CREATE TASK {
   <rebuild_segment_task_definition>
   | <check_disk_task_definition>
   | <rebalance_task_definition>
   }
<rebuild_segment_task_definition> ::=
    [name] TYPE REBUILD [ OPTIONS ('location_type' [, 'location_name' [, <rebuild_args> ]])]
<check_disk_task_definition> ::=
    [name] TYPE CHECK_DISK
        [ OPTIONS ('location_type' [, 'location_name' [, <check_disk_args> ]])]
<rebalance_task_definition> ::=
    [name] TYPE REBALANCE

Rebuilding Segment Task ( <rebuild_segment_task_definition> )

Performing a rebuild segment operation reconstructs data segments by using erasure-coded data in the same segment group. This task allows segments that are in DAMAGED or MISSING status to be restored to full performance.

For details about rebuild tasks, see the Guide to Rebuilding Segments. To create a rebuild segment task, you must have UPDATE privileges on the system.

Specifying locationType of SYSTEM means every segment in the system is rebuilt. Alternatively, you can specify individual clusters or nodes by name to rebuild their segments.

ParameterData TypeDescription
namestringAn optional identifier for the task.
location_typestringSpecify the type of location for rebuild from these selections: 'SYSTEM' | 'CLUSTER'
The value definitions are:
SYSTEM — Every segment in the system is rebuilt.
CLUSTER — Only the cluster specified by the location_name parameter is rebuilt.
location_namestringThe name of a specific cluster to rebuild.

Rebuild Arguments ( <rebuild_args> )

Additional arguments for the rebuild task. These arguments must be in a valid JSON format. All fields are optional. You must specify all arguments in a single JSON object.

<rebuild_args> ::=
'{
  "node": "node_name",
  "segment_groups": segment_array,
  "table_id": "table_id_string"
}'
ParameterData TypeDescription
nodestringIf included, this option limits the rebuild process to only rebuild segments on the node specified by node_name.
If not included, the system rebuilds all segment groups on the cluster or system.
segment_groupsstringIf included, this option limits the rebuild process to only the identifiers for the rebuild segment groups specified in the segment_array.
If not included, the system rebuilds all segment groups on the cluster or system.
table_idstringIf included, this option limits the rebuild process to only rebuild segment groups that belong to the table identifier specified in the table_id_string.
If not included, the system rebuilds all segment groups on the cluster or system.

Checking Disk Task ( <check_disk_task_definition> )

A CHECK_DISK task verifies the segments on a node by computing checksums.

ParameterData TypeDescription
namestringAn optional identifier for the task.
location_typestringThe type of location for the check disk task to be performed on. Supported location_type values include:
[ 'SYSTEM' | 'CLUSTER' | 'NODE' ]
The value definitions are:
SYSTEM — The task includes all segments.
CLUSTER — The task covers only a cluster specified by the location_name.
NODE — The task covers only a node specified by the location_name.
location_namestringThe specific name of the location where the check disk task is to be performed. This argument is required if the location_type argument is set to 'CLUSTER' or 'NODE'.

Check Disk Arguments (<check_disk_args>)

Arguments must be in a valid JSON format. All fields are optional. You must specify all arguments in a single JSON object.

<check_disk_args> ::=
'{
   "fix": true,
   "sample": false,
   "only_unhealthy":false,
   "storage_ids": ["02c65e30-3651-478e-96bf-9935c1bc8fb4"]
}'
ParameterData TypeDescription
fixBooleanIf set to true, this option modifies the storage cluster state based on the result of the checksum verification.
For example, if you set the fix option, the system moves a segment that fails the checksum from the INTACT state to the DAMAGED state.
sampleBooleanIf set to true, this option checks only a sample of data in each segment.
only_unhealthyBooleanIf set to true, this option checks only stored segments that are not in the INTACT state.
storage_idsstringThis option limits the disk check operation to include only the specified segment storage identifiers. Otherwise, the system checks all segments on the node.

Examples

Rebuild all segments on a system.

CREATE TASK TYPE rebuild;
CREATE TASK TYPE rebuild OPTIONS ('SYSTEM');

Rebuild all segments on a system for a specified table with the table identifier 529a2e9d-d06c-46cd-a93b-624d3bed1c08.

CREATE TASK TYPE rebuild OPTIONS ('SYSTEM', '{"table_id": "529a2e9d-d06c-46cd-a93b-624d3bed1c08"}');

Rebuild segments on Foundation cluster my_lts_cluster1.

CREATE TASK TYPE rebuild OPTIONS ('CLUSTER', 'my_lts_cluster1');

Rebuild segments on a Foundation Node my_node1.

CREATE TASK TYPE rebuild OPTIONS ('CLUSTER', 'my_lts_cluster1', '{"node": "my_node1"}');

Rebuild segments on a segment group with the identifier 53.

CREATE TASK TYPE rebuild OPTIONS ('CLUSTER', 'my_lts_cluster1', '{"segment_groups": [53]}');

Rebuild only the segment in segment group 53 on a Foundation Node my_node.

CREATE TASK TYPE rebuild OPTIONS ('CLUSTER', 'my_lts_cluster1', '{"node": "my_node1", "segment_groups": [53]}');

Compute the checksum on all segments on storage node my_node1.

CREATE TASK TYPE check_disk OPTIONS ('NODE', 'my_node1');

Compute a checksum on a sample of blocks for each segment on storage cluster my_lts_cluster1.

CREATE TASK TYPE check_disk OPTIONS ('CLUSTER', 'my_lts_cluster1', '{"sample": true}');

Compute a checksum on all nodes in the system and modify the state based on the result.

CREATE TASK TYPE check_disk OPTIONS ('SYSTEM', '{"fix": true}');

Compute a checksum for a segment with storage identifier 529a2e9d-d06c-46cd-a93b-624d3bed1c08 on the storage node my_node1.

CREATE TASK TYPE check_disk OPTIONS ('NODE', 'my_node1', '{"storage_ids": ["529a2e9d-d06c-46cd-a93b-624d3bed1c08"]}');

Rebalance Task (<rebalance_task_definition>)

Rebalancing evenly distributes data across disks in the system. Run this task if data is not balanced properly across the system, such as after adding additional nodes or drives.

For details about rebalancing, see Expand and Rebalance System.

CANCEL TASK 

Cancels a running task. 

To cancel a task, you must be assigned the System Administrator role. 

Syntax

CANCEL TASK ('task_name' | 'task_id')
ParameterData TypeDescription
task_namestringThe name specified on task creation. This applies only if an optional name was created for the task.
task_idstringThe 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.

CANCEL TASK 'my_task';

System Catalog

Guide to Rebuilding Segments