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

# /admin/remove/ranks

```
URL: http://<db.host>:<db.port>/admin/remove/ranks
```

Remove one or more ranks from an existing Kinetica cluster. All data will be
rebalanced to other ranks before the rank(s) is removed unless the
*rebalance\_sharded\_data* or *rebalance\_unsharded\_data* parameters are set to
*false* in the input parameter *options*, in which case the corresponding
[sharded data](../../concepts/tables/#sharding) and/or unsharded data
(a.k.a. [randomly-sharded](../../concepts/tables/#random-sharding)) will
be deleted.

The database must be offline for this operation, see
[/admin/offline](/content/api/rest/admin_offline_rest)

This endpoint's processing time depends on the amount of data in the system,
thus the API call may time out if run directly.  It is recommended to run this
endpoint asynchronously via [/create/job](/content/api/rest/create_job_rest).

**NOTE:** This endpoint should be used for on-premise deployments only.

## Input Parameter Description

<ParamField body="ranks" type="array of strings">
  Each array value designates one or more ranks to remove from the cluster. Values can be formatted as 'rankN' for a specific rank, 'hostN' (from the gpudb.conf file) to remove all ranks on that host, or the host IP address (hostN.address from the gpub.conf file) which also removes all ranks on that host. Rank 0 (the head rank) cannot be removed (but can be moved to another host using [/admin/switchover](/content/api/rest/admin_switchover_rest)). At least one worker rank must be left in the cluster after the operation.
</ParamField>

<ParamField body="options" type="map of string to strings">
  Optional parameters.

  The default value is an empty map ( \{} ).

  <Expandable title="options">
    <ParamField body="rebalance_sharded_data">
      If *true*, [sharded data](../../concepts/tables/#sharding) will be rebalanced approximately equally across the cluster. Note that for clusters with large amounts of sharded data, this data transfer could be time consuming and result in delayed query responses.

      The default value is `true`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="rebalance_unsharded_data">
      If *true*, unsharded data (a.k.a. [randomly-sharded](../../concepts/tables/#random-sharding)) will be rebalanced approximately equally across the cluster. Note that for clusters with large amounts of unsharded data, this data transfer could be time consuming and result in delayed query responses.

      The default value is `true`.

      The supported values are:

      * true
      * false
    </ParamField>

    <ParamField body="aggressiveness">
      Influences how much data is moved at a time during rebalance.  A higher *aggressiveness* will complete the rebalance faster.  A lower *aggressiveness* will take longer but allow for better interleaving between the rebalance and other queries. Valid values are constants from 1 (lowest) to 10 (highest).

      The default value is `10`.
    </ParamField>
  </Expandable>
</ParamField>

## Output Parameter Description

The Kinetica server embeds the endpoint response inside a standard response structure which contains status information and the actual response to the query.  Here is a description of the various fields of the wrapper:

<ResponseField name="status" type="String">
  'OK' or 'ERROR'
</ResponseField>

<ResponseField name="message" type="String">
  Empty if success or an error message
</ResponseField>

<ResponseField name="data_type" type="String">
  'admin\_remove\_ranks\_response' or 'none' in case of an error
</ResponseField>

<ResponseField name="data" type="String">
  Empty string
</ResponseField>

<ResponseField name="data_str" type="JSON or String">
  This embedded JSON represents the result of the /admin/remove/ranks endpoint:

  <Expandable title="data_str">
    <ResponseField name="removed_ranks" type="array of strings">
      The number assigned to each rank removed from the cluster. This array will be empty if the operation fails.
    </ResponseField>

    <ResponseField name="info" type="map of string to strings">
      Additional information.
    </ResponseField>
  </Expandable>

  Empty string in case of an error.
</ResponseField>