GORM for MongoDB

This implementation tries to be as compatible as possible with GORM for Hibernate. In general you can refer to the GORM documentation and the "Domain Classes" section of the reference guide (see the right nav) for usage information.

The following key features are supported by GORM for Mongo:

However, some features are not supported:

There may be other limitations not mentioned here so in general it shouldn’t be expected that an application based on GORM for Hibernate will "just work" without some tweaking involved. Having said that, the large majority of common GORM functionality is supported.

Below are the details of the changes across releases:

To get started with GORM for MongoDB within Grails you need configure it as a dependency in build.gradle:

If you receive an error that indicates a failure to resolve the grails-datastore-simple dependency you may need to add the following to build.gradle directly above the dependencies block:

If you receive an error at runtime such as:

It means you have an older version of the MongoDB Java driver on your classpath and you should add the following declaration to build.gradle to ensure the dependency is correct:

With that done you need to set up a running MongoDB server. Refer to the MongoDB Documentation for an explanation on how to startup a MongoDB instance. Once installed, starting MongoDB is typically a matter of executing the following command:

With the above command executed in a terminal window you should see output like the following appear:

As you can see the server is running on port 27017, but don’t worry the MongoDB plugin for Grails will automatically configure itself to look for MongoDB on that port by default.

If you want to configure how Grails connects to MongoDB then you can do so using the following settings in grails-app/conf/application.yml:

If you plan to use MongoDB as your primary datastore then you need to remove the Hibernate plugin from the build.gradle file by commenting out the hibernate line in the plugins block

With this done all domain classes in grails-app/domain will be persisted via MongoDB and not Hibernate. You can create a domain class by running the regular create-domain-class command:

The Person domain class will automatically be a persistent entity that can be stored in MongoDB.

If you have both the Hibernate and Mongo plugins installed then by default all classes in the grails-app/domain directory will be persisted by Hibernate and not Mongo. If you want to persist a particular domain class with Mongo then you must use the mapWith property in the domain class:

To use GORM for MongoDB in Spring Boot add the necessary dependencies to your Boot application:

Ensure your Boot Application class is annotated with ComponentScan, example:

Finally create your GORM entities and ensure they are annotated with grails.persistence.Entity:

If you wish to use GORM for MongoDB outside of a Grails application you should declare the necessary dependencies, for example in Gradle:

Then annotate your entities with the grails.gorm.annotation.Entity annotation:

Then you need to place the bootstrap logic somewhere in the loading sequence of your application which uses MongoDatastore:

For configuration you can either pass a map or an instance of the org.springframework.core.env.PropertyResolver interface:

If you are using Spring with an existing ApplicationContext you can instead call MongoDbDataStoreSpringInitializer.configureForBeanDefinitionRegistry prior to refreshing the context. You can pass the Spring Environment object to the constructor for configuration:

The way GORM for MongoDB works is to map each domain class to a Mongo collection. For example given a domain class such as:

This will map onto a MongoDB Collection called "person".

It is quite common in MongoDB to embed documents within documents (nested documents). This can be done with GORM embedded types:

You can map embedded lists and sets of documents/domain classes:

You can also embed maps of embedded classes where the keys are strings:

You can also map lists and maps of basic types (such as strings) simply by defining the appropriate collection type:

Basic collection types are stored as native ArrayList and BSON documents within the Mongo documents.

You may wish to customize how a domain class maps onto a MongoCollection. This is possible using the mapping block as follows:

In this example we see that the Person entity has been mapped to a collection called "mycollection" in a database called "mydb".

You can also control how an individual property maps onto a Mongo Document field (the default is to use the property name itself):

If you are using the mapping engine, for non-embedded associations by default GORM for MongoDB will map links between documents using MongoDB database references also known as DBRefs.

If you prefer not to use DBRefs then you tell GORM to use direct links by using the reference:false mapping:

By default in GORM entities are supplied with an integer-based identifier. So for example the following entity:

Has a property called id of type java.lang.Long. In this case GORM for Mongo will generate a sequence based identifier using the technique described in the Mongo documentation on Atomic operations.

However, sequence based integer identifiers are not ideal for environments that require sharding (one of the nicer features of Mongo). Hence it is generally advised to use either String based ids:

Or a native BSON ObjectId:

BSON ObjectId instances are generated in a similar fashion to UUIDs.

In order to be as efficient as possible when it comes to generating updates GORM for MongoDb will track changes you make to persistent instances.

When an object is updated only the properties or associations that have changed will be updated.

You can check whether a given property has changed by using the hasChanged method:

This method is defined by the org.grails.datastore.mapping.dirty.checking.DirtyCheckable trait.

In the case of collections and association types GORM for MongoDB will wrap each collection in a dirty checking aware collection type.

One of the implications of this is if you override the collection with a non-dirty checking aware type it can disable dirty checking and prevent the property from being updated.

If any of your updates are not updating the properties that you anticipate you can force an update using the markDirty() method:

This will force GORM for MongoDB to issue an update for the given property name.

