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.

Utilizar funciones de string en las query

En esta guía, puede aprender a llamar a funciones de string de Hibernate languaje del query (HQL) en un campo de string mediante el uso de la extensión de MongoDB para Hibernate ORM. Las funciones de string le permiten medir, reformatear y combinar valores de string como parte de una query.

Puede llamar a cada función en una cláusula SELECT. La extensión de Hibernate ORM traduce cada llamada a función a una expresión de agregación de MongoDB en la etapa $project. Dado que la extensión Hibernate ORM no admite llamadas a funciones como operandos de una expresión calculada, no se puede combinar una función de string con un operador aritmético.

La extensión Hibernate ORM admite las siguientes funciones de string:

Función
Traducción de MongoDB

length(), character_length(), char_length()

upper()

lower()

concat(), ||

substring()

locate()

replace()

trim()

$trim, $ltrim o $rtrim, según la dirección de recorte especificada

pad(), lpad(), rpad()

Calculado a partir de $strLenCP, $substrCP, y $concat

repeat()

Calculado a partir de $range y $reduce

Nota

Funciones de string no compatibles

La extensión Hibernate ORM no admite las funciones de string HQL position(), overlay(), left(), right() y collate(). Una query que llama a una de estas funciones lanza un FeatureNotSupportedException.

Para usar una función de string no compatible, llame al método createNativeQuery() e incluya el operador relevante en su instrucción de MongoDB languaje del query. Para más información, consulte la guía Realizar queries nativas de base de datos.

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 title de la entidad Movie, que almacena un valor String.

La función length(str) devuelve el número de caracteres de una string. También puede llamar a esta función como character_length(str) o char_length(str), que son alias para la misma función. Dado que la extensión Hibernate ORM traduce llamar al operador $strLenCP, la función cuenta puntos de código Unicode en lugar de bytes.

El siguiente ejemplo devuelve el título de la película "The Hunger Games" en la colección sample_mflix.movies y la longitud del título:

var lengthResult = session.createQuery( "select title, length(title) as titleLength from Movie where title = :title", Object[].class) .setParameter("title", "The Hunger Games") .getResultList();for (var row : lengthResult) { System.out.println("Title: " + row[0] + ", Length: " + row[1]);}

La extensión Hibernate ORM traduce la query anterior a la siguiente etapa $project:

{ "$project": { "title": true, "titleLength": { "$strLenCP": "$title" }, "_id": 0 }}

Las funciones upper(str) y lower(str) convierten una string a mayúsculas o minúsculas.

El siguiente ejemplo devuelve el título de la película "The Hunger Games" en mayúsculas:

var upperResult = session.createQuery( "select upper(title) as upperTitle from Movie where title = :title", String.class) .setParameter("title", "The Hunger Games") .getResultList();for (var upperTitle : upperResult) { System.out.println("Uppercase Title: " + upperTitle);}

La extensión Hibernate ORM traduce la query anterior a la siguiente etapa $project:

{ "$project": { "upperTitle": { "$toUpper": "$title" }, "_id": 0 }}

La función concat(x, y) une dos o más valores en una sola string. La extensión Hibernate ORM convierte cada operando en una string antes de unirse, para que pueda concatenar valores numéricos o concatenar un valor numérico a un valor de string.

El siguiente ejemplo añade un punto de exclamación al título de la película "The Hunger Games":

var concatResult = session.createQuery( "select concat(title, '!') as excitedTitle from Movie where title = :title", String.class) .setParameter("title", "The Hunger Games") .getResultList();for (var excitedTitle : concatResult) { System.out.println("Concatenated Title: " + excitedTitle);}

Tip

También puede usar el operador double pipe (||) para unir dos valores. La siguiente query es equivalente al ejemplo anterior:

"select title || '!' as excitedTitle from Movie where title = :title"

La extensión Hibernate ORM traduce la query anterior a la siguiente etapa $project:

{ "$project": { "excitedTitle": { "$concat": [ { "$toString": "$title" }, { "$toString": "!" } ] }, "_id": 0 }}

La función substring(str, start) devuelve la parte de una string que comienza en la posición start. La posición start se basa en uno, por lo que el primer carácter de la string está en la posición 1. Para limitar el resultado a un número fijo de caracteres, llame a la función como substring(str, start, length).

Si pasa una posición start de 0 o un valor negativo, la extensión Hibernate ORM lee desde el principio de la string. Si también pasa un length, la extensión resta los caracteres anteriores a la primera posición de la longitud devuelta. Por ejemplo, substring(str, -1, 3) devuelve un carácter y substring(str, 0, 3) devuelve dos caracteres.

