Specify a Query

Sample Data

The examples in this guide use the Movie entity, which represents the sample_mflix.movies collection from the Atlas sample datasets. The Movie entity has the following definition:

import com.mongodb.hibernate.annotations.ObjectIdGenerator;
import org.bson.types.ObjectId;
import java.time.Instant;
import java.util.List;
import jakarta.persistence.Embedded;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.OneToMany;
import jakarta.persistence.Table;
@Entity
@Table(name = "movies")
public class Movie {
   @Id
   @ObjectIdGenerator
   private ObjectId id;
   private String title;
   private String plot;
   private int year;
   private List<String> cast;
   private List<String> directors;
   private Instant released;
   @Embedded
   private Awards awards;
   @OneToMany(mappedBy = "movie", fetch = FetchType.LAZY)
   private List<Comment> comments;
   public Movie(String title, String plot, int year, List<String> cast, List<String> directors, Instant released, Awards awards) {
      this.title = title;
      this.plot = plot;
      this.year = year;
      this.cast = cast;
      this.directors = directors;
      this.released = released;
      this.awards = awards;
   }
   public Movie() {
   }
   public ObjectId getId() {
      return id;
   }
   public String getTitle() {
      return title;
   }
   public void setTitle(String title) {
      this.title = title;
   }
   public String getPlot() {
      return plot;
   }
   public void setPlot(String plot) {
      this.plot = plot;
   }
   public int getYear() {
      return year;
   }
   public void setYear(int year) {
      this.year = year;
   }
   public List<String> getCast() {
      return cast;
   }
   public void setCast(List<String> cast) {
      this.cast = cast;
   }
   public List<String> getDirectors() {
      return directors;
   }
   public void setDirectors(List<String> directors) {
      this.directors = directors;
   }
   public Awards getAwards() {
      return awards;
   }
   public void setAwards(Awards awards) {
      this.awards = awards;
   }
   public Instant getReleased() {
      return released;
   }
   public void setReleased(Instant released) {
      this.released = released;
   }
   public List<Comment> getComments() {
      return comments;
   }
   public void setComments(List<Comment> comments) {
      this.comments = comments;
   }
}

To learn how to create a Java application that uses the MongoDB Extension for Hibernate ORM to interact with this MongoDB sample collection, see the Get Started tutorial.

The code examples on this page also use the following Awards @Struct aggregate embeddable:

@Embeddable
@Struct(name = "Awards")
public class Awards {
    private int wins;
    private int nominations;
    private String text;
    public Awards(int wins, int nominations, String text) {
        this.wins = wins;
        this.nominations = nominations;
        this.text = text;
    }
    public Awards() {
    }
    public int getWins() {
        return wins;
    }
    public void setWins(int wins) {
        this.wins = wins;
    }
    public int getNominations() {
        return nominations;
    }
    public void setNominations(int nominations) {
        this.nominations = nominations;
    }
    public String getText() {
        return text;
    }
    public void setText(String text) {
        this.text = text;
    }
}

var sf = HibernateUtil.getSessionFactory();
Session session = sf.openSession();
Transaction tx = session.beginTransaction();
// ... Perform CRUD operations here
tx.commit();
session.close();
sf.close();

 // Replace <persistence unit> with the name of your persistence unit in the persistence.xml file
 EntityManagerFactory emf = Persistence.createEntityManagerFactory("<persistence unit>");
 EntityManager entityManager = entityManagerFactory.createEntityManager();
 entityManager.getTransaction().begin();
 // ... Perform CRUD operations here
entityManager.getTransaction().commit();
entityManager.close();
emf.close;

Compare Multiple Fields at Once

A row-value predicate compares a parenthesized list of fields to a parenthesized list of values in a single expression. The Hibernate ORM extension supports row-value predicates that use the following operators:

• =: Equality matching

• <>: Inequality matching

• IN and NOT IN: Matching against a list of value rows

You can supply the values as bound parameters or as literals, and each list must contain the same number of components.

The following example retrieves documents that have a title value of "Jurassic World" and a year value of 2015 from the sample_mflix.movies collection:

var rowValueResult = session.createQuery("from Movie where (title, year) = (:t, :y)", Movie.class)
                            .setParameter("t", "Jurassic World")
                            .setParameter("y", 2015)
                            .getResultList();
for (var m : rowValueResult) {
    System.out.println("Title: " + m.getTitle());
}

Title: Jurassic World

