Morphia 2.0 introduces a number of new ways to configure its behavior. These values are listed below:

  1. Collection naming

  2. Property naming

  3. The discriminator key

  4. The discriminator value

Collection and property naming

Traditionally Morphia has used with the class’s "simple name" for the collection name if you choose to not manually map the name of an entity’s collection. Similarly, an entity’s properties were named after the Java field name unless mapped otherwise with the @Property annotation. In 2.0, however, we define naming strategies. As of 2.0, the naming strategies supported out of the box are:

  1. identity This is the legacy behavior Morphia has always used.

  2. lower This is simply the lower case form of the identity strategy.

  3. snake This transforms element names in to their [snake case]( versions. For those coming from a Python background or who work with Python developers regularly, this should look familiar.

  4. camel This transforms element names in to their [camel case]( versions. This is the form most java developers will be familiar with.

  5. kebab This transforms element names in to their [kebab case]( versions. This looks exactly like the snake case but with - instead of _ so that it looks like it’s on a kebab skewer.

These strategies can all be access via the NamingStrategy class via their named methods. In the case where you have a custom naming strategy you’d like to employ, e.g., perhaps some hashing function to obscure element names, you can simply extend NamingStrategy yourself and implement whatever logic you might need.

Discriminator keys and values

Morphia has long hard coded the choice of how to encode an entity’s type in to the resulting documents in the database using the className key and the simple name of the class. As of 2.0, you have a choice to change that if you’d like. The new default is to use _t as the discriminator property key. This was chosen in part because of its use in other systems and also for its brevity. By default, Morphia 2.0 stores the entity type unless you configure your types otherwise so saving space seemed prudent.

Similar to how collections and fields have a naming strategy, we can apply a global function to determine the discriminator values should we choose. The choices here are simpler:

  1. className()/lowerClassName()

  2. simpleName()/lowerSimpleName()

These call all be accessed via their named methods on DiscriminatorFunction and just like the NamingStrategy cases if the provided options are not sufficient, you can implement your own by subclassing DiscriminatorFunction and implementing your own function.

Old versus New

Morphia can be configured in one of two ways: the legacy mode and the modern mode.


We’ll cover the legacy mode first as it reflects how Morphia worked prior to 2.0. MapperOptions drives the configuration and so this is where we’ll start. Prior to 2.0, you could simply create a MapperOptions instance directly. Starting with 2.0, you will need to use one of the factory methods. In this instance, you will want the legacy() method. Among other things, this will configure Morphia to the legacy implementation of the Query class. See here for more information. The legacy() builder currently configures the following settings:

  1. className as the discriminator key

  2. className() as the DiscriminatorFunction

  3. identity() as both the class and field name strategies

  4. Configures the legacy query implementation

New defaults

One of the big goals for 2.0 was to modernize both the API and behavior of Morphia. As such, the builder() method returns a Builder that applies some updated defaults:

  1. _t as the new discriminator key (replacing className)

  2. simpleName() as the discriminator function used to determine these values

  3. camelCase() is the default collection naming strategy

  4. identity() remains the property naming strategy

  5. A new Query implementation is configured enabling the new Filters based querying and disabling some older, deprecated methods.