El siguiente ejemplo devuelve los primeros seis caracteres del título de la película "The Hunger Games":

var substringResult = session.createQuery( "select substring(title, 1, 6) as titlePrefix from Movie where title = :title", String.class) .setParameter("title", "The Hunger Games") .getResultList();for (var titlePrefix : substringResult) { System.out.println("Title Prefix: " + titlePrefix);}

La función locate(pattern, str) devuelve la posición basada en uno de la primera aparición de pattern en la string, o 0 si la string no contiene el patrón.

Para iniciar la búsqueda en una posición específica, llame a la función como locate(pattern, str, start). Dado que la posición start está basada en uno, el primer carácter de la string está en la posición 1. Un valor start de 0 o un número negativo inicia la búsqueda en la posición 1.

El siguiente ejemplo devuelve la posición de la subcadena "Hunger" en el título de la película "The Hunger Games":

var locateResult = session.createQuery( "select locate('Hunger', title) as position from Movie where title = :title", Integer.class) .setParameter("title", "The Hunger Games") .getResultList();for (var position : locateResult) { System.out.println("Position: " + position);}

La función replace(str, pattern, replacement) reemplaza cada aparición de pattern en la string con replacement. La extensión Hibernate ORM traduce la llamar al operador $replaceAll. Los tres argumentos deben ser cadenas de texto.

El siguiente ejemplo reemplaza la subcadena "Hunger" por "Video" en el título de la película "The Hunger Games":

var replaceResult = session.createQuery( "select replace(title, 'Hunger', 'Video') as newTitle from Movie where title = :title", String.class) .setParameter("title", "The Hunger Games") .getResultList();for (var newTitle : replaceResult) { System.out.println("New Title: " + newTitle);}

La función trim(str) remueve los espacios iniciales y finales de una string. Para remover caracteres de un único extremo de la string, utilice trim(leading char from str) o trim(trailing char from str). Para remover un carácter que no sea un espacio de ambos extremos de la string, especifíquelo usando las palabras clave both y from, como en trim(both char from str).

El siguiente ejemplo remueve el carácter inicial "T" del título de la película "The Hunger Games":

var trimResult = session.createQuery( "select trim(leading 'T' from title) as trimmedTitle from Movie where title = :title", String.class) .setParameter("title", "The Hunger Games") .getResultList();for (var trimmedTitle : trimResult) { System.out.println("Trimmed Title: " + trimmedTitle);}

La extensión Hibernate ORM traduce la query anterior a la siguiente etapa $project:

{ "$project": { "trimmedTitle": { "$ltrim": { "chars": "T", "input": "$title" } }, "_id": 0 }}

Las funciones pad(str with length leading) y pad(str with length trailing) extienden una string a la length especificada añadiendo espacios al principio o al final de la string str. Para usar un carácter que no sea un espacio, especifique el carácter después de la dirección, como en pad(str with 20 leading char).

También puede llamar a las funciones lpad(str, length, padding) y rpad(str, length, padding), que rellenan un string con un valor que puede contener más de un carácter. La extensión Hibernate ORM repite el valor de relleno tantas veces como sea necesario y lo trunca para alcanzar la longitud deseada. Por ejemplo, lpad('x', 6, 'ab') devuelve "ababax".

El relleno se comporta de la siguiente manera en estos casos:

  • Si la longitud de destino es más corta que la string, la extensión Hibernate ORM trunca la string a la longitud de destino al remover los caracteres finales después de la longitud de destino.

  • Si la longitud objetivo es negativa, la función devuelve una string vacía.

  • Si el valor de relleno es una string vacía, la función devuelve la string original.

El siguiente ejemplo utiliza asteriscos iniciales para rellenar el título de la película "The Hunger Games" a 20 caracteres:

var padResult = session.createQuery( "select pad(title with 20 leading '*') as paddedTitle from Movie where title = :title", String.class) .setParameter("title", "The Hunger Games") .getResultList();for (var paddedTitle : padResult) { System.out.println("Padded Title: " + paddedTitle);}

La función repeat(str, count) devuelve una string que contiene count copias de str.

El siguiente ejemplo devuelve el título de la película "The Hunger Games", repetido dos veces:

var repeatResult = session.createQuery( "select repeat(title, 2) as repeatedTitle from Movie where title = :title", String.class) .setParameter("title", "The Hunger Games") .getResultList();for (var repeatedTitle : repeatResult) { System.out.println("Repeated Title: " + repeatedTitle);}

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 a llamar a funciones de fecha y hora en una query, ver la guía Usar funciones de fecha y hora en 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.