Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Manage Backup Service Threads

    • Couchbase Server 7.6.2
    March 23, 2025
    + 12
    You can change the number of threads a Backup Service node uses when backing up data.

    HTTP Methods and URIs

    Get all overrides to the thread Backup Service settings
    uri
    Copy
    GET /api/v1/nodesThreadsMap
    Overwrite all thread settings with new values
    uri
    Copy
    POST /api/v1/nodesThreadsMap
    Update some thread settings
    uri
    Copy
    PATCH /api/v1/nodesThreadsMap

    Description

    The nodesThreadMap endpoint lets you change the number of threads the Backup Service uses on a node. The default number of threads the Backup Service uses is based on the number of CPU cores in the node: max(1,cpu_cores×0.75). The number of threads also sets the number of concurrent client connections the service uses to retrieve data from nodes in the cluster. Each thread creates one connection. See Thread Usage for more information about how the number of threads affects the Backup Service.

    Curl Syntax

    Get the current thread overrides
    console
    Copy
    curl -u $USER:$PASSWORD -X GET \
     http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/nodesThreads
    Overwrite all thread settings
    console
    Copy
     curl -u Administrator:password -X POST \
      http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/nodesThreadsMap \
      -d <nodes_thread_map>
    Update/set some thread settings
    console
    Copy
     curl -u Administrator:password -X PATCH \
      http://$BACKUP_SERVICE_NODE:$BACKUP_SERVICE_PORT/api/v1/nodesThreadsMap \
      -d <nodes_thread_map>
    Table 1. POST Parameters
    Name Description Schema

    nodes_thread_map

    An object that sets the number of threads for Backup Service nodes. When you use the PATCH method, the changes only apply to the nodes in the map. Any existing settings that are not in the map remain in effect. Calling POST, removes any existing overrides. After the call, only the overrides you supply in the map are in effect.

    Node Threads Map
    Node Thread Map Schema
    json
    Copy
    {"nodes_threads_map": {
    <backup_node_uuid>:<threads>, . . .
    }
}
    Name Description Schema

    backup_node_uuid

    The unique identifier for a node running the Backup Service. You can get this value from the /pools/nodes REST API. See Getting Information on Nodes.

    string

    threads

    The number of threads for the Backup Service to use.

    When set to 0, the Backup Service uses the default number of threads based on the number of CPU cores in the node: max(1,cpu_cores×0.75).

    integer

    Responses

    Value Description

    200 OK

    Successful calls to POST and PATCH just return the response code.

    When calling the GET method, you receive a JSON object mapping the node UUIDs to thread values. See Examples for details.

    403 Forbidden

    User does not have the proper permission to call the API endpoint.

    In addition, the call returns a JSON object similar to the following:

    json
    Copy
    {
  "message": "Forbidden. User needs one of the following permissions",
  "permissions": [
    "ro_admin"
  ]
}

    404 Not Found

    The resource was not found.

    If you call the GET method before you have created a nodes threads map by calling POST or PATCH, you also receive the following JSON message:

    json
    Copy
    {
    "status":404,
    "msg":"Could not find the Nodes Threads Map",
    "extras":"element not found"
}

    Required Permissions

    • GET: Full Admin, Backup Full Admin, Read-Only Admin

    • POST and PATCH: Full Admin, Backup Full Admin

    Examples

    Set a backup service node to use a single thread, overwriting any existing overrides
    console
    Copy
    curl -s -u Administrator:password -X \
     POST http://localhost:8097/api/v1/nodesThreadsMap \
     -d '{"nodes_threads_map":{"cb5c77719df4f33131251afdca00531a":1}}'
    Get the thread settings
    console
    Copy
    curl -s -u Administrator:password -X \
     GET http://node3:8097/api/v1/nodesThreadsMap | jq

    The previous example returns output similar to the following:

    json
    Copy
    {
  "cb5c77719df4f33131251afdca00531a": 1
}

    See Also

    • For a an overview of the Backup Service, see Backup Service.

    • For a step-by-step guide to configure and use the Backup Service using the Couchbase Server Web Console, see Manage Backup and Restore.

    • See Thread Usage for more information about how the number of threads affects the Backup Service.