Overview
En esta guía, puede aprender cómo llamar a las funciones extract() y format() de Hibernate languaje del query (HQL) en un campo de fecha y hora mediante el uso de la extensión de MongoDB para Hibernate ORM. Puede utilizar extract() para devolver parte de un valor de fecha y hora y format() para renderizar un valor de fecha y hora como una string.
La extensión Hibernate ORM traduce cada llamar a una expresión de agregación de MongoDB en la etapa $project. Puede llamar a cualquiera de las dos funciones en un campo de fecha y hora en una cláusula SELECT.
Nota
Zona horaria
La extensión Hibernate ORM resuelve cada función de fecha y hora en la zona horaria por defecto de la JVM que ejecuta la aplicación. Pasa esa zona a MongoDB como el argumento timezone del operador generado. La misma query puede devolver diferentes valores en los host configurados con diferentes zonas horarias.
Como la extensión Hibernate ORM no admite llamar a funciones como operandos de una expresión calculada, no puede combinar una función de fecha y hora con un operador aritmético. Para obtener más información, consulte la sección Usar expresiones calculadas de la guía Especificar una query.
Datos de muestra
Los ejemplos de esta guía utilizan la entidad Movie, que representa la colección sample_mflix.movies del conjuntos de datos de muestras de Atlas. La entidad Movie tiene la siguiente definición:
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; }}Para aprender a crear una aplicación Java que utilice la extensión MongoDB para Hibernate ORM para interactuar con esta colección de muestra de MongoDB, consulta el tutorial Primeros pasos.
Los ejemplos de esta guía utilizan el campo released de la entidad Movie, que almacena un valor Instant.
Extraer un campo de fecha y hora
Puede utilizar la función extract() para devolver una parte específica de un valor de fecha y hora, como el año, el mes o el día.
La función extract(field from x) devuelve un único campo de un valor de fecha y hora. La extensión Hibernate ORM admite los siguientes valores para el field:
Campo | Traducción de MongoDB |
|---|---|
|
|
| Calculado dividiendo |
|
|
|
|
| Calculado a partir de |
| Calculado a partir de |
|
|
|
|
|
|
|
|
|
|
| Calculado a partir de |
| Calculado a partir de |
| Calculado como la cantidad de segundos enteros desde el Unix epoch |
El siguiente ejemplo devuelve el título de cada película "Hairspray" en la colección sample_mflix.movies y el año en que se estrenó la película:
var extractResult = session.createQuery( "select title, extract(year from released) as releaseYear from Movie where title = :title", Object[].class) .setParameter("title", "Hairspray") .getResultList();for (var row : extractResult) { System.out.println("Title: " + row[0] + ", Release Year: " + row[1]);}var extractResult = entityManager.createQuery( "select m.title, extract(year from m.released) as releaseYear from Movie m where m.title = :title", Object[].class) .setParameter("title", "Hairspray") .getResultList();for (var row : extractResult) { System.out.println("Title: " + row[0] + ", Release Year: " + row[1]);}La extensión Hibernate ORM traduce la query anterior a la siguiente etapa $project, en la que America/New_York es la zona horaria por defecto de la JVM:
{ "$project": { "title": true, "releaseYear": { "$year": { "date": "$released", "timezone": { "$literal": "America/New_York" } } }, "_id": 0 }}Importante
Numeración del día de la semana
El campo day of week devuelve el valor $dayOfWeek de MongoDB, que numera los días desde 1 para el domingo hasta 7 para el sábado. Esto difiere del enum Java DayOfWeek, que numera los días del 1 para el lunes al 7 para el domingo.
La extensión Hibernate ORM no es compatible con los campos date, time, offset, timezone_hour y timezone_minute. Una query que extrae un campo no admitido genera un FeatureNotSupportedException.
Dar formato a una fecha y hora como un string
La función format(x as pattern) renderiza un valor de fecha y hora como una string. La extensión Hibernate ORM traduce llamar al operador MongoDB $dateToString y asigna cada código de patrón al especificador de formato MongoDB equivalente. También puede llamar a la función como format(x, pattern) y pasar especificadores de formato de MongoDB directamente.
La extensión Hibernate ORM admite los siguientes códigos de patrón:
Código de patrón | Descripción | Especificador de MongoDB |
|---|---|---|
| Año de cuatro dígitos |
|
| Año de cuatro dígitos basado en la semana ISO-8601 |
|
| Mes de dos dígitos |
|
| Nombre del mes abreviado |
|
| Nombre completo del mes |
|
| Número de semana ISO-8601 de dos dígitos |
|
| Día del mes de dos dígitos |
|
| Día del año |
|
| Hora de dos dígitos en un reloj de 24horas |
|
| Minuto de dos dígitos |
|
| Segundo de dos dígitos |
|
| Milisegundo de tres dígitos |
|
| Desplazamiento UTC |
|
MongoDB devuelve los nombres de los meses y los días en la localización de EE. UU. Los caracteres que encierra entre comillas simples pasan a la salida sin interpretarse como códigos de patrón.
El siguiente ejemplo devuelve el título de cada película "Hairspray" y su fecha de lanzamiento como una string yyyy-MM-dd:
var formatResult = session.createQuery( "select title, format(released as 'yyyy-MM-dd') as releaseDate from Movie where title = :title", Object[].class) .setParameter("title", "Hairspray") .getResultList();for (var row : formatResult) { System.out.println("Title: " + row[0] + ", Release Date: " + row[1]);}Si desea utilizar especificadores de formato de MongoDB en su lugar, puede llamar a la función como format(released, '%Y-%m-%d').
var formatResult = entityManager.createQuery( "select m.title, format(m.released as 'yyyy-MM-dd') as releaseDate from Movie m where m.title = :title", Object[].class) .setParameter("title", "Hairspray") .getResultList();for (var row : formatResult) { System.out.println("Title: " + row[0] + ", Release Date: " + row[1]);}Si desea utilizar especificadores de formato de MongoDB en su lugar, puede llamar a la función como format(m.released, '%Y-%m-%d').
La extensión Hibernate ORM traduce la query anterior a la siguiente etapa $project:
{ "$project": { "title": true, "releaseDate": { "$dateToString": { "date": "$released", "format": { "$literal": "%Y-%m-%d" }, "timezone": { "$literal": "America/New_York" } } }, "_id": 0 }}Una query que utiliza un código de patrón fuera de la tabla anterior lanza un FeatureNotSupportedException. Esto incluye códigos de un solo carácter y de ancho variable como y, M, d, H, h, m, s y a, porque MongoDB no tiene un especificador equivalente para ellos. Un código de zona horaria repetido de más de tres caracteres, como ZZZZZZZ, es ambiguo y también genera una excepción.
Información Adicional
Para obtener más información sobre la creación de filtros de query y el uso de operadores en sus instrucciones de query, consulte la guía Especificar una query.
Para aprender más sobre el uso de HQL y JPQL para ejecutar queries, consulte Una guía sobre el languaje del query de Hibernate en la documentación de Hibernate ORM.