Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Usar funciones de fecha y hora en query

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.

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.

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

year

$year

quarter

Calculado dividiendo $month entre 3 y redondeando al alza

month

$month

week

$isoWeek, que devuelve el número de semana ISO-8601

week of year

Calculado a partir de $dayOfYear y $dayOfWeek como un número de semana basado en el domingo

week of month

Calculado a partir de $dayOfMonth y $dayOfWeek como un número de semana basado en el domingo

day, day of month

$dayOfMonth

day of week

$dayOfWeek

day of year

$dayOfYear

hour

$hour

minute

$minute

second

Calculado a partir de $second y $millisecond como un número fraccionario de segundos

nanosecond

Calculado a partir de $second y $millisecond

epoch

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]);}

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.

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

yyyy

Año de cuatro dígitos

%Y

YYYY

Año de cuatro dígitos basado en la semana ISO-8601

%G

MM

Mes de dos dígitos

%m

MMM

Nombre del mes abreviado

%b

MMMM

Nombre completo del mes

%B

ww

Número de semana ISO-8601 de dos dígitos

%V

dd

Día del mes de dos dígitos

%d

DDD

Día del año

%j

HH

Hora de dos dígitos en un reloj de 24horas

%H

mm

Minuto de dos dígitos

%M

ss

Segundo de dos dígitos

%S

SSS

Milisegundo de tres dígitos

%L

Z, ZZ, ZZZ, xx

Desplazamiento UTC

%z

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').

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.

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.