A newer version of this documentation is available.

View Latest

Examine Backed-Up Data

      +
      The Backup Service REST API allows the examination of instances of a specified document, within a subset of backups from a specified active, imported, or archived repository.

      HTTP Method and URI

      POST /cluster/self/repository/< "active" | "imported" | "archived" >/<repository-id>/examine

      Description

      Retrieves instances of a document from a subset of backups within a repository. The repository can be active, imported, or archived. The document-key and bucket (optionally with scope and collection) must be specified as a JSON payload.

      Curl Syntax

      curl -X POST http://<backup-node-ip-address-or-domain-name>:8097/cluster/self\
      /repository/< "active" | "imported" | "archived" >/<repository-id>/examine \
        -u <username>:<password>
        -d <document-search-specification>

      The username and password must identify an administrator with the Full Admin role. The repository-id must be the name of a repository that is active, imported, or archived, depending on the specification made by the preceding path-parameter. The document-search-specification must be a JSON document that specifies the following:

      • The key of a document.

      • A data path. The bucket, scope, and collection within which the document resides. The names must be specified in order of containment, period-separated: for example, travel-sample._default._default.

      Syntactically therefore, the document-search-specification should be as follows:

      {
        "key": <document-key>,
        "data_path": < bucket-name.scope-name.collection-name >
      }

      Responses

      If successful, the call returns 200 OK, and a series of documents, each being a backed up instance of that sought for by its key. If the specified repository cannot be found, 404 Object No Found is returned. If an internal error prevents successful execution, 500 is returned. Failure to authenticate returns 401 Unauthorized. An incorrectly specified URI returns 404 Object Not Found.

      Example

      The following example is used to examine instances of the document whose key is airline_10, within the default scope and collection of the travel-sample bucket, in the active repository hourlyBackupRepo.

      curl -v -X POST http://127.0.0.1:8097/api/v1/cluster/self/\
      repository/active/hourlyBackupRepo/examine \
      -u Administrator:password \
      -d '{"key": "airline_10","data_path":"travel-sample._default._default"}'

      On success, the call returns the following:

      {
        "backup": "2020-09-11T16_30_10.894277+01_00",
        "sequence_number": 500,
        "key": "airline_10",
        "value": {
          "callsign": "MILE-AIR",
          "country": "United States",
          "iata": "Q5",
          "icao": "MLA",
          "id": 10,
          "name": "40-Mile Air",
          "type": "airline"
        },
        "metadata": {
          "flags": 33554438,
          "expiry": 0,
          "locktime": 0,
          "cas": 1598358036122239000,
          "revseqno": 2,
          "datatype": 3
        },
        "deleted": false
      }
      {
        "backup": "2020-09-14T17_00_55.976325+01_00",
        "sequence_number": 501,
        "key": "airline_10",
        "value": {
          "callsign": "MILE-AIR",
          "country": "United States",
          "iata": "Q6",
          "icao": "MLA",
          "id": 11,
          "name": "40-Mile Air",
          "type": "airline"
        },
        "metadata": {
          "flags": 33554438,
          "expiry": 0,
          "locktime": 0,
          "cas": 1600097937324376000,
          "revseqno": 3,
          "datatype": 3
        },
        "deleted": false
      }

      Thus, each object returns contains the id of the backup within which the document-instance resides, the sequence number of the document-instance, and the data and metadata values of the instance.

      See Also

      An overview of the Backup Service is provided in Backup Service. A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in Manage Backup and Restore.