Using Dates in CRUD Operations in MongoDB

1. Overview

In this tutorial, we’ll use the MongoDB Java Driver to execute date-related CRUD operations, such as creating and updating documents with date fields, and querying, updating, and deleting documents whose date fields fall within a given range.

2. Setup

Before diving into the implementation, let’s set up our work environment.

2.1. Maven Dependency

First, you should have MongoDB installed. If you don’t, you can follow the official MongoDB installation guide to do so.

Next, let’s add the MongoDB Java Driver as a dependency to our pom.xml file:

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-sync</artifactId>
    <version>4.6.0</version>
</dependency>

2.2. POJO Data Model

Let’s define a POJO to represent the documents contained in our database:

public class Event {
    private String title;
    private String location;
    private LocalDateTime dateTime;

    public Event() {}
    public Event(String title, String location, LocalDateTime dateTime) {
        this.title = title;
        this.location = location;
        this.dateTime = dateTime;
    }
    
    // standard setters and getters
}

Note that we’ve declared two constructors. MongoDB uses the no-argument constructor by default. The other constructor is for our own use throughout this tutorial.

Let’s also note that, while dateTime could have been a String variable, the best practice is to use date/time-specific JDK classes for date fields. Using String fields to represent dates requires extra effort to ensure the values are formatted correctly.

We are now ready to connect a client to our database.

2.3. MongoDB Client

In order for MongoDB to serialize/deserialize our Event POJO, we need to register PojoCodecProvider with MongoDB’s CodecRegistry:

CodecProvider codecProvider = PojoCodecProvider.builder().automatic(true).build();
CodecRegistry codecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(codecProvider));

Let’s create a database, collection, and client that will use the PojoCodecProvider we registered:

MongoClient mongoClient = MongoClients.create(uri);
MongoDatabase db = mongoClient.getDatabase("calendar").withCodecRegistry(codecRegistry);
MongoCollection<Event> collection = db.getCollection("my_events", Event.class);

We’re now ready to create documents and perform date-related CRUD operations.

3. Creating Documents With Date Fields

In our POJO, we used LocalDateTime instead of a String in order to make it easier to work with date values. Let’s take advantage of that now by constructing Event objects using LocalDateTime‘s convenient API:

Event pianoLessonsEvent = new Event("Piano lessons", "Foo Blvd",
  LocalDateTime.of(2022, 6, 4, 11, 0, 0));
Event soccerGameEvent = new Event("Soccer game", "Bar Avenue",
  LocalDateTime.of(2022, 6, 10, 17, 0, 0));

We can insert the new Events into our database as follows:

InsertOneResult pianoLessonsInsertResult = collection.insertOne(pianoLessonsEvent);
InsertOneResult soccerGameInsertResult = collection.insertOne(soccerGameEvent);

Let’s verify the insertions were successful by checking the id of the inserted documents:

assertNotNull(pianoLessonsInsertResult.getInsertedId());
assertNotNull(soccerGameInsertResult.getInsertedId());

4. Querying Documents Matching Date Criteria

Now that we have Events in our database, let’s retrieve them based on their date fields.

We can use the equality filter (eq) to retrieve documents matching a specific date and time:

LocalDateTime dateTime = LocalDateTime.of(2022, 6, 10, 17, 0, 0);
Event event = collection.find(eq("dateTime", dateTime)).first();

Let’s check the individual fields of the resulting Event:

assertEquals("Soccer game", event.title);
assertEquals("Bar Avenue", event.location);
assertEquals(dateTime, event.dateTime);

We can also use the MongoDB BasicDBObject class along with the gte and lte operators to build more complex queries using Date ranges:

LocalDateTime from = LocalDateTime.of(2022, 06, 04, 12, 0, 0);
LocalDateTime to = LocalDateTime.of(2022, 06, 10, 17, 0, 0);
BasicDBObject object = new BasicDBObject();
object.put("dateTime", BasicDBObjectBuilder.start("$gte", from).add("$lte", to).get());
List list = new ArrayList(collection.find(object).into(new ArrayList()));

Since the soccer game is the only Event within the date range of our query, we should only see one Event object in the list, with the piano lesson excluded:

assertEquals(1, events.size());
assertEquals("Soccer game", events.get(0).title);
assertEquals("Bar Avenue", events.get(0).location);
assertEquals(dateTime, events.get(0).dateTime);

