{
  "schema_version": 2,
  "id": "operate/rs/references/rest-api/requests/bdbs/actions/optimize_shards_placement",
  "title": "Optimize shards placement database action requests",
  "url": "https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs/actions/optimize_shards_placement/",
  "summary": "Optimize shard placement requests",
  "tags": [
    "docs",
    "operate",
    "rs"
  ],
  "last_updated": "2026-10-05T16:11:44+01:00",
  "page_type": "content",
  "content_hash": "767218513e68a9e2233d5fbf0a53aafd245fb05c2e22d5352f96f3735d2ff075",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "This REST API path is deprecated as of Redis Software version 7.22. Use [`PUT /v1/bdbs/<uid>/actions/revamp?dry_run=true`](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs/actions/revamp/#put-bdbs-actions-revamp) instead.\n\n\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  |"
    },
    {
      "id": "get-bdbs-actions-optimize-shards-placement",
      "title": "Get optimized shards placement",
      "role": "content",
      "text": "[code example]\n\nGet optimized shards placement for the given database.\n\n#### Required permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [view_bdb_info](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_bdb_info) | admin<br />cluster_member<br />cluster_viewer<br />db_member<br />db_viewer<br />user_manager |"
    },
    {
      "id": "get-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\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:&nbsp;0) | Database memory limit (0 is unlimited), expressed in bytes |\n| shards_count | integer, <nobr>(range: 1-512)</nobr> (default:&nbsp;1) | Number of database server-side shards |\n| shards_placement | `dense` <br />`sparse` | Control the density of shards <br /> `dense`: Shards reside on as few nodes as possible <br /> `sparse`: Shards reside on as many nodes as possible |\n| bigstore_ram_size | integer (default:&nbsp;0) | Memory size of bigstore RAM part, expressed in bytes |\n| replication | `enabled`<br />`disabled` | In-memory database replication mode |\n\nThe following example request includes `shards_count` and `memory_size` as query parameters:\n\n[code example]"
    },
    {
      "id": "get-response",
      "title": "Response",
      "role": "returns",
      "text": "To rearrange the database shards, you can submit the blueprint returned in this response body as the `shards_blueprint` field in the [`PUT`&nbsp;`/v1/bdbs/{uid}`](#put-bdbs-rearrange-shards) request.\n\n#### Example JSON body\n\n[code example]\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 |"
    },
    {
      "id": "put-bdbs-rearrange-shards",
      "title": "Rearrange database shards",
      "role": "content",
      "text": "Use the blueprint returned by the [`GET`&nbsp;`/v1/bdbs/{uid}/actions/optimize_shards_placement`](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs/actions/optimize_shards_placement#get-bdbs-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`&nbsp;`/v1/bdbs/{uid}`](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs#put-bdbs) request headers.\n\nThe cluster will reject the update if its state was changed since the optimal shards placement was obtained."
    },
    {
      "id": "request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\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[code example]\n\n> [!WARNING]\n> If you submit such an optimized blueprint, it may cause strain on the cluster and its resources. Use with caution."
    }
  ],
  "examples": [
    {
      "id": "get-bdbs-actions-optimize-shards-placement-ex0",
      "language": "sh",
      "code": "GET /v1/bdbs/{int: uid}/actions/optimize_shards_placement",
      "section_id": "get-bdbs-actions-optimize-shards-placement"
    },
    {
      "id": "get-request-ex0",
      "language": "sh",
      "code": "GET /v1/bdbs/1/actions/optimize_shards_placement",
      "section_id": "get-request"
    },
    {
      "id": "get-request-ex1",
      "language": "sh",
      "code": "GET /v1/bdbs/1/actions/optimize_shards_placement?shards_count=10&memory_size=10000",
      "section_id": "get-request"
    },
    {
      "id": "get-response-ex0",
      "language": "json",
      "code": "[\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]",
      "section_id": "get-response"
    },
    {
      "id": "request-ex0",
      "language": "sh",
      "code": "PUT /v1/bdbs/1",
      "section_id": "request"
    },
    {
      "id": "request-ex1",
      "language": "json",
      "code": "{\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}",
      "section_id": "request"
    }
  ]
}