Document Data Format: Records

Overview

In this guide, you can learn how to store and retrieve data in the MongoDB Java Driver using Java records. Java records are a type of Java class often used to model data and separate business logic from data representation.

Serialize and Deserialize a Record

The driver natively supports encoding and decoding Java records for MongoDB read and write operations using the default codec registry. The default codec registry is a collection of classes called codecs that define how to convert encode and decode Java types. Learn more about codecs and the default codec registry in the guide on Codecs.

public record DataStorageRecord(
        String productName,
        double capacity
) {}

MongoCollection<DataStorageRecord> collection = database.getCollection("data_storage_devices", DataStorageRecord.class);
// insert the record
collection.insertOne(new DataStorageRecord("2TB SSD", 1.71));

MongoCollection<DataStorageRecord> collection = database.getCollection("data_storage_devices", DataStorageRecord.class);
// retrieve and print the records
List<DataStorageRecord> records = new ArrayList<DataStorageRecord>();
collection.find().into(records);
records.forEach(System.out::println);

DataStorageRecord[productName=1TB SSD, capacity=1.71]

Specify Component Conversion Using Annotations

This section describes how to configure the serialization behavior of record components by using annotations. For a full list of supported annotations, see the org.bson.codecs.pojo.annotations package API documentation.

import org.bson.BsonType;
import org.bson.codecs.pojo.annotations.BsonProperty;
import org.bson.codecs.pojo.annotations.BsonId;
import org.bson.codecs.pojo.annotations.BsonRepresentation;
public record NetworkDeviceRecord(
        @BsonId()
        @BsonRepresentation(BsonType.OBJECT_ID)
        String deviceId,
        String name,
        @BsonProperty("type")
        String deviceType
        )
{}

MongoCollection<NetworkDeviceRecord> collection = database.getCollection("network_devices", NetworkDeviceRecord.class);
// insert the record
String deviceId = new ObjectId().toHexString();
collection.insertOne(new NetworkDeviceRecord(deviceId, "Enterprise Wi-fi", "router"));

{
  _id: ObjectId("fedc..."),
  name: 'Enterprise Wi-fi',
  type: 'router'
}

MongoCollection<NetworkDeviceRecord> collection = database.getCollection("network_devices", NetworkDeviceRecord.class);
// return all documents in the collection as records
List<NetworkDeviceRecord> records = new ArrayList<NetworkDeviceRecord>();
collection.find().into(records);
records.forEach(System.out::println);

NetworkDeviceRecord[deviceId=fedc..., name=Enterprise Wi-fi, deviceType=router]

Operations with Recursive Types

The driver natively supports encoding and decoding of recursively defined records without causing runtime recursion. This support extends to cycles of multiple record types in type definitions. The following code provides an example of a recursive record design:

public record RecordTree(
        String content,
        RecordTree left,
        RecordTree right
) {}

You can perform read and write operations on recursively defined records the same way you would for other records. The following code shows how you can execute a find operation on a collection of RecordTree types:

MongoDatabase database = mongoClient.getDatabase("myDB");
MongoCollection<RecordTree> collection = database.getCollection("myCollection", RecordTree.class);
Bson filter = Filters.eq("left.left.right.content", "Ikatere");
collection.find(filter).forEach(doc -> System.out.println(doc));

RecordTree[content=Ranginui, left=RecordTree[content=..., left=RecordTree[content=..., right=RecordTree[content=Ikatere...]]

Retrieve the Record Codec

You can use the RecordCodecProvider to retrieve the record codec. You should use this interface when you want to customize the codec to encode and decode Java record objects to and from corresponding BSON types while minimizing duplicate code. To learn more about codecs and their usage, see Codecs.

You can't create a record codec directly, but you can use the RecordCodecProvider to implement the record codec in your code. Learn more about the RecordCodecProvider, see the API documentation.