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:

JavaScript

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

The command excepts the following fields:

Field	Type	Mandatory	Description
prepare	document	yes	The 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.
execute	document	yes	The 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:

JavaScript

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

The command excepts the following fields:

Field	Type	Mandatory	Description
collection	string	yes	The collection name which the documents belongs to.
filter	document	yes	A filter identifying the documents to be forgotten
minVersion	number	no	If specified, only purge the documents that are current within minVersion and maxVersion.
maxVersion	number	no	If specified, only purge the documents that are current within minVersion and maxVersion.
inclusiveRange	boolean	no	If 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.
destroyExistingProofs	boolean	no	If 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:

JavaScript

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

The command excepts the following fields:

Field	Type	Mandatory	Description
forgetId	number	yes	The identifier returned by the prepare operation.
password	string	yes	The password returned by the prepare operation.

Output

Prepare Output

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

Field	Type	Description
ok	number	The status of the command.
forgetId	number	The identifier of the request. This is a primary key into the _provendb_forgetRequests collection.
password	string	A password used in the execute stage.
forgetSummary	document	A 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:

Field	Type	Description
ok	number	The status of the command.
forgetSummary	document	A 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:

javascript

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

Then execute a forget like this:

JavaScript

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:

JavaScript

{  
  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":

JavaScript

// 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)
	}
}```