> ## 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/add/ranks

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

Add one or more ranks to an existing Kinetica cluster. The new ranks will not
contain any data initially (other than replicated tables) and will not be
assigned any shards. To rebalance data and shards across the cluster, use
[/admin/rebalance](/content/api/rest/admin_rebalance_rest).

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

For example, if attempting to add three new ranks (two ranks on host
172.123.45.67 and one rank on host 172.123.45.68) to a Kinetica cluster with
additional configuration parameters:

* input parameter *hosts* would be an array including 172.123.45.67 in the
  first two indices (signifying two ranks being added to host 172.123.45.67)
  and 172.123.45.68 in the last index (signifying one rank being added to host
  172.123.45.67)
* input parameter *config\_params* would be an array of maps, with each map
  corresponding to the ranks being added in input parameter *hosts*. The key of
  each map would be the configuration parameter name and the value would be the
  parameter's value, e.g. '\{"rank.gpu":"1"}'

This endpoint's processing includes copying all replicated table data to the
new rank(s) and therefore could take a long time. 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="hosts" type="array of strings">
  Array of host IP addresses (matching a hostN.address from the gpudb.conf file), or host identifiers (e.g. 'host0' from the gpudb.conf file), on which to add ranks to the cluster. The hosts must already be in the cluster. If needed beforehand, to add a new host to the cluster use [/admin/add/host](/content/api/rest/admin_add_host_rest). Include the same entry as many times as there are ranks to add to the cluster, e.g., if two ranks on host 172.123.45.67 should be added, input parameter *hosts* could look like '\["172.123.45.67", "172.123.45.67"]'. All ranks will be added simultaneously, i.e. they're not added in the order of this array. Each entry in this array corresponds to the entry at the same index in the input parameter *config\_params*.
</ParamField>

<ParamField body="config_params" type="array of maps of string to strings">
  Array of maps containing configuration parameters to apply to the new ranks found in input parameter *hosts*. For example, '\{"rank.gpu":"2", "tier.ram.rank.limit":"10000000000"}'. Currently, the available parameters are rank-specific parameters in the [Network](../../config/#config-main-network), [Hardware](../../config/#config-main-hardware), [Text Search](../../config/#config-main-text-search), and [RAM Tiered Storage](../../config/#config-main-ram-tier) sections in the gpudb.conf file, with the key exception of the 'rankN.host' settings in the Network section that will be determined by input parameter *hosts* instead. Though many of these configuration parameters typically are affixed with 'rankN' in the gpudb.conf file (where N is the rank number), the 'N' should be omitted in input parameter *config\_params* as the new rank number(s) are not allocated until the ranks have been added to the cluster. Each entry in this array corresponds to the entry at the same index in the input parameter *hosts*. This array must either be completely empty or have the same number of elements as the input parameter *hosts*.  An empty input parameter *config\_params* array will result in the new ranks being set with default parameters.
</ParamField>

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

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

  <Expandable title="options">
    <ParamField body="dry_run">
      If *true*, only validation checks will be performed. No ranks are added.

      The default value is `false`.

      The supported values are:

      * true
      * false
    </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\_add\_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/add/ranks endpoint:

  <Expandable title="data_str">
    <ResponseField name="added_ranks" type="array of strings">
      The number assigned to each added rank, formatted as 'rankN', in the same order as the ranks in input parameter *hosts* and input parameter *config\_params*.
    </ResponseField>

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

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