1.3.9. /{db}/_shards — Apache CouchDB® 3.5 Documentation

# 1.3.9. `/{db}/_shards`

Added 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

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 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/{docid}`

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

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

    - 404 Not Found – Database or document not found

    - 500 Internal Server Error – Internal server error or timeout

  Request:

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

  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`

Added 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

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

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