forget

Removes data from a document without destroying any blockchain proofs

Definition

forget "forgets" one or more documents by erasing all user data, but preserving hashes so that proofs are retained.

The forget command has the following form:

{
  "forget": {
      "prepare" : <document>,
      "execute" : <document>
  }
}

The command excepts the following fields:

FieldTypeMandatoryDescription
preparedocumentyesThe prepare document identifies the documents that will be forgotten and creates an entry in the _provendb_forgetRequests collection. It returns a summary of the documents that will be affected, and a password that must be supplied in the following request. See Prepare.
executedocumentyesThe execute document deletes the documents concerned. The user must specify the password from the previous prepare operation. See Execute.

📘

Note

Either prepare or execute must exist in the command, but not both.

Prepare Definition

The forget command in prepare mode has the following form:

{
   "forget": {
        "prepare": {
            "collection": <string> ,
            "filter": <document>,
            "minVersion": <number>,
            "maxVersion": <number>,
            "inclusiveRange": <boolean>
        }
    }
}

The command excepts the following fields:

FieldTypeMandatoryDescription
collectionstringyesThe collection name which the documents belongs to.
filterdocumentyesA filter identifying the documents to be forgotten
minVersionnumbernoIf specified, only purge the documents that are current within minVersion and maxVersion.
maxVersionnumbernoIf specified, only purge the documents that are current within minVersion and maxVersion.
inclusiveRangebooleannoIf true, only forget documents that are within the range of versions ONLY. This means that any version outside of the range is unaffected. If false, then documents within the range will be forgotten even if they also exist in versions outside of the range. Default is true.
destroyExistingProofsbooleannoIf true allow a forget operation to invalidate existing proofs. Only collection level proofs with filter conditions might be invalidated by a forget, but if this is possible, the forget will fail unless this flag is set.

Execute Definition

The forget command in execute mode has the following form:

 {
    "forget" :  {
            "execute" : {
                "forgetId": <number>,
                "password": <string>
           }
    }
}

The command excepts the following fields:

FieldTypeMandatoryDescription
forgetIdnumberyesThe identifier returned by the prepare operation.
passwordstringyesThe password returned by the prepare operation.

Output

Prepare Output

The returned document in prepare mode contains a subset of the following fields:

FieldTypeDescription
oknumberThe status of the command.
forgetIdnumberThe identifier of the request. This is a primary key into the _provendb_forgetRequests collection.
passwordstringA password used in the execute stage.
forgetSummarydocumentA document containing the number of documents that will be forgotten and the number of versions affected.

Execute Output

The returned document in execute mode contains a subset of the following fields:

FieldTypeDescription
oknumberThe status of the command.
forgetSummarydocumentA document containing the number of documents that were forgotten and the number of versions affected.

Version Ranges

By default, the version range includes all documents that exist within the two versions specified. This may include documents that exist in subsequent versions. For instance a document created in version 19 and "deleted" (eg capped) in version 21 would be included in the range [10,20]. This means that by default versions outside the version range may be affected.

If the inclusiveRange flag is set, only documents that exist within the two ranges ONLY are affected. In this case a document created in version 19 and deleted in version 21 would not be forgotten by a range condition of [10,20].

Transactional Behavior

There is no rollback available for forget operations. Each document is forgotten independently. A failure to forget all documents will leave the entry in the _provendb_forgetRequests to failed (in the event of some unanticipated error) or incomplete (if a null hash is encountered).

Forget takes out a collection level read lock for the duration of its execution.

Invalidation of proofs

If a proof is created that has a filter condition, and then a forget is executed that includes any documents matching that filter, then the forget will invalidate the proof. This is because provenDB can no longer identify which documents were included in the proof - since it's no longer possible to identify the documents that matched the initial filter.

So, if you create a proof like this:

db.runCommand({submitProof: version,  
  collections: collectionName,  
  filter: {  
    name: 'Guy'  
  },  
  nChecks: 0  
});

Then execute a forget like this:

db.runCommand({  
  forget: {  
    prepare: {  
      collection: collectionName,  
      filter: {  
        name: 'Guy'  
      }  
    }  
  }  
});

You need to supply the destroyExistingProofs: true argument when executing the forget. If do you force the forget, then try to validate the proof, it fails:

{  
  ok: 1,  
  version: Long("38718"),  
  dateTime: ISODate("2023-12-12T23:18:54.004Z"),  
  hash: '89b98a177eb67c68860f4ea7f05b67fdc71195e29a2671383db9077c498c3dca',  
  proofId: '1ad65e7c-d7c8-42fb-bda6-72e0359bfb67',  
  proofStatus: 'Invalid'  
}

Example

The following example prepares and executes a forget operation for documents in the collection 'files_5c6b4735769348aee6f8fd00' where name starts with "Last Will" and ends with ".docx":

// Prepare to forget
> db.runCommand({
...   forget: {
...     prepare: {
...       collection: 'files_5c6b4735769348aee6f8fd00',
...       filter: { name: { $regex: '^Last Will(.*).docx$' } }
...     }
...   }
... });
{
	"ok" : 1,
	"forgetId" : NumberLong(6),
	"password" : "ef230d48-7de7-45f2-8aaf-3fa626f19d15",
	"forgetSummary" : {
		"documentsToBeForgotten" : NumberLong(1),
		"uniqueDocuments" : NumberLong(1)
	}
}
// Execute the forget
mongo>db.runCommand({
...   forget: {
...     execute: { forgetId: 5, password: 'f4b77b8a-3f91-442e-88e7-3c944225ebaf' }
...   }
... });
{
	"ok" : 1,
	"status" : "Complete",
	"forgetSummary" : {
		"documentsForgotten" : NumberLong(1),
		"uniqueDocuments" : NumberLong(1)
	}
}```
 

What’s Next