var rowValueResult = entityManager.createQuery("select m from Movie m where (m.title, m.year) = (:t, :y)", Movie.class)
                                  .setParameter("t", "Jurassic World")
                                  .setParameter("y", 2015)
                                  .getResultList();
for (var m : rowValueResult) {
    System.out.println("Title: " + m.getTitle());
}

Title: Jurassic World

The Hibernate ORM extension compares each pair of components separately. The preceding row-value predicate translates to the following $match stage:

{
  "$match": {
    "$and": [
      { "title": { "$eq": "Jurassic World" } },
      { "year": { "$eq": 2015 } }
    ]
  }
}

A row-value predicate that uses the <> operator translates to the same $and expression wrapped in a $nor expression.

If you compare the fields to another list of fields, as in where (title1, year1) = (title2, year2), the Hibernate ORM extension translates the predicate to a $expr expression instead.

You can use a row-value predicate in a SELECT clause. The predicate evaluates to a boolean value in the projection.

var rowValueInResult = session.createQuery(
                "from Movie where (title, year) in (('Jurassic World', 2015), ('Ex Machina', 2015))", Movie.class)
        .getResultList();
for (var m : rowValueInResult) {
    System.out.println("Title: " + m.getTitle());
}

Title: Jurassic World
Title: Ex Machina

var rowValueInResult = entityManager.createQuery(
                "select m from Movie m where (m.title, m.year) in (('Jurassic World', 2015), ('Ex Machina', 2015))", Movie.class)
        .getResultList();
for (var m : rowValueInResult) {
    System.out.println("Title: " + m.getTitle());
}

Title: Jurassic World
Title: Ex Machina

{
  "$match": {
    "$or": [
      { "$and": [
          { "title": { "$eq": "Jurassic World" } },
          { "year": { "$eq": 2015 } }
      ] },
      { "$and": [
          { "title": { "$eq": "Ex Machina" } },
          { "year": { "$eq": 2015 } }
      ] }
    ]
  }
}

Compare Field Values to Null

When you compare a field to null by using a comparison operator, the Hibernate ORM extension applies MongoDB Query Language null semantics instead of the ternary logic that Hibernate ORM defines.

MongoDB comparison operators evaluate both a missing field and a field that stores an explicit null value to null. As a result, a = null comparison matches documents in which the field stores null and documents in which the field is absent. A <> null or != null comparison matches documents in which the field stores any other value.

The following example uses the = operator to retrieve documents that have a null or missing cast value from the sample_mflix.movies collection:

var nullComparisonResult = session.createQuery("from Movie where cast = null", Movie.class)
        .getResultList();
