# 1.3.9. `/db/_shards`

New in version 2.0.

`GET` `/{db}/_shards`

  The response will contain a list of database shards. Each shard will have its internal database range, and the nodes on which replicas of those shards are stored.

  Parameters:

  - db – Database name

  Request Headers:

  - Accept –
    - application/json
    - text/plain

  Response Headers:

  - Content-Type –
    - application/json
    - text/plain; charset=utf-8

  Response JSON Object:

  - shards (object) – Mapping of shard ranges to individual shard replicas on each node in the cluster

  Status Codes:

  - 200 OK – Request completed successfully
  - 400 Bad Request – Invalid database name
  - 401 Unauthorized – Read privilege required
  - 415 Unsupported Media Type – Bad Content-Type value
  - 500 Internal Server Error – Internal server error or timeout

  Request:

      GET /db/_shards HTTP/1.1
      Accept: */*
      Host: localhost:5984

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 621
      Content-Type: application/json
      Date: Fri, 18 Jan 2019 19:55:14 GMT
      Server: CouchDB/2.4.0 (Erlang OTP/19)

      {
        "shards": {
          "00000000-1fffffff": [
            "couchdb@node1.example.com",
            "couchdb@node2.example.com",
            "couchdb@node3.example.com"
          ],
          "20000000-3fffffff": [
            "couchdb@node1.example.com",
            "couchdb@node2.example.com",
            "couchdb@node3.example.com"
          ],
          "40000000-5fffffff": [
            "couchdb@node1.example.com",
            "couchdb@node2.example.com",
            "couchdb@node3.example.com"
          ],
          "60000000-7fffffff": [
            "couchdb@node1.example.com",
            "couchdb@node2.example.com",
            "couchdb@node3.example.com"
          ],
          "80000000-9fffffff": [
            "couchdb@node1.example.com",
            "couchdb@node2.example.com",
            "couchdb@node3.example.com"
          ],
          "a0000000-bfffffff": [
            "couchdb@node1.example.com",
            "couchdb@node2.example.com",
            "couchdb@node3.example.com"
          ],
          "c0000000-dfffffff": [
            "couchdb@node1.example.com",
            "couchdb@node2.example.com",
            "couchdb@node3.example.com"
          ],
          "e0000000-ffffffff": [
            "couchdb@node1.example.com",
            "couchdb@node2.example.com",
            "couchdb@node3.example.com"
          ]
        }
      }

# 1.3.10. `/db/_shards/doc`

`GET` `/{db}/_shards/{docid}`

  Returns information about the specific shard into which a given document has been stored, along with information about the nodes on which that shard has a replica.

  Parameters:

  - db – Database name
  - docid – Document ID

  Request Headers:

  - Accept –
    - application/json
    - text/plain

  Response Headers:

  - Content-Type –
    - application/json
    - text/plain; charset=utf-8

  Response JSON Object:

  - range (string) – The shard range in which the document is stored
  - nodes (array) – List of nodes serving a replica of the shard

  Status Codes:

  - 200 OK – Request completed successfully
  - 401 Unauthorized – Read privilege required
  - 404 Not Found – Database or document not found
  - 500 Internal Server Error – Internal server error or timeout

  Request:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 94
      Content-Type: application/json
      Date: Fri, 18 Jan 2019 20:08:07 GMT
      Server: CouchDB/2.3.0-9d4cb03c2 (Erlang OTP/19)

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 94
      Content-Type: application/json
      Date: Fri, 18 Jan 2019 20:26:33 GMT
      Server: CouchDB/2.3.0-9d4cb03c2 (Erlang OTP/19)

      {
        "range": "e0000000-ffffffff",
        "nodes": [
          "node1@127.0.0.1",
          "node2@127.0.0.1",
          "node3@127.0.0.1"
        ]
      }

# 1.3.11. `/db/_sync_shards`

New in version 2.3.1.

`POST` `/{db}/_sync_shards`

  For the given database, force-starts internal shard synchronization for all replicas of all database shards.

  This is typically only used when performing cluster maintenance, such as moving a shard.

  Parameters:

  - db – Database name

  Request Headers:

  - Accept –
    - application/json
    - text/plain

  Response Headers:

  - Content-Type –
    - application/json
    - text/plain; charset=utf-8

  Response JSON Object:

  - ok (boolean) – Operation status. Available in case of success
  - error (string) – Error type. Available if response code is `4xx`
  - reason (string) – Error description. Available if response code is `4xx`

  Status Codes:

  - 202 Accepted – Request accepted
  - 400 Bad Request – Invalid database name
  - 401 Unauthorized – CouchDB Server Administrator privileges required
  - 404 Not Found – Database not found
  - 500 Internal Server Error – Internal server error or timeout

  Request:

      POST /db/_sync_shards HTTP/1.1
      Host: localhost:5984
      Accept: */*

  Response:

      HTTP/1.1 202 Accepted
      Cache-Control: must-revalidate
      Content-Length: 12
      Content-Type: application/json
      Date: Fri, 18 Jan 2019 20:19:23 GMT
      Server: CouchDB/2.3.0-9d4cb03c2 (Erlang OTP/19)
      X-Couch-Request-ID: 14f0b8d252
      X-CouchDB-Body-Time: 0

      {
          "ok": true
      }

Note

Admins may want to bump their `[mem3] sync_concurrency` value to a larger figure for the duration of the shards sync.