docHistory

Retrieves complete histories for one or more documents

Definition

The docHistory command returns all versions of specified documents.

The docHistory command has the following form:

{
  "docHistory":
    {
      "collection": <string>,
      "filter":<document>,
      "projection":<document>
    }
 }

The command accepts the following fields:

FieldTypeMandatoryDescription
docHistory.collectionstringyesThe target collection
docHistory.filterdocumentyesA MongoDB compatible filter condition
docHistory.projectiondocumentnoA MongoDB compatible projection document

Output

The returned document contains a subset of the following fields:

FieldTypeDescription
oknumberThe status of the command.
docHistoryarrayAn array of DocHistory Item's.

DocHistory Item

FieldTypeDescription
collectionstringThe collection which contains the document.
_idanyThe document id.
historydocumentThe document's history.
history.versionsarrayAn array of DocHistory Version's.

DocHistory Version

FieldTypeDescription
minVersionnumberThe version the document started.
maxVersionnumberThe version the document ended.
statusstringThe proof status of the document.
startedtimestampThe timestamp when the version started.
endedtimestampThe timestamp when the version ended.
documentdocumentThe document content.

Example

This example returns all versions of the document that contains the string 'Last Will and Testament' in the name attribute and returns just the name and uploadedAt attributes for each document.

> db.runCommand({docHistory:{
...    collection:'files_5c6b4735769348aee6f8fd00' ,
...    filter:{name:{$regex:"Last Will and Testament"}},
...    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 Testament 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"
                        }
                    }
                ]
            }
        }
    ]
}

πŸ“˜

Note:

docHistory will return an error if the amount of data returned exceeds the maximum network message size of approximately 64MB. If you encounter this error, you should use either the filter or projection clauses to reduce the amount of data returned.

You can use a projection to reduce the amount of document data returned. For instance, here we suppress all document data using a projection on a non-existent attribute:

db.runCommand({
  docHistory: { collection: collectionName, filter: { X 4 },
                      projection:{nonExistentAttribute:1} }}

If you really need to extract all versions of large documents you can do so using normal queries. If a filter condition is specified on provendb metadata attributes, then these will over-ride the implicit 'current version' filter. So for instance, this query will return all versions of the documents which has an _id of 4, and will return the metadata as well as the user data:

collection.find({'_provendb_metadata':{$exists:true},'_id':4},
                          {'_provendb_metadata':1});

What’s Next