Version:

/admin/add/ranks

URL: http://GPUDB_IP_ADDRESS:GPUDB_PORT/admin/add/ranks

Add one or more new ranks to the Kinetica cluster. The new ranks will not contain any data initially, other than replicated tables, and not be assigned any shards. To rebalance data across the cluster, which includes shifting some shard key assignments to newly added ranks, see /admin/rebalance.

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.

Input Parameter Description

Name Type Description
hosts array of strings The IP address of each rank being added to the cluster. Insert one entry per rank, even if they are on the same host. The order of the hosts in the array only matters as it relates to the input parameter config_params.
config_params array of maps of string to strings Configuration parameters to apply to the new ranks, e.g., which GPU to use. Configuration parameters that start with 'rankN.', where N is the rank number, should omit the N, as the new rank number(s) are not allocated until the ranks are created. Each entry in this array corresponds to the entry at the same array index in the input parameter hosts. This array must either be completely empty or have the same number of elements as the hosts array. An empty array will result in the new ranks being set only with default parameters.
options map of string to strings

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

Supported Parameters (keys) Parameter Description
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

Output Parameter Description

The GPUdb 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:

Name Type Description
status String 'OK' or 'ERROR'
message String Empty if success or an error message
data_type String 'admin_add_ranks_request' or 'none' in case of an error
data String Empty string
data_str JSON or String

This embedded JSON represents the result of the /admin/add/ranks endpoint:

Name Type Description
added_ranks array of ints The number assigned to each newly added rank, in the same order as the ranks in the input parameter hosts. Will be empty if the operation fails.
results array of strings Text description of the result of each rank being added. Indicates the reason for any errors that occur. Entries are in the same order as the input parameter hosts.
info map of string to strings Additional information.

Empty string in case of an error.