Data Serialization

Supported Types

The Kotlin Sync driver supports the following types:

• All Kotlin types that are supported by the kotlinx.serialization library

• All BSON types

Query Annotated Classes

You can query annotated data classes by using the Filters class from the mongodb-driver-kotlin-extensions package. This class allows you to create query filters on field names annotated with the @SerialName annotation.

The following example queries the orders collection for documents that have a brand field value of "Sherwin-Williams":

val queryFilter = eq(PaintOrder::manufacturer, "Sherwin-Williams")
val results = collection.find(queryFilter).toList()

The preceding code creates a query filter that references the PaintOrder::manufacturer property but queries the brand BSON field. The driver automatically converts the data class property name to the field name specified in the @SerialName annotation.

Custom Serializer Example

You can create a custom serializer to handle how your data is represented in BSON. The Kotlin Sync driver uses the KSerializer interface from the kotlinx.serialization library to implement custom serializers. You can specify the custom serializer as the parameter to the @Serializable annotation for a specific field.

The following example shows how to create a custom KSerializer instance to convert a kotlinx.datetime.Instant to a BsonDateTime:

object InstantAsBsonDateTime : KSerializer<Instant> {
    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("InstantAsBsonDateTime", PrimitiveKind.LONG)
    override fun serialize(encoder: Encoder, value: Instant) {
        when (encoder) {
            is BsonEncoder -> encoder.encodeBsonValue(BsonDateTime(value.toEpochMilli()))
            else -> throw SerializationException("Instant is not supported by ${encoder::class}")
        }
    }
    override fun deserialize(decoder: Decoder): Instant {
        return when (decoder) {
            is BsonDecoder -> Instant.ofEpochMilli(decoder.decodeBsonValue().asDateTime().value)
            else -> throw SerializationException("Instant is not supported by ${decoder::class}")
        }
    }
}

The following code shows the PaintOrder data class in which the orderDate field has an annotation that specifies the custom serializer class defined in the preceding code:

@Serializable
data class PaintOrder(
    val color: String,
    val qty: Int,
    @Serializable(with = InstantAsBsonDateTime::class)
    val orderDate: Instant,
)

To learn more about the methods and classes mentioned in this section, see the following API documentation:

• KSerializer in the Kotlin documentation

• Instant in the Kotlin documentation

• BsonEncoder

• BsonDecoder

Custom Codec Example

The following example shows how to create a codec by using the KotlinSerializerCodec.create() method and then configure it to not encode defaults:

val myCustomCodec = KotlinSerializerCodec.create<PaintOrder>(
    bsonConfiguration = BsonConfiguration(encodeDefaults = false)
)
val registry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(myCustomCodec), collection.codecRegistry
)

Implement Snake Case Naming Strategy

When using bson-kotlinx package v5.4 or later, you can direct the driver to serialize data class fields names written in camel case to snake case in MongoDB. The following example shows how to create and register a custom codec to convert data class field names into snake case by setting the bsonNamingStrategy parameter in a codec:

val myCustomCodec = KotlinSerializerCodec.create<PaintOrder>(
    bsonConfiguration = BsonConfiguration(bsonNamingStrategy = BsonNamingStrategy.SNAKE_CASE)
)
val registry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(myCustomCodec), collection.codecRegistry
)

To learn more about the methods and classes mentioned in this section, see the following API documentation:

• KotlinSerializerCodec

• KotlinSerializerCodec.create()

• BsonConfiguration

• BsonNamingStrategy

Polymorphic Data Classes Example

The following example creates an interface and two data classes that inherit that interface. In the data classes, the id field is marked with the annotations described in the Annotate Data Classes section:

@Serializable
sealed interface Person {
    val name: String
}
@Serializable
data class Student(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val grade: Int,
) : Person
@Serializable
data class Teacher(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val department: String,
) : Person

Then, you can perform operations with data classes as usual. The following example parametrizes the collection with the Person interface, then performs operations with the polymorphic classes Teacher and Student. When you retrieve documents, the driver automatically detects the type based on the discriminator value and deserializes them accordingly.

val collection = database.getCollection<Person>("school")
val teacherDoc = Teacher(ObjectId(), "Vivian Lee", "History")
val studentDoc = Student(ObjectId(), "Kate Parker", 10)
collection.insertOne(teacherDoc)
collection.insertOne(studentDoc)
println("Retrieving by using data classes")
val resultTeacher = collection.withDocumentClass<Teacher>()
    .find(Filters.exists("department"))
    .firstOrNull()
println(resultTeacher)
val resultStudent = collection.withDocumentClass<Student>()
    .find(Filters.exists("grade"))
    .firstOrNull()
println(resultStudent)
println("\nRetrieving by using Person interface")
val resultsPerson = collection.withDocumentClass<Person>().find()
resultsPerson.forEach { result ->
    println(result)
}
println("\nRetrieving as Document type")
val resultsDocument = collection.withDocumentClass<Document>().find()
resultsDocument.forEach { result ->
    println(result)
}

Retrieving by using data classes
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving by using Person interface
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving as Document type
Document{{_id=..., _t=Teacher, name=Vivian Lee, department=History}}
Document{{_id=..., _t=Student, name=Kate Parker, grade=10}}

kotlinx-datetime Library

kotlinx-datetime is a Kotlin library that offers a high level of control over how your date and time values are serialized. To use the library, add the kotlinx-datetime dependency to your project's dependency list.

Select from the following tabs to see how to add the kotlinx-datetime dependency to your project by using the Gradle and Maven package managers:

implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-datetime-jvm</artifactId>
    <version>0.6.1</version>
</dependency>

To learn more about this library, see the kotlinx-datetime repository on GitHub.

Example Data Class with Dates and Times

After you add the library dependency, you can implement serializers from the kotlinx-datetime library that map your data class field values to the expected types in BSON.

In this example, the driver serializes the fields of the Appointment data class with the following behavior:

• name: The driver serializes the value as a string.

• date: The driver uses the kotlinx-datetime serializer because the field has the @Contextual annotation. LocalDate values are serialized as BSON dates.

• time: The driver serializes the value as a string because it does not have the @Contextual annotation. This is the default serialization behavior for LocalTime values.

@Serializable
data class Appointment(
    val name: String,
    @Contextual val date: LocalDate,
    val time: LocalTime,
)

The following example inserts an instance of the Appointment data class into the appointments collection:

val collection = database.getCollection<Appointment>("appointments")
val apptDoc = Appointment(
    "Daria Smith",
    LocalDate(2024, 10, 15),
    LocalTime(hour = 11, minute = 30)
)
collection.insertOne(apptDoc)

In MongoDB, the LocalDate value is stored as a BSON date, and the time field is stored as a string by default serialization:

{
  "_id": ...,
  "name": "Daria Smith",
  "date": {
    "$date": "2024-10-15T00:00:00.000Z"
  },
  "time": "11:30",
}