GORM for MongoDB

A domain that declares String id without its own storedAs mapping now persists _id as a BSON ObjectId. Before 8.0.0 the default was BSON String.

Application code is unaffected: person.id is still the 24-char hex String, and get, findAllByIdInList, updates and deletes still accept hex strings. What changes is the BSON type written to and matched in the database.

This is a data-compatibility change. An application upgrading from 7.x whose collections already hold String _id values has two options:

Domains keyed by a natural string value (slug, email, UUID) should declare the opt-out explicitly, since such values are not valid ObjectId hex:

See Identity Generation for the full description of storedAs.

A transactional service method called from another, or withTransaction inside withTransaction, used to begin a second transaction on the same session: it committed on its own, and the surrounding transaction’s commit then did nothing, so the surrounding transaction’s later writes could be lost. It now joins the surrounding transaction, and everything commits once when that one does, as on Hibernate.

The effect most applications will notice: without multi-document transactions, GORM for MongoDB does not flush before a query while a transaction is in progress, so a write a joined call leaves queued is not visible to a later query in the same transaction. It used to be, because the inner transaction flushed it when it returned:

Save with flush: true where a later query in the same transaction must see the write. This includes integration tests annotated with @Rollback, whose service calls now join the test’s transaction. With multi-document transactions enabled (grails.mongodb.transactional), GORM flushes before a query inside the server-side transaction, so the query sees the order, and the write is still rolled back if the transaction fails. See Nested Transactions for the other propagation changes.

GORM 7.1 supports Apache Groovy 3, Java 14, MongoDB Driver 4.3 and Spring 5.3.x.

Each of these underlying components may have changes that require altering your application. These changes are beyond the scope of this documentation.

A Grails Service (or a bean) inside GORM DataService will default to autowire by-type, For example:

./grails-app/services/example/BookService.groovy