for (var m : nullComparisonResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Song of Lahore
Title: A Sinner in Mecca
Title: Very Semi-Serious

var nullComparisonResult = entityManager.createQuery("select m from Movie m where m.cast = null", Movie.class)
        .getResultList();
for (var m : nullComparisonResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Song of Lahore
Title: A Sinner in Mecca
Title: Very Semi-Serious

The Hibernate ORM extension translates this query to the following $match stage:

{
  "$match": {
    "cast": { "$eq": null }
  }
}

Comparisons that use the >, >=, <, and <= operators follow the MongoDB BSON comparison order for non-existent fields. Because null is its own BSON type, A >= null or <= null comparison matches documents in which the field stores null or is missing. A > null or < null comparison matches no documents.

To match null and missing values by using a predicate instead of a comparison operator, see the IS NULL and IS NOT NULL sections of this guide.

Perform Arithmetic in a Projection

When you select a computed expression, the Hibernate ORM extension adds the computed value to the $project stage. If you assign the expression an alias by using the AS keyword, the Hibernate ORM extension uses the alias as the projection key. Otherwise, it generates a key in the form #c_<n>.

The following example computes the age of each "Hairspray" movie in the sample_mflix.movies collection by subtracting the year field value from a query parameter:

var arithmeticResult = session.createQuery(
                "select title, :currentYear - year as age from Movie where title = :title",
                Object[].class)
        .setParameter("currentYear", 2026)
        .setParameter("title", "Hairspray")
        .getResultList();
for (var row : arithmeticResult) {
    System.out.println("Title: " + row[0] + ", Age: " + row[1]);
}

Title: Hairspray, Age: 38
Title: Hairspray, Age: 19

var arithmeticResult = entityManager.createQuery(
                "select m.title, :currentYear - m.year as age from Movie m where m.title = :title",
                Object[].class)
        .setParameter("currentYear", 2026)
        .setParameter("title", "Hairspray")
        .getResultList();
for (var row : arithmeticResult) {
    System.out.println("Title: " + row[0] + ", Age: " + row[1]);
}

Title: Hairspray, Age: 38
Title: Hairspray, Age: 19

The Hibernate ORM extension translates the preceding computed expression to the following $project stage:

{
  "$project": {
    "title": true,
    "age": { "$subtract": [ 2026, "$year" ] },
    "_id": 0
  }
}

Filter on a Computed Expression

In the WHERE clause, you can compare a computed expression to a value or compare two field values to each other. When either side of a comparison is not a direct field reference or value, the Hibernate ORM extension wraps the comparison in the MongoDB $expr operator. Comparisons between a field and a value continue to use the compact { field: { operator: value } } form.

The following example retrieves "Hairspray" movies released fewer than 20 years before 2026:

var computedFilterResult = session.createQuery(
                "from Movie where title = :title and :currentYear - year < 20", Movie.class)
        .setParameter("title", "Hairspray")
        .setParameter("currentYear", 2026)
        .getResultList();
for (var m : computedFilterResult) {
    System.out.println("Title: " + m.getTitle() + ", Year: " + m.getYear());
}

Title: Hairspray, Year: 2007

var computedFilterResult = entityManager.createQuery(
                "select m from Movie m where m.title = :title and :currentYear - m.year < 20",
                Movie.class)
        .setParameter("title", "Hairspray")
        .setParameter("currentYear", 2026)
        .getResultList();
for (var m : computedFilterResult) {
    System.out.println("Title: " + m.getTitle() + ", Year: " + m.getYear());
}

Title: Hairspray, Year: 2007

The Hibernate ORM extension translates the preceding query to the following $match stage, in which the title comparison uses the compact form and the computed comparison uses $expr:

{
  "$match": {
    "$and": [
      { "title": { "$eq": "Hairspray" } },
      { "$expr": { "$lt": [ { "$subtract": [ 2026, "$year" ] }, 20 ] } }
    ]
  }
}

Project a Comparison Result

You can use a comparison in a SELECT statement to return its boolean result instead of using the comparison as a filter.

The following example returns the title of each "Hairspray" movie and whether the movie was released after 2000:

var comparisonResult = session.createQuery(
                "select title, year > 2000 as isRecent from Movie where title = :title",
                Object[].class)
        .setParameter("title", "Hairspray")
        .getResultList();
for (var row : comparisonResult) {
    System.out.println("Title: " + row[0] + ", Recent: " + row[1]);
}

Title: Hairspray, Recent: false
Title: Hairspray, Recent: true

var comparisonResult = entityManager.createQuery(
                "select m.title, m.year > 2000 as isRecent from Movie m where m.title = :title",
                Object[].class)
        .setParameter("title", "Hairspray")
        .getResultList();
for (var row : comparisonResult) {
    System.out.println("Title: " + row[0] + ", Recent: " + row[1]);
}

Title: Hairspray, Recent: false
Title: Hairspray, Recent: true

The Hibernate ORM extension translates the preceding comparison to the following $project stage:

{
  "$project": {
    "title": true,
    "isRecent": { "$gt": [ "$year", 2000 ] },
    "_id": 0
  }
}

EXISTS

The EXISTS predicate matches documents that have a specific field and returns only one result for each matching parent document, regardless of how many array elements match.

For a full example, see the Query on Elements of an Embedded Array section of this guide.

BETWEEN

The BETWEEN predicate matches documents that have a field value within a specified range.

The following example uses the BETWEEN predicate to retrieves documents that have a year value between 2012 and 2013, inclusive, from the sample_mflix.movies collection:

var betweenResult = session.createQuery("from Movie where year between :start and :end", Movie.class)
                           .setParameter("start", 2012)
                           .setParameter("end", 2013)
                           .getResultList();
for (var m : betweenResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Absent Minded
Title: The Disappearance of Eleanor Rigby: Her
Title: Thread of Lies

var betweenResult = entityManager.createQuery("select m from Movie m where m.year between :start and :end", Movie.class)
                                 .setParameter("start", 2012)
                                 .setParameter("end", 2013)
                                 .getResultList();
for (var m : betweenResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Absent Minded
Title: The Disappearance of Eleanor Rigby: Her
Title: Thread of Lies

The Hibernate ORM extension translates the preceding BETWEEN predicate to the following $match stage:

{
  "$match": {
    "year": { "$gte": 2012, "$lte": 2013 }
  }
}

IN

The IN predicate matches documents where a field value equals any value in a specified list. You can supply the list values as literals, named parameters, or positional parameters.

The following example uses the IN predicate to retrieve documents that have a year value of either 1994 or 1996 from the sample_mflix.movies collection:

var inResult = session.createQuery("from Movie where year in (:first, :second)", Movie.class)
                      .setParameter("first", 1994)
                      .setParameter("second", 1996)
                      .getResultList();
for (var m : inResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Kadhal Kottai
Title: Gotti
Title: It's Just a Ride

var inResult = entityManager.createQuery("select m from Movie m where m.year in (:first, :second)", Movie.class)
                            .setParameter("first", 1994)
                            .setParameter("second", 1996)
                            .getResultList();
for (var m : inResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Kadhal Kottai
Title: Gotti
Title: It's Just a Ride

The Hibernate ORM extension translates the preceding IN predicate to the following $match stage:

{
  "$match": {
    "year": { "$in": [ 1994, 1996 ] }
  }
}

An empty list is valid, but it never matches any documents. For example, year in () matches no documents.

NOT IN

The NOT IN predicate matches documents in which a field value does not equal any value in a specified list. NOT IN accepts the same list forms and has the same limitations as the IN predicate.

The following example uses the NOT IN predicate to retrieve documents that have a title value other than "Romeo and Juliet" or "Best in Show" from the sample_mflix.movies collection. Because NOT IN excludes only the listed values, the example calls the setMaxResults() method to limit the result set to ten documents:

var notInResult = session.createQuery("from Movie where title not in (:first, :second)", Movie.class)
                         .setParameter("first", "Romeo and Juliet")
                         .setParameter("second", "Best in Show")
                         .setMaxResults(10)
                         .getResultList();
for (var m : notInResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: 'R Xmas
Title: 'Round Midnight
Title: 'Til Madness Do Us Part

var notInResult = entityManager.createQuery("select m from Movie m where m.title not in (:first, :second)", Movie.class)
                               .setParameter("first", "Romeo and Juliet")
                               .setParameter("second", "Best in Show")
                               .setMaxResults(10)
                               .getResultList();
for (var m : notInResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: 'R Xmas
Title: 'Round Midnight
Title: 'Til Madness Do Us Part

The Hibernate ORM extension translates the preceding NOT IN predicate to the following $match stage:

{
  "$match": {
    "title": { "$nin": [ "Romeo and Juliet", "Best in Show" ] }
  }
}

Because $nin matches every document against an empty list of values, title not in () matches all documents.

IS NULL

The IS NULL predicate matches documents that have a specific field with a null or missing value.

To compare a field to null by using a comparison operator instead of a predicate, see the Compare Field Values to Null section of this guide.

The following example uses the IS NULL predicate to retrieve documents that have a missing or null cast value from the sample_mflix.movies collection:

var isNullResult = session.createQuery("from Movie where cast is null", Movie.class)
        .getResultList();
for (var m : isNullResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Tom Swift and His Electric Rifle
Title: A Sinner in Mecca
Title: Very Semi-Serious

var isNullResult = entityManager.createQuery("select m from Movie m where m.cast is null", Movie.class)
        .getResultList();
for (var m : isNullResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Tom Swift and His Electric Rifle
Title: A Sinner in Mecca
Title: Very Semi-Serious

The Hibernate ORM extension translates the preceding IS NULL predicate to the following $match stage, which matches documents where the field is explicitly null or missing:

{
  "$match": {
    "cast": { "$eq": null }
  }
}

IS NOT NULL

The IS NOT NULL predicate matches documents that have a field with a non-null or non-missing value.

The following example uses the IS NOT NULL predicate to retrieve documents that have a directors value from the sample_mflix.movies collection:

var isNotNullResult = session.createQuery("from Movie where directors is not null", Movie.class)
        .getResultList();
for (var m : isNotNullResult) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Our Loved Ones
Title: No Home Movie
Title: Scenes of a Sexual Nature

var isNotNullResultEm = entityManager.createQuery("select m from Movie m where m.directors is not null", Movie.class)
        .getResultList();
for (var m : isNotNullResultEm) {
    System.out.println("Title: " + m.getTitle());
}

...
Title: Our Loved Ones
Title: No Home Movie
Title: Scenes of a Sexual Nature

The Hibernate ORM extension translates the preceding IS NOT NULL predicate to the following $match stage, which matches documents where the field exists and is not explicitly null:

{
  "$match": {
    "directors": { "$ne": null }
  }
}

Query a Field on an Embedded Document

You can reference a field on an embeddable type by using a dotted path expression in the SELECT, WHERE, ORDER BY, and UPDATE clauses of an HQL or JPQL query. You can also chain multiple embeddable names in a path expression to reference a field on a nested embeddable within another embeddable.

The following example uses a path expression to filter documents in the sample_mflix.movies collection. There are two "Hairspray" movies in the sample_mflix.movies collection. One "Hairspray" movie is from 1998, and the other is from 2007. The query matches documents that have a title value of "Hairspray" and an awards.wins value greater than 10:

var matchingDocument = session.createQuery("from Movie where title = :title and awards.wins > :minWins", Movie.class)
        .setParameter("title", "Hairspray")
        .setParameter("minWins", 10)
        .getResultList();
for (var m : matchingDocument) {
    System.out.println("Title: " + m.getTitle() + ", Year: " + m.getYear());
}

Title: Hairspray, Year: 2007

var matchingDocument = entityManager.createQuery("select m from Movie m where m.title = :title and m.awards.wins > :minWins", Movie.class)
        .setParameter("title", "Hairspray")
        .setParameter("minWins", 10)
        .getResultList();
for (var m : matchingDocument) {
    System.out.println("Title: " + m.getTitle() + ", Year: " + m.getYear());
}

Title: Hairspray, Year: 2007

Query on Elements of an Embedded Array

When a field of your entity stores an array of @Struct aggregate embeddables, you can use an EXISTS subquery to match parent documents in which at least one element of that array meets your criteria. The Hibernate ORM extension translates the subquery to the MongoDB $elemMatch operator, which applies all criteria to the same array element.

package org.example;
import com.mongodb.hibernate.annotations.ObjectIdGenerator;
import jakarta.persistence.Column;
import org.bson.types.ObjectId;
import java.util.List;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
@Entity
@Table(name = "restaurants")
public class Restaurant {
    @Id
    @ObjectIdGenerator
    @Column(name = "_id")
    private ObjectId id;
    private String name;
    private String borough;
    private List<Grade> grades;
    public Restaurant(String name, String borough, List<Grade> grades) {
        this.name = name;
        this.borough = borough;
        this.grades = grades;
    }
    public Restaurant() {
    }
    public ObjectId getId() {
        return id;
    }
    public void setId(ObjectId id) {
        this.id = id;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getBorough() {
        return borough;
    }
    public void setBorough(String borough) {
        this.borough = borough;
    }
    public List<Grade> getGrades() {
        return grades;
    }
    public void setGrades(List<Grade> grades) {
        this.grades = grades;
    }
}

package org.example;
import jakarta.persistence.*;
import org.hibernate.annotations.Struct;
@Embeddable
@Struct(name = "Grade")
public class Grade {
    private String grade;
    private int score;
    public Grade() {
        
    }
    public Grade(String grade, int score) {
        this.grade = grade;
        this.score = score;
    }
    public String getGrade() {
        return grade;
    }
    public void setGrade(String grade) {
        this.grade = grade;
    }
    public int getScore() {
        return score;
    }
    public void setScore(int score) {
        this.score = score;
    }
}

{
  "_id": { "$oid": "5eb3d668b31de5d588f4292a" },
  "name": "Morris Park Bake Shop",
  "borough": "Bronx",
  "cuisine": "Bakery",
  "grades": [
    { "date": { "$date": 1393804800000 }, "grade": "A", "score": 2 },
    { "date": { "$date": 1299715200000 }, "grade": "B", "score": 14 }
  ]
}

var existsResult = session.createQuery(
                "from Restaurant r where exists (select g.grade from r.grades g where g.grade = :grade and g.score = :score)",
                Restaurant.class)
        .setParameter("grade", "B")
        .setParameter("score", 12)
        .getResultList();
for (var r : existsResult) {
    System.out.println("Name: " + r.getName());
}

Name: Sam'S Restaurant
Name: Nb. National Bakery
Name: Sapporo Ichiban

var existsResultEm = entityManager.createQuery(
                "select r from Restaurant r where exists (select g.grade from r.grades g where g.grade = :grade and g.score = :score)",
                Restaurant.class)
        .setParameter("grade", "B")
        .setParameter("score", 12)
        .getResultList();
for (var r : existsResultEm) {
    System.out.println("Name: " + r.getName());
}

Name: Sam'S Restaurant
Name: Nb. National Bakery
Name: Sapporo Ichiban

{
  "$match": {
    "grades": {
      "$elemMatch": {
        "grade": { "$eq": "B" },
        "score": { "$eq": 12 }
      }
    }
  }
}