1.3.9. /db/_shards — Apache CouchDB® 3.2 Documentation

# 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.