Method Path Description
GET /v1/bdbs/{uid}/actions/optimize_shards_placement Get optimized shards placement for a database

Get optimized shards placement

GET /v1/bdbs/{int: uid}/actions/optimize_shards_placement

Get optimized shards placement for the given database.

Required permissions

Permission name Roles
view_bdb_info admin
cluster_member
cluster_viewer
db_member
db_viewer

Request

Example HTTP request

GET /bdbs/1/actions/optimize_shards_placement

Query parameters

Include query parameters in a GET request to generate an optimized shard placement blueprint for a database, using settings that are different from the database’s current configuration.

Field Type Description
avoid_nodes list of integers Comma-separated list of cluster node IDs to avoid when placing the database’s shards and binding its endpoints (for example, avoid_nodes=1,2)
memory_size integer (default: 0) Database memory limit (0 is unlimited), expressed in bytes
shards_count integer, (range: 1-512) (default: 1) Number of database server-side shards
shards_placement dense
sparse
Control the density of shards
dense: Shards reside on as few nodes as possible
sparse: Shards reside on as many nodes as possible
bigstore_ram_size integer (default: 0) Memory size of bigstore RAM part, expressed in bytes

The following example request includes shards_count and memory_size as query parameters:

GET /bdbs/1/actions/optimize_shards_placement?shards_count=10&memory_size=10000

Response

To rearrange the database shards, you can submit the blueprint returned in this response body as the shards_blueprint field in the PUT /bdbs/{uid} request.

Example JSON body

[
    {
        "nodes": [
            {
                "node_uid": "3",
                "role": "master"
            },
            {
                "node_uid": "1",
                "role": "slave"
            }
        ],
        "slot_range": "5461-10922"
    },
    {
        "nodes": [
            {
                "node_uid": "3",
                "role": "master"
            },
            {
                "node_uid": "1",
                "role": "slave"
            }
        ],
        "slot_range": "10923-16383"
    },
    {
        "nodes": [
            {
                "node_uid": "3",
                "role": "master"
            },
            {
                "node_uid": "1",
                "role": "slave"
            }
        ],
        "slot_range": "0-5460"
    }
]

Headers

Key Value Description
Content-Length 352 Length of the request body in octets
cluster-state-id 30 Cluster state ID

Status codes

Code Description
200 OK No error
404 Not Found Database UID does not exist
406 Not Acceptable Not enough resources in the cluster to host the database

Rearrange database shards

Use the blueprint returned by the GET /bdbs/{uid}/actions/optimize_shards_placement request as the value of the shards_blueprint field to rearrange the database shards.

To ensure that the optimized shard placement is relevant for the current cluster state, pass the cluster-state-id, taken from the response header of the GET request, in the PUT /bdbs/{uid} request headers.

The cluster will reject the update if its state was changed since the optimal shards placement was obtained.

Request

Example HTTP request

PUT /bdbs/1

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type
cluster-state-id 30 Cluster state ID

Example JSON body

{
  "shards_blueprint": [
    {
      "nodes": [
        {
          "node_uid": "2",
          "role": "master"
        }
      ],
      "slot_range": "0-8191"
    },
    "..."
  ]
}
Warning -
If you submit such an optimized blueprint, it may cause strain on the cluster and its resources. Use with caution.