A feature of MongoDB is its ability to customize how important a database write is to the user. The Java client models this as a WriteConcern and there are various options that indicate whether the client cares about server or network errors, or whether the data has been successfully written or not.

If you wish to customize the WriteConcern for a domain class you can do so in the mapping block:

Unlike a relational database, MongoDB allows for "schemaless" persistence where there are no limits to the number of attributes a particular document can have. A GORM domain class on the other hand has a schema in that there are a fixed number of properties. For example consider the following domain class:

Here there are two fixed properties, name and goesInPatch, that will be persisted into the MongoDB document. Using GORM for MongoDB you can however use dynamic properties via the Groovy subscript operator. For example:

Using the subscript operator you can add additional attributes to the underlying Document instance that gets persisted to the MongoDB allowing for more dynamic domain models.

GORM for MongoDB will persist all common known Java types like String, Integer, URL etc., however if you want to persist one of your own classes that is not a domain class you can implement a custom user type.

GORM for MongoDB supports all of the regular methods for executing GORM queries apart from HQL, which is a Hibernate specific query language more appropriate for SQL databases.

If you wish to execute a native MongoDB query you can use the find method that takes a Bson argument. For example:

The find method will return a FindIterable instance that you can then use to further customize via filters, sorting and projections.

The find method will return instances of your domain class for each query. If you wish to instead obtain MongoDB Document instance then you should use the collection property of the domain class:

MongoDB supports storing Geospacial data in both flat and spherical surface types.

To store data in a flat surface you use a "2d" index, whilst a "2dsphere" index used for spherical data. GORM for MongoDB supports both and the following sections describe how to define and query Geospacial data.

Using MongoDB 2.6 and above you can create full text search indices.

To create a "text" index using the index method inside the mapping block:

You can then search for instances using the search method:

You can search for the top results by rank using the searchTop method:

And count the number of hits with the countHits method:

To configure multiple Mongo client connections you need to use the grails.mongodb.connections setting. For example in application.yml:

You can configure individual settings for each Mongo client. If a setting is not specified by default the setting is inherited from the default Mongo client.

If a domain class has no specify Mongo client connection configuration then the default is used.

You can set the connection method in the mapping block to configure an alternate Mongo Client.

For example, if you want to use the ZipCode domain to use a Mongo client connection called 'lookup', configure it like this:

A domain class can also use two or more configured Mongo client connections by using the connections method with a list of names to configure more than one, for example:

If a domain class uses the default connection and one or more others, you can use the ConnectionSource.DEFAULT constant to indicate that:

If a domain class uses all configured DataSource instances use the value ALL:

You can switch to a different connection at runtime with the withConnection method:

Any logic executed within the body of the closure will use the alternate connection. Once the close finishes execution GORM will switch back to the default connection automatically.

Introduced in GORM 6.0, the ConnectionSources API allows you to introspect the data sources configured for the application:

You can configure Multi-Tenancy the same way described in the GORM for Hibernate documenation, simply specify a multi tenancy mode and resolver:

Note that if you are using MongoDB and Hibernate together the above configuration will configure both MongoDB and Hibernate to use a multi-tenancy mode of DATABASE.

If you only want to enable multi-tenancy for MongoDB only you can use the following configuration instead:

The following transformations can be applied to any class to simplify greatly the development of Multi-Tenant applications. These include:

For example:

As mentioned previously, GORM for MongoDB supports all three multi tenancy modes however there are some considerations to keep in mind.

If you are using a multi-tenancy mode of DATABASE then by default the expectation is that all tenants are configured in your application.yml file.

However, it is possible read your Mongo client connection sources dynamically using MongoConnectionSources.

The MongoConnectionSources class will read the mongo client configurations from a Mongo collection called mongo.connections by default. To configure it you must specify the connectionSourcesClass in application.yml:

You can then even add new connections at runtime using the ConnectionSources API:

All new connection sources will be stored within the specified connectionsCollection and if the application is restarted will read from the connectionsCollection.

Domain classes are by default stateful, which means when they are read from a MongoDB document their state is stored in the user session (which is typically bound to the request in Grails). This has several advantages for write heavy applications:

For an example of when a stateful domain class is better consider the following:

With a stateful entity the updates to the three properties can be batched up and executed in the save() call, when there is no state then 3 updates needs to be executed for each schemaless property (ouch!).

However, stateful domain classes can cause problems for read-heavy applications. Take for example the following code:

The above example will read 100,000 books and print the title of each. In stateful mode this will almost certainly run out of memory as each MongoDB document is stored in user memory as is each book. Rewriting the code as follows will solve the problem:

Alternatively you can map the domain class as stateless, in which case its state will never be stored in the session:

There are several disadvantages to using stateless domain classes as the default. One disadvantage is that if you are using assigned identifiers GORM cannot detect whether you want to do an insert or an update so you have to be explicit about which one you want:

In the above case we use the explicit insert method to tell Grails this is an insert not an udpate. Another disadvantage is that reading of schemaless/dynamic properties is more costly. For example:

Here GORM has to execute an additional read method for each schemaless property! This is better written as:

Thus only requiring one query. Or alternatively you can use the native API:

Which would be more efficient.