Please note that with autowire by-type as the default, when multiple beans for same type are found the application with throw Exception. Use the Spring `@Qualifier annotation for Fine-tuning Annotation Based Autowiring with Qualifiers.

Creating a MongoDatastore no longer connects to MongoDB or builds the indexes the domain classes declare, whichever constructor creates it, including one handed a MongoClient the application created itself. The datastore connects and builds them when it is started. In an application, Spring starts it with the other lifecycle beans, after every bean has been created and before BootStrap runs or the web server accepts a request, so the indexes are in place where they were before.

Code that creates a MongoDatastore itself and relies on the indexes existing once the constructor returns has to start it first:

A datastore that nothing has started starts itself the first time a session is opened on it, which any GORM query, save or withTransaction does, so code that goes through GORM finds the indexes as before. What needs the explicit start() is code that inspects the indexes, or reaches MongoDB through the MongoClient directly, straight after creating the datastore. A datastore stopped with stop() is started again only by start(); using it in between is refused.

Code that queries MongoDB while the application’s beans are still being created, rather than in BootStrap or later, starts the datastore early. It still works, but the process can then no longer be checkpointed with CRaC as its context refreshes; see Checkpoint and Restore.

In a Spring Boot application, grails-data-mongodb-spring-boot now declares the MongoClient bean itself, ahead of Spring Boot’s MongoDB auto-configuration, which then declares none. GORM builds it the way Spring Boot builds its own, from the spring.mongodb.* properties, Spring Boot’s MongoClientSettings and every Spring Boot MongoClientSettingsBuilderCustomizer bean, so it connects to the same server with the same options. Spring Data, health checks, metrics and anything else that injects a MongoClient are given GORM’s. GORM owns that client: it connects it when the datastore starts, closes it when the application shuts down, and stops and starts it around a CRaC checkpoint. Before, GORM’s auto-configuration ran after Spring Boot’s and was handed Spring Boot’s client, which GORM then left alone, so it was not stopped for a checkpoint.

An application that declares a MongoClient bean of its own keeps it, and GORM uses it as before.

When GORM is handed a MongoClient that it did not create — which is what happens whenever the application declares a MongoClient bean of its own — it built its settings from the defaults and applied only the database name. Everything else configured under grails.gorm and grails.mongodb was silently ignored on that path. Those settings are now applied, exactly as they always were when GORM creates the client itself.

Nothing in your configuration changes. What changes is that configuration you already have starts taking effect:

Multi-tenancy needs one extra step on this path. A TenantResolver registered as a Spring bean is injected into the connection source factory, and there is no factory involved when the client is supplied, so the bean is never consulted. Configure the resolver by class instead:

Without it the mode is active but the resolver is NoTenantResolver, which throws TenantNotFoundException on every tenant-scoped operation. Settings under grails.mongodb continue to take precedence over the grails.gorm equivalents.

The connection details are the exception, since the supplied client is already connected: grails.mongodb.url is not applied to it. That also matters for a connection declared under grails.mongodb.connections without a url of its own, which falls back to the host, port, username and password settings — 127.0.0.1:27017 unless those are set — rather than to grails.mongodb.url. Give each such connection its own url.

Inside Book.moreBooks.withTransaction { }, Book.moreBooks.withNewSession { }, a withConnection block or a method annotated @Transactional(connection = 'moreBooks') for a class that declares that connection, the calls on Book itself, such as Book.list() or book.save(), now use that connection. Previously they used the default connection, so a document saved there was written to the default database. Code that reached the default connection from inside such a block by calling the class directly should name it, as in ``Book.default.list()``.

When you construct a MongoDatastore with a MongoClient that you created yourself, GORM no longer closes that client when the datastore shuts down. The client is owned by whoever created it, so closing it is now your responsibility.

This only affects you if you previously relied on MongoDatastore.close() to also close a client you passed in:

No change is required when GORM creates the client itself — for example new MongoDatastore(Person), or configuration-driven setups where GORM builds the client from grails.mongodb.* settings — because GORM continues to own and close those clients. A MongoClient registered as a Spring bean likewise continues to be closed by the ApplicationContext.

A declared unique index that cannot be built because documents in the collection already share a value used to end the index build with a DuplicateKeyException: the indexes declared after it were not built, and with the default synchronous build the application did not start. It is now handled like any other index the server refuses: logged at ERROR with the domain class and the duplicate key, counted as a failure in the build summary, which is logged at WARN, and the build goes on with the remaining declarations. The application starts without that index.

Remove the duplicates and build the index again, with buildIndex() or by restarting, to have it created. To keep refusing to run without it, check the result of buildIndexAsync() (see Building Indexes on Demand) and stop when failures() is not zero.

The index build of each connection created the indexes declared by every domain class, including classes mapped only to another connection, so a class mapped to the default connection also had its collection and indexes created in the database of every named connection. Each connection now builds the indexes of the classes mapped to it: those that name it with connection or connections, those mapped to ConnectionSource.ALL, and, on the default connection, those that name none. The indexes already created elsewhere stay where they are; findUndeclaredIndexes() on that connection does not report them, since no class is mapped to their collection there.

As mentioned the GORM for MongoDB plugin will configure all the defaults for you, but if you wish to customize those defaults you can do so in grails-app/conf/application.yml:

or equivalently in grails-app/conf/application.groovy:

The databaseName setting configures the default database name. If not specified the databaseName will default to the name of your application.

You can also customize the MongoDB connection settings using an options block:

Available options and their descriptions are defined in the MongoClientOptions javadoc.

Since 2.0, you can also use MongoDB connection strings to configure the connection:

Using MongoDB connection strings is currently the most flexible and recommended way to configure MongoDB connections.

Below is a complete example showing all configuration options:

Using the grails.mongodb.default.mapping setting in grails-app/conf/application.groovy you can configure global mapping options across your domain classes. This is useful if, for example, you want to disable optimistic locking globally or you wish to use DBRefs in your association mappings. For example, the following configuration will disable optimistic locking globally and use DBRefs for all properties:

The * method is used to indicate that the setting applies to all properties.

The storage type of String id fields is controlled globally by grails.mongodb.stringIds.defaultStoredAs (values objectid, the default as of 8.0.0, or string). See Identity Generation for details, including the upgrade note for applications with existing String _id data.

grails.mongodb.engine selects the persistence engine. codec is the default and the recommended value. mapping remains available for compatibility, but is deprecated.

The mapping engine is deprecated and will be removed in a future release. It reaches MongoDB through a separate persister hierarchy that has to be kept in step with the codec one for every change to the storage layer, and it offers no capability the codec engine lacks. An application setting it should remove the setting:

Selecting it logs a warning at startup.

GORM creates and reconciles the indexes declared in your mapping blocks each time the datastore starts, and startup waits for MongoDB to finish building them. In an application the datastore starts when Spring starts its lifecycle beans, after every bean has been created and before BootStrap runs or the web server accepts a request. A datastore created outside an application context starts the first time a session is opened on it. Set grails.mongodb.buildIndexes = false to leave the indexes on the server untouched instead, and build them with MongoDatastore.buildIndex() when you choose, or grails.mongodb.buildIndexesAsync = true to keep building them but on a background thread — see Querying Indexing for details and when to use each.

GORM takes part in the Spring lifecycle, so an application can be checkpointed with CRaC and restored, whether the checkpoint is taken while the application is running or as its context refreshes (-Dspring.context.checkpoint=onRefresh). CRaC refuses to checkpoint a process holding open sockets, and a connected MongoClient holds several:

An embedded MongoDB is stopped after the clients and started again before them.

The MongoClient GORM hands out stays the same object across a checkpoint: stopping it closes the driver’s client inside it, and starting it builds a new one. The mongo bean, a client obtained from MongoDatastore.getMongoClient(), multi-tenancy and the Spring Data MongoDB integration all go on working after the restore. A MongoDatabase, MongoCollection or ClientSession obtained from the client belongs to the driver’s client it came from, so obtain it again after a restore rather than keeping it.

A client the application supplied to GORM is neither started, stopped nor replaced. It belongs to whoever created it, and that code has to close it before the checkpoint for the checkpoint to succeed, and, for a checkpoint taken as the context refreshes, must not have connected it by then. In a Spring Boot application GORM declares the MongoClient bean itself, built from Spring Boot’s settings (see Using GORM in Spring Boot), so unless the application declares one of its own, that client is GORM’s and is handled like the rest.

A checkpoint taken as the context refreshes also needs the application itself to leave MongoDB alone until then: code that queries it while beans are still being created, rather than in BootStrap or later, connects the datastore early, and so does reading the connections themselves from MongoDB with MongoConnectionSources, which reads them as the datastore is created.

By default a GORM transaction for MongoDB is a client-side unit of work: pending inserts, updates and deletes are batched and flushed to the server when the transaction commits, but each write is applied individually and is not rolled back if a later operation fails.

Since MongoDB 4.0, the server supports multi-document ACID transactions. To have GORM run transactional operations inside a real server-side transaction — so that all writes within a withTransaction block (or a @Transactional service method) commit or roll back atomically — enable:

With this enabled, a GORM transaction starts a MongoDB session and transaction; on commit all buffered writes are committed together, and on rollback they are discarded on the server:

A transaction started inside another joins it, so the writes of both commit or roll back together; PROPAGATION_REQUIRES_NEW runs in a server-side transaction of its own. A read-only transaction reads without one. See Nested Transactions and Read-Only Transactions.

Two backends are supported.

in-memory is used unless flapdoodle is on the classpath, in which case flapdoodle is preferred, so adding the dependency is all that is needed to move to a real mongod. Set embedded.mongodb.backend to choose explicitly.

Flapdoodle is not a dependency of this module because it requires jgrapht, which is offered under LGPL-2.1 or EPL-2.0 and so cannot be required by an Apache release. An application adds it in the same way it chooses a SQL driver:

Whether to start a server, which port, and which database are all read from the URL. These configure the server behind it.

A multi-document transaction, a change stream and a causally consistent read are all refused by a standalone MongoDB server: every one of them needs a replica set. An application that asks GORM for transactions is therefore given one - a set of a single node, which is what a single machine has to offer, and enough for all three:

The server runs as the replica set rs0 and is handed to the application only once it has elected itself primary, so the first query does not race the election. Name the set with embedded.mongodb.replica-set to call it something else, or to run one without asking GORM for transactions:

Only the flapdoodle backend can do this, because only a real mongod has replication. The in-memory backend reimplements the wire protocol and refuses transactions whatever it is configured with.

A generated application names a real host in production, so nothing is started there.

Where an embedded server in production is genuinely wanted, ask for one in that environment’s url and use flapdoodle with a directory, so the data survives a restart:

A server started by this module runs until the JVM exits, so a Spring Boot DevTools restart reuses it instead of starting another. Only a server this module started is reused: if anything else is already holding the port, startup fails with an error naming the port rather than connecting to an unrelated service.

A restart that carries a different setting - a backend, a database directory, a version, a replica set, or transactions being switched on - is given a server that matches it, which means the previous one is replaced and anything it held in memory goes with it. Data in a database-dir outlives the replacement, except across a change of version: MongoDB refuses to start against a directory written by a different release. To use a MongoDB started by hand, name its host in grails.mongodb.url as usual.

Switching backend counts as much as the rest: an application handed the in-memory server after asking for flapdoodle would not fail at the switch but later, at the first transaction or $text query it ran. Naming a backend whose library is not on the classpath fails the restart rather than handing back the server already listening, which is what that configuration does when nothing is running yet.

The server is normally started as soon as the application context is initialized, so that anything talking to MongoDB while beans are still being created finds it listening. An application checkpointed with CRaC as its context refreshes (-Dspring.context.checkpoint=onRefresh), or one that exits there (-Dspring.context.exit=onRefresh, as a run that trains a class data sharing archive does), has its URL published all the same, but its server is started with the application context’s lifecycle beans, ahead of the datastore. A checkpoint cannot contain the server’s listening socket, and a JVM halted as its context refreshes would leave a flapdoodle mongod running. A URL that asks for port 0 is given a free port when it is published, since the server binds later.

The module is plain Java and knows nothing about Grails beyond the default property name, so embedded.mongodb.property-names makes it usable from any Spring application:

Spring Data MongoDB applications are usually better served by flapdoodle’s own de.flapdoodle.embed.mongo.spring3x auto configuration, which this module deliberately does not duplicate.

With GORM multi-document transactions enabled (grails.mongodb.transactional = true, see Advanced Configuration), a single transactional method commits or rolls back GORM writes and Spring Data writes together on one server-side ClientSession:

The unified manager is registered as the primary transactionManager (it has to be, to be chosen over GORM’s plain mongoTransactionManager for an unqualified @Transactional). It backs off automatically if the application already defines a bean named transactionManager. To run a block with GORM-only semantics, qualify the manager: @Transactional("mongoTransactionManager").

Only the connection, codecs and (within a transaction) the ClientSession are shared. The two object-mapping models remain separate: GORM maps its @Entity classes through its own mapping context, and Spring Data maps its own document classes through MappingMongoConverter. Do not point @EnableMongoRepositories at GORM @Entity packages, and do not register GORM entities with Spring Data’s mapping context. Two classes may map the same collection only if you keep their field mappings compatible.

Declaring String id on every domain class ties that source to MongoDB: the same class compiled against Hibernate would need Long id instead. Where domain classes are shared, or an application is written to run against either store, the build can ask for the identity type of whichever GORM implementation each domain class is mapped with:

A domain class mapped with MongoDB is then given a String id — holding the hexadecimal form of a generated ObjectId, exactly as if it had been declared — while one mapped with Hibernate keeps Long. Nothing in the domain class itself names a store.

The default is defaultIdType = 'long', which gives every domain class a Long id as earlier releases did. The type is resolved when the domain class is compiled, from its mapWith property and the GORM implementations on the compilation classpath, so an application using more than one implementation gets the right type for each domain class from the single setting. A domain class that declares an id of its own keeps the type it declares either way.

Precompiled plugin domain classes cannot have their bytecode changed by the consuming application’s compiler. A plugin that wants to leave this choice to its consumer can declare a portable identity:

The consuming application uses the same build setting above for both cases. The Grails Gradle plugin packages its value as grails.gorm.defaultIdType, which is used at runtime for precompiled plugin domains. No duplicate application configuration is required, although normal external configuration can override the packaged value.

MongoDB resolves the portable identity to String for native and Long for long. The result is stored in the entity mapping metadata, so normal persistence operations do not perform repeated type resolution. An explicitly declared concrete identity type still wins.

Note that if you manually assign an identifier, then you will need to use the insert method instead of the save method, otherwise GORM can’t work out whether you are trying to achieve an insert or an update. Example:

A domain that declares String id is convenient in application code — HTTP controllers return clean JSON, URLs embed ids directly, and you never need new ObjectId(...) at call sites. Writing _id as a BSON String to match would give up the native ObjectId benefits at the storage layer (12-byte index entries vs. 24-byte hex strings, embedded creation timestamp, etc.).

The storedAs mapping option decouples the two, so you get both: the domain sees a String id (hex form), while _id on disk is a BSON ObjectId. As of Grails 8.0.0 this is the default for any String id that declares no storedAs of its own — the mapping below is what that default applies for you, and is only needed to be explicit or to override a global defaultStoredAs: string:

With storedAs: ObjectId:

This is especially useful when migrating a legacy ObjectId id domain to String id for ergonomic reasons, because neither a data migration nor any change in application call sites is required.

Dirty checking uses the equals() method to determine if a property has changed. In the case of associations, it is important to recognize that if the association is a proxy, comparing properties on the domain that are not related to the identifier will initialize the proxy, causing another database query.

If the association does not define equals() method, then the default Groovy behavior of verifying the instances are the same will be used. Because proxies are not the same instance as an instance loaded from the database, which can cause confusing behavior. It is recommended to implement the equals() method if you need to check the dirtiness of an association. For example:

MongoDB doesn’t require that you specify indices to query, but like a relational database without specifying indices your queries will be significantly slower.

With that in mind it is important to specify the properties you plan to query using the mapping block:

With the above mapping a MongoDB index will be automatically created for you. You can customize the index options using the indexAttributes configuration parameter:

You can use MongoDB Query Hints by passing the hint argument to any dynamic finder:

Or in a criteria query using the query "arguments" method

MongoDB supports the notion of compound keys. GORM for MongoDB enables this feature at the mapping level using the compoundIndex mapping:

As per the MongoDB docs 1 is for ascending and -1 is for descending.

MongoDB can automatically remove documents from a collection once they reach a certain age using a TTL index. Declare one by adding expireAfterSeconds to the indexAttributes of a single date-valued property:

With the mapping above MongoDB expires each LoginEvent roughly one hour (3600 seconds) after the value stored in its dateCreated property. The indexed property must hold a Date (or an array of dates), and TTL is supported on single-field indexes only — MongoDB ignores expireAfterSeconds if it is applied to a compoundIndex.

If you later change the declared expireAfterSeconds, GORM reconciles the existing index in place on startup (using MongoDB’s collMod command) so that the new expiry takes effect without dropping or rebuilding the index.

In addition to declaring a text index with the index method (see Full Text Search), you can declare one on a single property through indexAttributes using type: 'text':

The type attribute sets the index type for that field, so it can equally be used to declare other special index types such as '2d' or '2dsphere'. Note that MongoDB allows at most one text index per collection. See Full Text Search for how to query a text index once it has been created.

An index is created from its declared options the first time the collection is initialised. If you later change the options of an already-created index — for example marking it unique — MongoDB cannot alter most options in place and reports an IndexOptionsConflict. By default GORM logs this conflict and leaves the existing index untouched.

To have GORM drop the existing index and recreate it with the newly declared options, add recreateOnConflict: true to the indexAttributes:

A declared index whose name is already held by an index on different keys is the same kind of conflict, reported by MongoDB as an IndexKeySpecsConflict, and recreateOnConflict resolves it the same way:

Without it, GORM says which name is taken, leaves the index that holds it alone, and counts the declaration as failed.

A change to a TTL index’s expireAfterSeconds is handled automatically and does not require recreateOnConflict, because GORM updates the expiry in place rather than rebuilding the index.

By default GORM creates and reconciles every index declared in a mapping block when the datastore starts. Set buildIndexes to false in grails-app/conf/application.yml to switch that off:

or, in application.groovy:

With this setting GORM issues no createIndex or collMod command by itself, for any domain class, and the indexes already present on the server are left exactly as they are until the application builds them (see Building Indexes on Demand below). Queries are unaffected and continue to use whichever indexes exist. This is useful when deploying against live data whose indexes are managed separately — by a DBA or a migration step — so that a deployment does not build an index against a large production collection, and so an application running against an older index set does not have those indexes reconciled underneath it.

It also suppresses index creation for domain classes registered after startup. Declared at the top level the setting applies to every connection, and each connection can override it:

MongoDB answers a createIndex command only once the index has been built, so by default the thread that starts the datastore — in an application, the thread starting the application context — waits for every declared index before the application finishes starting. On an empty collection that is instant; on a large existing collection an index build can take minutes, and a deployment waits for all of them in turn.

Set buildIndexesAsync to have index builds run on a background thread instead, both the one GORM runs at startup and any the application starts with buildIndex():

Startup then continues without waiting. The indexes are still built one at a time per connection, on a daemon thread named after its connection, such as gorm-mongo-index-build-default-1. Different connections can build indexes concurrently, including when they use the same MongoDB server. The thread is released after the build finishes and it has been idle for one second.

Two consequences are worth planning for:

The setting also applies with buildIndexes set to false, to the builds the application starts with buildIndex(). A domain class registered after startup is indexed on the thread registering it, once any build running on the connection has finished, and only when it is mapped to the default connection; if the datastore is stopped for a checkpoint at the time, it is indexed when the datastore is started again.

An index build that finishes without error logs one summary line at INFO:

The domain class count includes every class considered for indexing, including classes that declare no indexes. The created and already-present counts describe index declarations; declaring the same keys twice can report one created and one already present.

The elapsed time is what the caller actually spent waiting — startup, or whoever called buildIndex(), with the default settings, or the background thread when buildIndexesAsync is enabled, where this line is also the only signal that the build has finished.

The split between created and already present is what makes that time interpretable. MongoDB answers a createIndex for an index it already has immediately and without building anything, so a restart that changed no mappings reports everything as already present and costs milliseconds; a line reporting indexes created is the one that accounts for a slow start. An index that recreateOnConflict dropped and built again costs as much as a new one, and is counted apart as recreated:

A declaration the server refuses does not end the build: an option conflict GORM is not authorised to resolve, an invalid specification, or a unique index over documents that already share a value is logged at ERROR as it fails and counted, and the build goes on with the remaining declarations. Only an error that stops the build itself ends it early: a lost connection, or a write concern the server could not satisfy, which leaves unknown whether the index was built. With the default synchronous build that fails startup.

If any declaration failed, the summary is logged at WARN instead and reports how many; the failures themselves are logged individually as they happen. A build that stops partway — a lost connection or a timeout — reports how far it got before stopping, also at WARN:

Telling a created index from one that was already there takes one listIndexes command per collection that declares indexes. It is only issued when the summary will be logged, that is when INFO is enabled for org.grails.datastore.mapping.mongo.

A collection whose indexes cannot be listed still has its declarations applied; only the split between created and already present is missing for it. The summary counts those declarations separately, and the other collections keep their split:

When nothing could be classified — the logger is at WARN, so the build skips listIndexes and a summary is logged only for a build that failed or did not finish, or no collection’s indexes could be listed — the summary reports how many declarations were applied instead:

To find which index is the slow one, enable DEBUG logging for org.grails.datastore.mapping.mongo, which adds a line per index with its own elapsed time:

With buildIndexes off, a declared index exists only once something builds it, and nothing reports one that has not been built yet. findMissingIndexes() on the MongoDatastore bean lists the indexes the domain classes declare that their collections do not have, without changing anything. Logged at startup, it shows when a build has been forgotten:

Each MissingIndex gives the database, the collection, the domain class declaring the index, its key pattern and the options declared with it. A declared index is present when its collection has an index on the same key pattern, the same fields in the same order, whatever its name and options: an option that differs is for the build to reconcile (see Reconciling Index Option Changes). A text index is present when one indexes the same text fields, in any order, with the same keys before and after them, whatever its weights. Keys that several classes mapped to one collection declare are reported once. buildIndex() or buildIndexAsync() creates what is missing. Each named connection covers its own domain classes, so call it through that connection’s datastore for those.

GORM never drops an index. One that a mapping stops declaring, or declares again with its keys in another order, stays on the server, still maintained on every write. findUndeclaredIndexes() on the MongoDatastore bean lists them without changing anything:

Each UndeclaredIndex gives the database, collection, name and key pattern of the index, and the whole description listIndexes returned for it, options included.

An index counts as declared when a domain class mapped to its collection declares the same key pattern, the same fields in the same order, through compoundIndex, index or a property’s index: true. Its name and options do not matter: those differences are what the build reconciles (see Reconciling Index Option Changes). A text index counts as declared when a class declares text on the same fields, in any order, with the same keys before and after them, whatever its weights. The declarations of every class mapped to a collection count, so a subclass’s index on its root’s collection is declared. The _id index is never reported, and nor is any index on a collection that no domain class maps.

dropUndeclaredIndexes() drops everything findUndeclaredIndexes() reports, logging each index at INFO, and returns what it dropped. To drop only some, pass the reviewed list to dropUndeclaredIndexes(List). Each index is checked again before it is dropped, since the server can have changed since the list was made: an index or collection that has gone is skipped, and so, with a WARN, is an index whose name now belongs to an index on other keys, one whose keys a domain class now declares, and one on a collection that no class is mapped to on that connection:

Like the index build, each named connection covers its own domain classes, so call these through that connection’s datastore:

In addition to the convenience features described above you can use the index method to define any index you want. For example:

In the above example I define an index on an embedded attribtue of the document. In fact what arguments you pass to the index method get passed to the underlying MongoDB createIndex method.

GORM for MongoDB is built ontop of MongoDB’s BSON encoding framework. This means it is possible to implement custom Codecs for encoding and decoding values to and from BSON.

For example consider the following simple Groovy class:

By default the encoding engine does not know how to represent this type as a BSON value. To make the encoding engine understand this type you have to implement a custom codec:

With that done you then need to register the custom Codec. There are two ways to achieve this.

You can register a list of codecs in the grails.mongodb.codecs setting in application.yml:

Or you can create a META-INF/services/org.bson.codecs.Codec file containing the fully qualified class name of the Codec. If there are multiple codec classes you would like to register, put each one on a separate line.

Another option is to define a GORM custom type. For example consider the following class:

If you attempt to reference this class from a domain class it will not automatically be persisted for you. However you can create a custom type implementation and register it with Spring. For example:

The above BirthdayType class is a custom user type implementation for MongoDB for the Birthday class. It provides implementations for three methods: readInternal, writeInternal and the optional queryInternal. If you do not implement queryInternal your custom type can be persisted but not queried.

The writeInternal method gets passed the property, the key to store it under, the value and the native DBObject where the custom type is to be stored:

You can then read the values of the custom type and register them with the DBObject. The readInternal method gets passed the PersistentProperty, the key the user type info is stored under (although you may want to use multiple keys) and the DBObject:

You can then construct the custom type by reading values from the DBObject. Finally the queryInternal method allows you to handle how a custom type is queried:

The method gets passed a criterion which is the type of query and depending on the type of query you may handle the query differently. For example the above implementation supports between and equals style queries. So the following 2 queries will work:

However "like" or other query types will not work.

To register a custom type in a grails application simply register it as Spring bean. For example, to register the above BirthdayType add the following to grails-app/conf/spring/resources.groovy:

A Map passed as a criterion value to findWhere, findAllWhere, a criteria query, the where DSL or a dynamic finder is sent to MongoDB as a literal subdocument comparison. Because MongoDB interprets a value document whose keys start with $ as an operator expression rather than as a value, a map that contains such a key at any depth is rejected with InvalidDataAccessResourceUsageException. This applies to every property type, including enums and other custom types; geospatial criteria take shape documents by design and are exempt.

If you need to run an operator query that GORM does not express, use the native find method with a Bson filter as shown above.

MongoDB’s 2dsphere indexes support queries that calculate geometries on an earth-like sphere.

Although you can use coordinate pairs in a 2dsphere index, they are considered legacy by the MongoDB documentation and it is recommended you store data using GeoJSON Point types.

To support this GORM for MongoDB features a special type, grails.mongodb.geo.Point, that can be used within domain classes to store geospacial data:

The Point type gets persisted as a GeoJSON Point. A Point can be constructed from coordinates represented in longitude and latitude (the inverse of 2d index location coordinates!). Example:

Once the 2dsphere index is in place you can use various MongoDB plugin specific dynamic finders to query, including:

Some examples:

In addition to being able to pass any Shape to geospacial query methods you can also pass a map that represents the native values to be passe to the underlying query. For example:

In the above example the native query parameters are simply passed to the $near query

MongoDB supports 2d indexes that store points on a two-dimensional plane. although they are considered legacy and you should use 2dsphere indexes instead.

It is possible to use a MongoDB 2d index by mapping a list or map property using the geoIndex mapping:

By default the index creation assumes latitude/longitude and thus is configured for a -180..180 range. If you are indexing something else you can customise this with indexAttributes

You can then save Geo locations using a two dimensional list:

Alternatively you can use a map with keys representing latitude and longitude:

Once you have your data indexed you can use MongoDB specific dynamic finders to find hotels near a given a location:

You can also find a location within a box (bound queries). Boxes are defined by specifying the lower-left and upper-right corners:

You can also find a location within a circle. Circles are specified using a center and radius:

If you plan on querying a location and some other value it is recommended to use a compound index:

In the example above you an index is created for both the location and the number of stars a Hotel has.

You can also store any GeoJSON shape using the grails.mongodb.geo.Shape super class:

And then use the findBy*GeoIntersects method to figure out whether shapes intersect with each other:

When using the DATABASE mode, only GORM methods calls are dispatched to the correct tenant. This means the following will use the tenant id:

However, going directly through the MongoClient will not work:

If you are working directly with the MongoClient instance you need to make sure you obtain the correct instance. For example:

When using the SCHEMA mode, GORM for MongoDB will use a different MongoDB database, but the same MongoClient instance, for each tenant.

However, once again only GORM methods will use the correct database. For example:

However, getting the database directly from MongoClient will not work:

To resolve this you should always use the DB property of the class which will ensure the right database is used:

When using the DISCRIMINATOR approach, GORM for MongoDB will store a tenantId attribute in each MongoDB document and attempt to partition the data.

Once again this works only when using GORM methods and even then there are cases where it will not work if you use native MongoDB interfaces.

For example the following works fine:

As does this:

But this logic bypasses any built into tenant id interception and inclusion:

Since you are operating directly on the collection GORM cannot know when you perform a query on said collection.

In this case you will have to ensure to include the tenantId manually:

And the same is true of write operations such as inserts that are done with the native API.

Returns the MongoDB MongoDatabase object.