Working with versions

What is a version?

In ProvenDB, a version is a unique state of the database. The version number increments every time an update, insert or delete completes. You can read more about versions here.

Getting and setting versions

The getVersion command tells you what version is currently in effect. By default, the "current" version is always set:

JavaScript

Mongo Shell>db.runCommand({getVersion:1});
{
	"ok" : 1,
	"response" : "The version is set to: 'current'",
	"version" : NumberLong(36496),
	"status" : "current"
}

setVersion sets the active version. You can set it to 'current', to a specific version number or to a date. For instance in the example below we insert some data, then go back to the version before the version was inserted and confirm that the data does not exist:

JavaScript

Mongo Shell>// Get the current version number 
Mongo Shell>var version1=db.runCommand({getVersion:1}).version;
Mongo Shell>// Insert some data
Mongo Shell>db.myCollection.insert({name:'Guy'});
WriteResult({ "nInserted" : 1 })
Mongo Shell>// Go back to the version before 
Mongo Shell>db.runCommand({setVersion:version1});
{
	"ok" : 1,
	"response" : "The version has been set to: '36496'",
	"version" : NumberLong(36496),
	"status" : "userDefined"
}
Mongo Shell>// See that the data is not there 
Shell>db.myCollection.find({name:'Guy'}).count();
0

Restrictions on versions

You can issue any queries - finds and aggregates in older versions, but you can't modify an older version. If you try and update a collection when you've used a non current version you will get an error:

JavaScript

dbKoda Mongo Shell>db.myCollection.insert({name:'Eliot'});
WriteCommandError({
	"ok" : 0,
	"n" : 0,
	"writeErrors" : [
		{
			"index" : 0,
			"code" : 50000,
			"errmsg" : "Session not current"
		}
	]
})

It is necessary to issue a setVersion with the 'current' argument in order to perform modifications:

JavaScript

Mongo Shell>db.runCommand({setVersion:'current'});
{
	"ok" : 1,
	"response" : "The version has been set to: 'current'",
	"version" : NumberLong(36497),
	"status" : "current"
}
Mongo Shell>db.myCollection.insert({name:'Eliot'});
WriteResult({ "nInserted" : 1 })

Listing versions

listVersions can be used to obtain information about versions. By default it lists the last 10 versions. startDate and endDate may be used to filter versions by date range and limit and sortDirection control the number of versions returns and the sorting of those versions. A typical use would be to determine the version number active at a point in time.

For instance, below we determine the version number in effect this time yesterday:

JavaScript

mongo shell> var yesterday=new Date((new Date())-(24*3600*1000))
mongo shell> db.runCommand({listVersions:{endDate:yesterday,limit:1,sortDirection:-1}});
{
	"ok" : 1,
	"versions" : [
		{
			"version" : NumberLong(5046),
			"status" : "Ended",
			"effectiveDate" : ISODate("2019-03-19T05:52:39Z")
		}
	]
}

Working with versions of a document.

Individual documents will have multiple versions as they are updated. The docHistory command allows you to retrieve these. For instance, the following example returns all versions of the document that contains the string 'Last Will and Testement' in the name attribute and returns just the name and uploadedAt attributes for each document.

JavaScript

Mongo Shell>db.runCommand({docHistory:{
...    collection:'files_5c6b4735769348aee6f8fd00' ,
...    filter:{name:{$regex:"Last Will and Testement"}},
...    projection:{name:1,uploadedAt:1}
... }})
{
	"ok" : 1,
	"docHistory" : [
		{
			"collection" : "files_5c6b4735769348aee6f8fd00",
			"_id" : ObjectId("5c7f46eebe1e3eaea78b1abe"),
			"history" : {
				"versions" : [
					{
						"minVersion" : NumberLong(2),
						"maxVersion" : NumberLong(5),
						"status" : "Valid",
						"started" : "2019-03-06 03:05:02",
						"ended" : "2019-03-06 03:05:03",
						"document" : {
							"name" : "Last Will and Testement of John ProvenDocs.pdf",
							"uploadedAt" : "2019-03-06T04:05:02.765Z"
						}
					},
					{
						"minVersion" : NumberLong(6),
						"maxVersion" : NumberLong("9223372036854775807"),
						"status" : "Valid",
						"started" : "2019-03-06 03:13:27",
						"ended" : "2019-03-06 03:13:27",
						"document" : {
							"name" : "Last Will and Testement of John ProvenDocs.pdf",
							"uploadedAt" : "2019-03-06T04:13:27.562Z"
						}
					}
				]
			}
		}
	]
}