Unique Field in MongoDB Document in Spring Data

1. Introduction

In this tutorial, we’re going to learn how to define a unique field in MongoDB using Spring Data. Unique fields are an essential part of the DB design. They guarantee consistency and performance at the same time, preventing duplicate values where there shouldn’t be.

2. Configuration

Unlike relational databases, MongoDB does not offer the option to create constraints. Therefore, our only option is to create unique indexes. However, automatic index creation in Spring Data is turned off by default. Firstly, let’s go ahead and turn it on in our application.properties:

spring.data.mongodb.auto-index-creation=true

With that configuration, indexes will be created on boot time if they do not yet exist. But, we have to remember that we cannot create a unique index after we already have duplicate values. This would result in an exception being thrown during the startup of our application.

3. The @Indexed Annotation

The @Indexed annotation allows us to mark fields as having an index. And since we configured automatic index creation, we won’t have to create them ourselves. By default, an index is not unique. Therefore, we have to turn it on via the unique property. Let’s see it in action by creating our first example:

@Document
public class Company {
    @Id
    private String id;

    private String name;

    @Indexed(unique = true)
    private String email;

    // getters and setters
}

Notice we can still have our @Id annotation, which is completely independent of our index. And that’s all we need to have a document with a unique field. As a result, if we insert more than one document with the same email, it will result in a DuplicateKeyException:

@Test
public void givenUniqueIndex_whenInsertingDupe_thenExceptionIsThrown() {
    Company a = new Company();
    a.setName("Name");
    a.setEmail("[email protected]");

    companyRepo.insert(a);

    Company b = new Company();
    b.setName("Other");
    b.setEmail("[email protected]");
    assertThrows(DuplicateKeyException.class, () -> {
        companyRepo.insert(b);
    });
}

This approach is useful when we want to enforce uniqueness but still have a unique ID field generated automatically.

3.1. Annotating Multiple Fields

We can also add the annotation to multiple fields. Let’s go ahead and create our second example:

@Document
public class Asset {
    @Indexed(unique = true)
    private String name;

    @Indexed(unique = true)
    private Integer number;
}

Notice we’re not explicitly setting @Id on any field. MongoDB will still set an “_id” field for us automatically, but it won’t be accessible to our application. But, we cannot put the @Id along with a @Indexed annotation marked as unique on the same field. It would throw an exception when the application tried to create the index.

Also, now we have two unique fields. Note that this does not mean that it’s a compound index. Consequently, multiple inserts of the same value for any of the fields will result in a duplicate key. Let’s test it:

@Test
public void givenMultipleIndexes_whenAnyFieldDupe_thenExceptionIsThrown() {
    Asset a = new Asset();
    a.setName("Name");
    a.setNumber(1);

    assetRepo.insert(a);

    assertThrows(DuplicateKeyException.class, () -> {
        Asset b = new Asset();
        b.setName("Name");
        b.setNumber(2);

        assetRepo.insert(b);
    });

    assertThrows(DuplicateKeyException.class, () -> {
        Asset b = new Asset();
        b.setName("Other");
        b.setNumber(1);

        assetRepo.insert(b);
    });
}

If we want only the combined values to form a unique index, we have to create a compound index.

3.2. Using a Custom Type as an Index

Similarly, we can annotate a field of a custom type. That will achieve the effect of a compound index. Let’s start with a SaleId class to represent our compound index:

public class SaleId {
    private Long item;
    private String date;

    // getters and setters
}

Let’s now create our Sale class to make use of it:

@Document
public class Sale {
    @Indexed(unique = true)
    private SaleId saleId;

    private Double value;

    // getters and setters
}

Now, every time we try to add a new Sale with the same SaleId, we’ll get a duplicate key. Let’s test it:

@Test
public void givenCustomTypeIndex_whenInsertingDupe_thenExceptionIsThrown() {
    SaleId id = new SaleId();
    id.setDate("2022-06-15");
    id.setItem(1L);

    Sale a = new Sale(id);
    a.setValue(53.94);

    saleRepo.insert(a);

    assertThrows(DuplicateKeyException.class, () -> {
        Sale b = new Sale(id);
        b.setValue(100.00);

        saleRepo.insert(b);
    });
}

This approach has the advantage of keeping the index definition separate. This allows us to include or remove new fields from SaleId without having to recreate or update our index. It’s also very similar to a composite key. But, indexes differ from keys because they can have one null value.

4. The @CompoundIndex Annotation

To have a unique index comprised of multiple fields without a custom class, we have to create a compound index. For that, we use the @CompoundIndex annotation directly in our class. This annotation contains a def property that we’ll use to include the fields we need. Let’s create our Customer class defining a unique index for the storeId and number fields:

@Document
@CompoundIndex(def = "{'storeId': 1, 'number': 1}", unique = true)
public class Customer {
    @Id
    private String id;

    private Long storeId;
    private Long number;
    private String name;

    // getters and setters
}

This differs from @Indexed on multiple fields. This approach only results in a DuplicateKeyException if we try inserting a customer with the same storeId and number values:

@Test
public void givenCompoundIndex_whenDupeInsert_thenExceptionIsThrown() {
    Customer customerA = new Customer("Name A");
    customerA.setNumber(1l);
    customerA.setStoreId(2l);

    Customer customerB = new Customer("Name B");
    customerB.setNumber(1l);
    customerB.setStoreId(2l);

    customerRepo.insert(customerA);

    assertThrows(DuplicateKeyException.class, () -> {
        customerRepo.insert(customerB);
    });
}

With this approach, we have the advantage of not having to create another class just for our index. Also, it’s possible to add the @Id annotation to a field from the compound index definition. However, different from @Indexed, it won’t result in an exception.

5. Conclusion

In this article, we learned how to define unique fields for our documents. Consequently, we learned that our only option is to use unique indexes. Also, using Spring Data, we can easily configure our application to automatically create our indexes. And, we saw the many ways to use the @Indexed and @CompoundIndex annotations.