Modified MongoDB commands

Aggregate

The MongoDB aggregate command is implemented with some restrictions.

By default, documents for the currently active version (as set by setVersion ) are returned). To return all documents across versions, add a $match condition on the _provendb_metadata attribute and use showMetadata to allow metadata to be visible. For instance, the following aggregate command returns all documents and their version ranges:

Mongo Shell>db.runCommand({ showMetaData: true });
{ "ok" : 1 }
Mongo Shell>db.tutorial.
...   aggregate([{ $match: { _provendb_metadata: { $exists: true } } }]).
...   pretty();
{
    "_id" : ObjectId("5c8707cda012509300a012c3"),
    "_provendb_metadata" : {
        "_id" : ObjectId("5c8707cda012509300a012c3"),
        "_mongoId" : ObjectId("5c8707cda012509300a012c3"),
        "minVersion" : NumberLong(15430),
        "hash" : "6502450df261b225c877d8657ee4aa7b899333b9b668638fbdbc4b7e9194e2f5",
        "maxVersion" : NumberLong(15430)
    },
    "name" : "Guy",
    "rating" : 10
}
{
    "_id" : ObjectId("5c8707cda012509300a012c4"),
    "_provendb_metadata" : {
        "_id" : ObjectId("5c8707cda012509300a012c4"),
        "_mongoId" : ObjectId("5c8707cda012509300a012c4"),
        "minVersion" : NumberLong(15430),
        "hash" : "3166f2c2ef0a1c56a93cf36236bea5dd8f5335d85293bcc6e870b2aa39b82081",
        "maxVersion" : NumberLong(15430)
    },
    "name" : "Mike",
    "rating" : 9
}
{
    "_id" : ObjectId("5c8707f6a012509300a012c5"),
    "_provendb_metadata" : {
        "_id" : ObjectId("5c8707f6a012509300a012c5"),
        "_mongoId" : ObjectId("5c8707f6a012509300a012c5"),
        "minVersion" : NumberLong(15432),
        "hash" : "0b5015e9e7b76e0a869ce5d94466890405a1d7e7ddc20e36fa3261d5883cfb1a",
        "maxVersion" : NumberLong(15432)
    },
    "name" : "Guy",
    "rating" : 10
}

createIndex

Create index works as for MongoDB.

To ensure that the index is efficient, ProvenDB appends the hidden metadata attribute _provendb_metadata.maxVersion to the index. This allows the index to fetch only documents for a specific version. For instance, the following index command:

Mongo Shell>db.tutorial.createIndex({name:1});
{
    "createdCollectionAutomatically" : false,
    "numIndexesBefore" : 6,
    "numIndexesAfter" : 7,
    "ok" : 1
}

Creates an index as follows:

{
        "v" : 2,
        "key" : {
            "name" : 1,
            "_provendb_metadata.maxVersion" : 1
        },
        "name" : "name_1Max",
        "ns" : "dev_guy01.tutorial"
}

The insertion of the _provendb_metadata.maxVersion attribute can be controlled by the provendb_metadata option. provendb_metadata takes one of the following arguments:

  • "-1": this is the default. the maxVersion attribute is inserted at the end of the requested index keys.
  • "0": the maxVersion attribute is not added to the key list.
  • "1": the maxVersion attribute is added before the requested index keys

For example, an index requested as follows:

db.getSiblingDB('provendbTest')
  .getCollection('collection159375')
  .createIndex(
    {
      myKey: 1
    },
    {
      background: false,
      unique: false,
      sparse: false
    }
  );

Would be translated as follows:

db.getSiblingDB('provendbTest')
  .getCollection('collection159375')
  .createIndex(
    {
      myKey: 1,
      '_provendb_metadata.maxVersion': 1
    },
    {
      background: false,
      unique: false,
      sparse: false
    }
  );

If provendb_metadata is set to 1, as in the following example:

db.getSiblingDB('provendbTest')
  .getCollection('collection159375')
  .createIndex(
    {

      myKey: 1
    },
    {
      background: false,
      unique: false,
      sparse: false,
      provendb_metadata: 1
    }
  );

Then the index would be created as follows:

db.getSiblingDB('provendbTest')
  .getCollection('collection159375')
  .createIndex(
    {
      '_provendb_metadata.maxVersion': 1,
      myKey: 1
    },
    {
      background: false,
      unique: false,
      sparse: false
    }
  );

If provendb_metadata:0 is specified then the index command is issued without modification.

🚧

Note

Create Index commands that work under MongoDB might not work under ProvenDB unless provendb_metadata:0 is specified. Text indexes for instance cannot take multiple arguments.

Drop

The collection drop command in ProvenDB marks all documents as finalised in the current version. It does not remove any data.

Find

Find returns documents for a specific version of the database only. Syntax is identical to normal mongoDB syntax.

By default, find returns only documents from the currently active version as determined by setVersion . However, if the find condition contains references to the _provendb_metadata attributes, then documents for all versions will be returned.

By default, metadata attributes are not returned by find. The showMetadata command will control the display of metadata in find results

Below is an example of a find command which returns data across versions and which displays metadata:

Mongo Shell>db.runCommand({showMetaData:true});
{ "ok" : 1 }
Mongo Shell>db.tutorial.find({'_provendb_metadata':{$exists:true},
...                   name:'Guy'}).pretty();
{
    "_id" : ObjectId("5c8707cda012509300a012c3"),
    "_provendb_metadata" : {
        "_id" : ObjectId("5c8707cda012509300a012c3"),
        "_mongoId" : ObjectId("5c8707cda012509300a012c3"),
        "minVersion" : NumberLong(15430),
        "hash" : "6502450df261b225c877d8657ee4aa7b899333b9b668638fbdbc4b7e9194e2f5",
        "maxVersion" : NumberLong(15430)
    },
    "name" : "Guy",
    "rating" : 10
}
{
    "_id" : ObjectId("5c8707f6a012509300a012c5"),
    "_provendb_metadata" : {
        "_id" : ObjectId("5c8707f6a012509300a012c5"),
        "_mongoId" : ObjectId("5c8707f6a012509300a012c5"),
        "minVersion" : NumberLong(15432),
        "hash" : "0b5015e9e7b76e0a869ce5d94466890405a1d7e7ddc20e36fa3261d5883cfb1a",
        "maxVersion" : NumberLong(15432)
    },
    "name" : "Guy",
    "rating" : 10
}
{
    "_id" : ObjectId("5c8707f6a012509300a012c5"),
    "_provendb_metadata" : {
        "_id" : ObjectId("5c8707f6a012509300a012c5"),
        "_mongoId" : ObjectId("5c8708471ac8ed00084571a0"),
        "minVersion" : NumberLong(15433),
        "hash" : "3d0a79030f179955e637c9231b13e642a47a07e0d5c2f3052192b0018387f044",
        "maxVersion" : NumberLong("9223372036854775807")
    },
    "name" : "Guy",
    "rating" : 11
}

What’s Next