5. Updating Documents

Let’s explore two use cases for updating documents based on their date fields. First, we’ll update the date field of a single document, and then we’ll update multiple documents matching a date range.

5.1. Updating a Document’s Date Field

To update a MongoDB document, we can use the updateOne() method. Let’s also use the currentDate() method to set the dateTime field of our piano lesson event:

Document document = new Document().append("title", "Piano lessons");
Bson update = Updates.currentDate("dateTime");
UpdateOptions options = new UpdateOptions().upsert(false);
UpdateResult result = collection.updateOne(document, update, options);

Note that the first argument to updateOne() is a Document object that MongoDB will use to match a single entry in our database. If multiple documents are a match, MongoDB will only update the first document it encounters. Let’s also note that we passed false to the upsert() method. If we had instead passed in true, MongoDB would insert a new document if none of the existing documents matched.

We can confirm the operation was successful by checking how many documents were modified:

assertEquals(1, result.getModifiedCount());

5.2. Updating Documents Matching Date Criteria

To update multiple documents, MongoDB provides the updateMany method. In this example, we’ll update multiple events matching the date range from our query.

Unlike updateOne(), the updateMany() method expects a second Bson object to encapsulate the query criteria that will define which documents we want to update. In this case, we’ll specify a date range covering all events in 2022 by introducing the lt field operator:

LocalDate updateManyFrom = LocalDate.of(2022, 1, 1);
LocalDate updateManyTo = LocalDate.of(2023, 1, 1);
Bson query = and(gte("dateTime", from), lt("dateTime", to));
Bson updates = Updates.currentDate("dateTime");
UpdateResult result = collection.updateMany(query, updates);

Just like with updateOne(), we can confirm this operation updated multiple events by checking the update count of our result object:

assertEquals(2, result.getModifiedCount());

6. Deleting Documents Matching Date Criteria

As with updates, we can delete one or multiple documents from our database at a time. Suppose we need to remove all events from 2022. Let’s use a Bson date range query and the deleteMany() method to do that:

LocalDate deleteFrom = LocalDate.of(2022, 1, 1);
LocalDate deleteTo = LocalDate.of(2023, 1, 1);
Bson query = and(gte("dateTime", deleteFrom), lt("dateTime", deleteTo));
DeleteResult result = collection.deleteMany(query);

Since all of the events we have created in this tutorial have a 2022 dateTime field value, deleteMany() removed them all from our collection. We can confirm this by checking the delete count:

assertEquals(2, result.getDeletedCount());

7. Using Time Zones

MongoDB stores dates in UTC, and this cannot be changed. Thus, if we want our date fields to be specific to a time zone, we can store the time zone offset in a separate field and do the conversion ourselves. Let’s add that field as a String:

public String timeZoneOffset;

We’ll need to adjust our constructor so we can set the new field when creating events:

public Event(String title, String location, LocalDateTime dateTime, String timeZoneOffset) {
    this.title = title;
    this.location = location;
    this.dateTime = dateTime;
    this.timeZoneOffset = timeZoneOffset;
}

We can now create and insert events for specific time zones into our database. Let’s use the ZoneOffset class to avoid having to manually format the time zone offset String:

LocalDateTime utcDateTime = LocalDateTime.of(2022, 6, 20, 11, 0, 0);
Event pianoLessonsTZ = new Event("Piano lessons", "Baz Bvld", utcDateTime, ZoneOffset.ofHours(2).toString());
InsertOneResult pianoLessonsTZInsertResult = collection.insertOne(pianoLessonsTZ);
assertNotNull(pianoLessonsTZInsertResult.getInsertedId());

Note that since the offset is relative to UTC, the dateTime member variable must represent UTC time so we can correctly convert it later. Once we retrieve the document from the collection, we can make the conversion using the offset field and the OffsetDateTime class:

OffsetDateTime dateTimeWithOffset = OffsetDateTime.of(pianoLessonsTZ.dateTime, ZoneOffset.of(pianoLessonsTZ.timeZoneOffset));

8. Conclusion

In this article, we learned how to perform date-related CRUD operations using Java and a MongoDB database.

We used date values to create, retrieve, update, or remove documents in our database. Throughout our examples, we covered various helper classes and introduced MongoDB operators that are helpful when dealing with dates. Finally, to work around how MongoDB only stores dates in UTC, we learned how to work with date/time values that need to be time zone specific.