{
  "id": "optimize_shards_placement",
  "title": "Optimize shards placement database action requests",
  "url": "https://redis.io/docs/latest/operate/rs/7.8/references/rest-api/requests/bdbs/actions/optimize_shards_placement/",
  "summary": "Optimize shard placement requests",
  "content": "\n| Method | Path | Description |\n|--------|------|-------------|\n| [GET](#get-bdbs-actions-optimize-shards-placement) | `/v1/bdbs/{uid}/actions/optimize_shards_placement` | Get optimized shards placement for a database  |\n\n\n## Get optimized shards placement {#get-bdbs-actions-optimize-shards-placement}\n\n```sh\nGET /v1/bdbs/{int: uid}/actions/optimize_shards_placement\n```\n\nGet optimized shards placement for the given database.\n\n#### Required permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [view_bdb_info]() | admin\u003cbr /\u003ecluster_member\u003cbr /\u003ecluster_viewer\u003cbr /\u003edb_member\u003cbr /\u003edb_viewer\u003cbr /\u003euser_manager |\n\n### Request {#get-request}\n\n#### Example HTTP request\n\n```sh\nGET /v1/bdbs/1/actions/optimize_shards_placement\n```\n\n#### Query parameters\n\nInclude 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.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| 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`) |\n| memory_size | integer (default:\u0026nbsp;0) | Database memory limit (0 is unlimited), expressed in bytes |\n| shards_count | integer, \u003cnobr\u003e(range: 1-512)\u003c/nobr\u003e (default:\u0026nbsp;1) | Number of database server-side shards |\n| shards_placement | `dense` \u003cbr /\u003e`sparse` | Control the density of shards \u003cbr /\u003e `dense`: Shards reside on as few nodes as possible \u003cbr /\u003e `sparse`: Shards reside on as many nodes as possible |\n| bigstore_ram_size | integer (default:\u0026nbsp;0) | Memory size of bigstore RAM part, expressed in bytes |\n| replication | `enabled`\u003cbr /\u003e`disabled` | In-memory database replication mode |\n\nThe following example request includes `shards_count` and `memory_size` as query parameters:\n\n```sh\nGET /v1/bdbs/1/actions/optimize_shards_placement?shards_count=10\u0026memory_size=10000\n```\n\n### Response {#get-response}\n\nTo rearrange the database shards, you can submit the blueprint returned in this response body as the `shards_blueprint` field in the [`PUT`\u0026nbsp;`/v1/bdbs/{uid}`](#put-bdbs-rearrange-shards) request.\n\n#### Example JSON body\n\n```json\n[\n    {\n        \"nodes\": [\n            {\n                \"node_uid\": \"3\",\n                \"role\": \"master\"\n            },\n            {\n                \"node_uid\": \"1\",\n                \"role\": \"slave\"\n            }\n        ],\n        \"slot_range\": \"5461-10922\"\n    },\n    {\n        \"nodes\": [\n            {\n                \"node_uid\": \"3\",\n                \"role\": \"master\"\n            },\n            {\n                \"node_uid\": \"1\",\n                \"role\": \"slave\"\n            }\n        ],\n        \"slot_range\": \"10923-16383\"\n    },\n    {\n        \"nodes\": [\n            {\n                \"node_uid\": \"3\",\n                \"role\": \"master\"\n            },\n            {\n                \"node_uid\": \"1\",\n                \"role\": \"slave\"\n            }\n        ],\n        \"slot_range\": \"0-5460\"\n    }\n]\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Content-Length | 352 | Length of the request body in octets |\n| cluster-state-id | 30 | Cluster state ID |\n\n#### Status codes {#get-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |\n| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database UID does not exist |\n| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not enough resources in the cluster to host the database |\n\n## Rearrange database shards {#put-bdbs-rearrange-shards}\n\nUse the blueprint returned by the [`GET`\u0026nbsp;`/v1/bdbs/{uid}/actions/optimize_shards_placement`]() request as the value of the `shards_blueprint` field to rearrange the database shards.\n\nTo 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`\u0026nbsp;`/v1/bdbs/{uid}`]() request headers.\n\nThe cluster will reject the update if its state was changed since the optimal shards placement was obtained.\n\n### Request\n\n#### Example HTTP request\n\n```sh\nPUT /v1/bdbs/1\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n| cluster-state-id | 30 | Cluster state ID |\n\n#### Example JSON body\n\n```json\n{\n  \"shards_blueprint\": [\n    {\n      \"nodes\": [\n        {\n          \"node_uid\": \"2\",\n          \"role\": \"master\"\n        }\n      ],\n      \"slot_range\": \"0-8191\"\n    },\n    \"...\"\n  ]\n}\n```\n\n\nIf you submit such an optimized blueprint, it may cause strain on the cluster and its resources. Use with caution.\n\n",
  "tags": ["docs","operate","rs"],
  "last_updated": "2026-04-01T08:10:08-05:00"
}