> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Distributed Tasks

export const Ocient = "Ocient®";

You can manage distributed tasks in the {Ocient} 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](/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 SQL theme={null}
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](#rebuild-task) — Reconstruct data segments by using erasure-coded data in the same segment group.
* [check\_disk](#check_disk-task) — Verify segments on a node by computing checksums.
* [rebalance](#rebalance-task) — 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.<br /><br />The identifier for the task.                                                                                                                                                                                         |
| `TYPE`            | String          | Required. Specifies the type of the distributed task to create. Supported tasks are: <br /><br />`rebuild` — Rebuild task<br />`check_disk` — Check disk task<br />`rebalance` — Rebalance task<br /><br />Task names are case sensitive. |
| `node_name`       | String          | This argument is required only if your task targets a node with the `LOCATION NODE` keywords.<br /><br />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.<br /><br />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](/guide-to-rebuilding-segments).

<Info>
  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.
</Info>

`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 SQL theme={null}
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 SQL theme={null}
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 SQL theme={null}
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 SQL theme={null}
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 SQL theme={null}
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 SQL theme={null}
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`.<br /><br />Otherwise, the task reports any segments that fail the checksum, but it does not alter segment states.<br /><br />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.<br /><br />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.<br /><br />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 SQL theme={null}
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 SQL theme={null}
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 SQL theme={null}
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](/expand-and-rebalance-system).

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

**Example**

This example performs a rebalance task across all foundation clusters.

```sql SQL theme={null}
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 SQL theme={null}
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. <br />For rebuild tasks, you can find the unique identifier in the [sys.result\_cache](/system-catalog#sys-result_cache) table.<br />For check disk tasks, you can find the unique identifier in the [sys.subtasks](/system-catalog#sys-subtasks) table. |

**Example** 

Cancel a task named `my_task`.

```sql SQL theme={null}
CANCEL TASK 'my_task';
```

## Related Links

[System Catalog](/system-catalog)

[Guide to Rebuilding Segments](/guide-to-rebuilding-segments)