Navigation

Update an Online Archive

Beta

Online archive is available as a Beta feature. The feature and the corresponding documentation may change at any time during the Beta stage.

You can pause or resume archiving for an online archive or modify the archiving criteria in an online archive from the API. You can also pause and resume or edit an online archive from the Atlas UI. You must have the GROUP_DATA_ACCESS_ADMIN (Project Data Access Admin) role to update an online archive.

The Atlas API uses HTTP Digest Authentication. Provide a programmatic API public key and corresponding private key as the username and password when constructing the HTTP request.

For complete documentation on configuring API access for an Atlas project, see Configure Atlas API Access.

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

Base URL: https://cloud.mongodb.com/api/atlas/v1.0

Syntax

PATCH /groups/{GROUP-ID}/clusters/{CLUSTER-NAME}/onlineArchives/{ARCHIVE-ID}

Request Parameters

Request Path Parameters

Path Element Necessity Description
GROUP-ID Required Unique identifier of the project that contains the specified cluster.
CLUSTER-NAME Required Name of the cluster that contains the collection whose online archive to update.
ARCHIVE-ID Required Unique identifier of the online archive to update.

Request Query Parameters

The following query parameters are optional:

Query Parameter Type Description Default
pretty boolean Displays response in a prettyprint format. false
envelope boolean Specifies whether or not to wrap the response in an envelope. false

Request Body Parameters

Name Type Necessity Description
criteria object Conditional Criteria to use for archiving data. This is only required for modifying the archiving criteria. Either criteria or paused is required.
criteria.expireAfterDays int Conditional The number of days after which the data in the live Atlas cluster can be archived. Note that data is archived only when the current date is greater than the value of the date field specified via the dateField parameter plus the number of days specified here.
paused boolean Conditional

Pause or resume archiving for the the online archive. Value can be:

  • true - to pause archiving for an active online archive

  • false - to resume archiving for a paused online archive

    Note

    The resume request will fail if the collection has another active online archive.

This is required for pausing an active or resume a paused online archive.

Either paused or criteria is required.

Response Elements

Name Type Description
id string ID of the online archive.
clusterName string Name of the cluster that contains the collection.
collName string Name of the collection.
criteria document Criteria to use for archiving data.
criteria.dateField string Name of the date field that the online archive is based on. Data is archived when the current date is greater than the value of the date field specified here plus the number of days specified via the expireAfterDays parameter.
criteria.expireAfterDays int Number of days that specifies the age limit for the data in the live Atlas cluster. Data is archived when the current date is greater than the value of the date field specified via the dateField parameter plus the number of days specified here.
dbName string Name of the database that contains the collection.
groupId string Unique identifier of the project that contains the cluster.
partitionFields document array Fields to use to partition data.
partitionFields.fieldName string Name of the field.
partitionFields.fieldType string Data type of the field.
partitionFields.order int

Position of the field in the partition. Value can be:

  • 0 - for the first position
  • 1 - for the second position
  • 2 - for the third position
paused boolean

State of the online archive. Value is:

  • true if the online archive is in paused state.
  • false if the online archive is in pending or active state.

Examples

The following example request updates the number of days criteria for an online archive from 5 days to 7 days. The example response contains the updated archiving criteria for the people.employees collection in the cluster named myTestClstr.

Example Request

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Content-Type: application/json" \
--include \
--request PATCH "https://cloud.mongodb.com/api/atlas/v1.0/groups/5e2211c17a3e5a48f5497de3/clusters/myTestClstr/onlineArchives/5ebad3c1fe9c0ab8d37d61e1?pretty=true" \
--data '
  {
          "criteria": {
                "expireAfterDays": 7
  }
}'

Example Response

{
  "_id": "5ebad3c1fe9c0ab8d37d61e1",
  "clusterName": "onlineArchiveSbx",
  "collName": "employees",
  "criteria": {
     "dateField": "startDate",
     "expireAfterDays": 7
  },
  "dbName": "people",
  "groupId": "5e2211c17a3e5a48f5497de3",
  "partitionFields": [
     {
         "fieldName": "firstName",
         "fieldType": "string",
         "order": 0
     },
     {
         "fieldName": "lastName",
         "fieldType": "string",
         "order": 1
     },
     {
         "fieldName": "startDate",
         "fieldType": "date",
         "order": 2
     }
  ],
  "paused": false
}

The following example request pauses archiving for an online archive specified by its ID. The example response contains the updated status of the online archive for the people.employees collection in the cluster named myTestClstr.

Example Request

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Content-Type: application/json" \
--include \
--request PATCH "https://cloud.mongodb.com/api/atlas/v1.0/groups/5e2211c17a3e5a48f5497de3/clusters/myTestClstr/onlineArchives/5ebad3c1fe9c0ab8d37d61e1?pretty=true" \
--data '{ "paused": true }'

Example Response

{
  "_id": "5ebad3c1fe9c0ab8d37d61e1",
  "clusterName": "myTestClstr",
  "collName": "employees",
  "criteria": {
     "dateField": "startDate",
     "expireAfterDays": 7
  },
  "dbName": "people",
  "groupId": "5e2211c17a3e5a48f5497de3",
  "partitionFields": [
     {
         "fieldName": "firstName",
         "fieldType": "string",
         "order": 0
     },
     {
         "fieldName": "lastName",
         "fieldType": "string",
         "order": 1
     },
     {
         "fieldName": "startDate",
         "fieldType": "date",
         "order": 2
     }
  ],
  "paused": true
}

Error Codes

If the request fails, it returns one of the following errors:

Error Code Description
INVALID_GROUP_ID The specified project ID is not valid.
CLUSTER_NOT_FOUND There is no cluster with the specified name in the specified project.
CLUSTER_DELETE_REQUESTED The cluster for the online archive is being deleted.
NAMESPACE_HAS_ONLINE_ARCHIVE The collection has another active online archive and so, the specified online archive can’t be resumed.
RESOURCE_NOT_FOUND The specified archive ID is not valid.