Navigation

Update an Online Archive

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 authenticates using HTTP Digest Authentication. Provide a programmatic API public key and corresponding private key as the username and password when constructing the HTTP request.

To learn how to configure API access for an Atlas project, see Configure Atlas API Access.

Info With Circle IconCreated with Sketch.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.

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

PATCH /groups/{GROUP-ID}/clusters/{CLUSTER-NAME}/onlineArchives/{ARCHIVE-ID}
Path ElementNecessityDescription
GROUP-IDRequiredUnique identifier of the project that contains the specified cluster.
CLUSTER-NAMERequiredName of the cluster that contains the collection whose online archive to update.
ARCHIVE-IDRequiredUnique identifier of the online archive to update.

The following query parameters are optional:

Query ParameterTypeDescriptionDefault
prettybooleanDisplays response in a prettyprint format.false
envelopebooleanSpecifies whether or not to wrap the response in an envelope.false
NameTypeNecessityDescription
criteriaobjectConditionalCriteria to use for archiving data. This is only required for modifying the archiving criteria. Either criteria or paused is required.
criteria.typestringRequired

Type of criteria. Value can be one of the following:

  • DATE - to select documents for archiving based on a date.
  • CUSTOM - to select documents for archiving based on a custom JSON query.
criteria.dateFieldstringConditional

Required if criteria.type is DATE. Immutable.

Name of an already indexed date field from the documents. 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.dateFormatenumConditional

Required if criteria.type is DATE. Immutable.

If criteria.type is DATE, the date format. Value can be one of the following:

  • ISODATE - ISO-8601 format date (default)
  • EPOCH_SECONDS - Unix timestamp in seconds
  • EPOCH_MILLIS - Unix timestamp in milliseconds
  • EPOCH_NANOSECONDS - Unix timestamp in nanoseconds
criteria.expireAfterDaysintConditional

Required if criteria.type is DATE.

The number of days after which the data in the live Atlas cluster can be archived.

criteria.querystringConditional

Required if criteria.type is CUSTOM.

JSON query to use to select documents to archive. Atlas uses the specified query with the db.collection.find(query) command. The empty document {} to return all documents is not supported.

pausedbooleanConditional

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

    Info With Circle IconCreated with Sketch.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.

NameTypeDescription
idstringID of the online archive.
clusterNamestringName of the cluster that contains the collection.
collNamestringName of the collection.
criteriadocumentCriteria to use for archiving data.
criteria.typestring

Type of criteria. Value can be one of the following:

  • DATE - to select documents for archiving based on a date.
  • CUSTOM - to select documents for archiving based on a custom JSON query.
criteria.dateFieldstringIf criteria.type is DATE, name of the date field that the online archive is based on. Data is archived when the current date is after the date specified here plus the number of days specified via the expireAfterDays parameter.
criteria.dateFormatenum

If criteria.type is DATE, the date format. Value can be one of the following:

  • ISODATE - ISO-8601 format date (default)
  • EPOCH_SECONDS - Unix timestamp in seconds
  • EPOCH_MILLIS - Unix timestamp in milliseconds
  • EPOCH_NANOSECONDS - Unix timestamp in nanoseconds
criteria.expireAfterDaysintIf criteria.type is DATE, 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.
criteria.queryintIf criteria.type is CUSTOM, JSON query used to select documents for archiving. The specified query is used with the db.collection.find(query) command.
dbNamestringName of the database that contains the collection.
groupIdstringUnique identifier of the project that contains the cluster.
partitionFieldsdocument arrayFields to use to partition data.
partitionFields.fieldNamestringName of the field.
partitionFields.fieldTypestringData type of the field.
partitionFields.orderint

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
pausedboolean

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

Status of the online archive. Valid values are:

PendingIndicates documents are queued for archive, but archiving has not yet started.
ArchivingIndicates archiving has started. In this state, the documents that meet the criteria for archiving are being archived.
IdleIndicates online archive is waiting for the next archival job to start.
PausedIndicates archiving has been temporarily stopped. In this state, previously archived documents continue to be available on the cloud object storage, but the specified archiving operation on the active cluster is put on hold. You can resume archiving for paused archives at any time.
OrphanedIndicates collection associated with an active or paused online archive was deleted. Atlas will not automatically delete the archived data. You must manually delete the online archives associated with the deleted collection.
DeletedIndicates online archive was deleted. When you delete an online archive, associated archived documents are removed from the cloud object storage.

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.

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": {
"type": "DATE",
"dateField": "startDate",
"dateFormat": "ISODATE",
"expireAfterDays": 7
}
}'
{
"_id": "5ebad3c1fe9c0ab8d37d61e1",
"clusterName": "onlineArchiveSbx",
"collName": "employees",
"criteria": {
"type": "DATE",
"dateField": "startDate",
"dateFormat": "ISODATE",
"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 modifies the custom query used to select documents in the people.employees collection from engineering department to sales and the lastDate field exists. The example response contains the updated archiving criteria for the people.employees collection in the cluster named myTestClstr.

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/5fca93aa94f65a28923fe0ed?pretty=true" \
--data '
{
"criteria": {
"type": "CUSTOM",
"query": "{\"department\":\"sales\", lastDate: { $exists: true }}"
}
}'
{
"_id": "5fca93aa94f65a28923fe0ed",
"clusterName": "myTestClstr",
"collName": "employees",
"criteria": {
"type": "CUSTOM",
"query": "{\"department\":\"sales\", lastDate: { $exists: true }}"
},
"dbName": "people",
"groupId": "5e2211c17a3e5a48f5497de3",
"partitionFields": [
{
"fieldName": "name.firstName",
"fieldType": null,
"order": 0
},
{
"fieldName": "name.lastName",
"fieldType": null,
"order": 1
}
],
"paused": false,
"state": "PENDING"
}

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.

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 }'
{
"_id": "5ebad3c1fe9c0ab8d37d61e1",
"clusterName": "myTestClstr",
"collName": "employees",
"criteria": {
"type": "DATE",
"dateField": "startDate",
"dateFormat": "ISODATE",
"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
}

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

Error CodeDescription
INVALID_GROUP_IDThe specified project ID is not valid.
CLUSTER_NOT_FOUNDThere is no cluster with the specified name in the specified project.
CLUSTER_DELETE_REQUESTEDThe cluster for the online archive is being deleted.
NAMESPACE_HAS_ONLINE_ARCHIVEThe collection has another active online archive and so, the specified online archive can't be resumed.
RESOURCE_NOT_FOUNDThe specified archive ID is not valid.
Give Feedback