/ /

Usar funções de string em queries

Visão geral

Neste guia, você pode aprender a chamar funções de cadeia de caracteres do Hibername Query Language (HQL) em um campo de cadeia de caracteres usando a extensão MongoDB para hibernação ORM. As funções de string permitem medir, reformatar e combinar valores de string como parte de uma query.

Você pode chamar cada função em uma cláusula SELECT. A extensão ORM do Hibername traduz cada chamada de função para uma expressão de agregação do MongoDB no estágio $project. Como a extensão ORM do Hibernado não suporta chamadas de função como operandos de uma expressão computada, você não pode combinar uma função de string com um operador aritmético.

A extensão Hibername ORM suporta as seguintes funções de string:

Função	Tradução do MongoDB
`length()`, `character_length()` , `char_length()`	$strLenCP
`upper()`	$toUpper
`lower()`	$toLower
`concat()`, `\|\|`	$concat
`substring()`	$substrCP
`locate()`	$indexOfCP
`replace()`	$replaceAll
`trim()`	$trim, $ltrim ou $rtrim, dependendo da direção de corte especificada
`pad()`, `lpad()` , `rpad()`	Computado de $strLenCP, $substrCP e $concat
`repeat()`	Computado a partir de $range e $reduce

Observação

Funções de string não suportadas

A extensão Hibernar ORM não suporta as funções de cadeia de caracteres HQL position(), overlay(), left(), right() e collate(). Uma query que chama uma dessas funções lança um FeatureNotSupportedException.

Para usar uma função de string sem suporte, chame o método createNativeQuery() e inclua o operador relevante em sua declaração de linguagem de query do MongoDB . Para saber mais, consulte o guia Executar queries de banco de dados nativas.

Dados de amostra

Os exemplos neste guia usam a entidade Movie, que representa a coleção sample_mflix.movies dos conjuntos de dados de amostra do Atlas. A entidade Movie tem a seguinte definição:

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 como criar um aplicativo Java que use a Extensão MongoDB para Hibernate ORM para interagir com essa coleção de amostras do MongoDB, veja o tutorial Get Started.

Os exemplos neste guia usam o campoMovie da entidade title , que armazena um valor String.

Medir o comprimento de uma string

A função length(str) retorna o número de caracteres em uma string. Você também pode chamar essa função de character_length(str) ou char_length(str), que são apelidos para a mesma função. Como a extensão Hibername ORM traduz a chamada para o operador $strLenCP, a função conta os pontos de código Unicode em vez de bytes.

O exemplo a seguir retorna o título do filme "The Hunger Games" na coleção sample_mflix.movies e a duração do 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]);
}

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

A extensão ORM do Hibername traduz a query anterior para o seguinte estágio $project:

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

Alterar a capitalização de uma string

As funções upper(str) e lower(str) convertem uma string em maiúsculas ou minúsculas.

O exemplo a seguir retorna o título do filme "The Hunger Games" em maiú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);
}

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

A extensão ORM do Hibername traduz a query anterior para o seguinte estágio $project:

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

Concatenar strings

A função concat(x, y) une dois ou mais valores em uma única string. A extensão ORM do Hibername converte cada operando em uma string antes de ingressar, para que você possa concatenar valores numéricos ou concatenar um valor numérico a um valor de string.

O exemplo a seguir anexa um ponto de interrogação ao título do filme "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);
}

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

Dica

Você também pode usar o operador de pipe duplo (||) para unir dois valores. A seguinte query é equivalente ao exemplo anterior:

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

A extensão ORM do Hibername traduz a query anterior para o seguinte estágio $project:

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

Extrair uma substring

A função substring(str, start) retorna a parte de uma string que começa na posição start. A posição start é baseada em um, então o primeiro caractere na string está na posição 1. Para limitar o resultado a um número fixo de caracteres, chame a função como substring(str, start, length).

Se você passar uma posição start de 0 ou um valor negativo, a extensão ORM do Hibername lerá desde o início da string. Se você também passar um length, a extensão subtrai os caracteres antes da primeira posição do comprimento retornado. Por exemplo, substring(str, -1, 3) retorna um caractere e substring(str, 0, 3) retorna dois caracteres.

O exemplo a seguir retorna os primeiros seis caracteres do título do filme "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);
}

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

Localizar uma substring

A função locate(pattern, str) retorna a posição um da primeira ocorrência de pattern na string ou 0 se a string não contiver o padrão.

To begin the search at a specific position, call the function as locate(pattern, str, start). Because the start position is one-based, the first character in the string is at position 1. A start value of 0 or a negative number starts the search at position 1.

O exemplo a seguir retorna a posição da substring "Hunger" no título do filme "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);
}

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

Substituir uma substring

A função replace(str, pattern, replacement) substitui cada ocorrência de pattern na string por replacement. A extensão Hibername ORM traduz a chamada para o operador $replaceAll. Todos os três argumentos devem ser strings.

O exemplo a seguir substitui a substring "Hunger" por "Video" no título do filme "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);
}

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

Cortar caracteres de uma string

A função trim(str) remove os espaços iniciais e finais de uma string. Para remover caracteres de apenas uma extremidade da string, use trim(leading char from str) ou trim(trailing char from str). Para remover um caractere que não seja um espaço de ambas as extremidades da string, especifique-o usando as palavras-chave both e from, como em trim(both char from str).

O exemplo a seguir remove o caractere "T" principal do título do filme "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);
}

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

A extensão ORM do Hibername traduz a query anterior para o seguinte estágio $project:

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

Preencher uma string

As funções pad(str with length leading) e pad(str with length trailing) estendem uma string até o length especificado adicionando espaços ao início ou final da string str. Para usar um caractere diferente de um espaço, especifique o caractere após a direção, como em pad(str with 20 leading char).

Você também pode chamar as funções lpad(str, length, padding) e rpad(str, length, padding), que preenchem uma string com um valor que pode conter mais de um caractere. A extensão ORM do Hibernar repete o valor de preenchimento quantas vezes for necessário e o trunca para atingir o comprimento alvo. Por exemplo, lpad('x', 6, 'ab') retorna "ababax".

O preenchimento se comporta da seguinte maneira nesses casos:

Se o comprimento do destino for mais curto do que a string, a extensão ORM do Hibername trunca a string para o comprimento do destino removendo os caracteres finais após o comprimento do destino.
Se o comprimento de destino for negativo, a função retornará uma string vazia.
Se o valor de preenchimento for uma string vazia, a função retornará a string original.

O exemplo a seguir usa asteriscos iniciais para preencher o título do filme "The Hunger Games" com 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);
}

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

Repetir uma string

A função repeat(str, count) retorna uma string que contém count cópias de str.

O exemplo a seguir retorna o título do filme "The Hunger Games", repetido duas vezes:

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

Repeated Title: The Hunger GamesThe Hunger Games

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

Repeated Title: The Hunger GamesThe Hunger Games

Informações adicionais

Para saber mais sobre como criar filtros de query e usar operadores em suas declarações de query, consulte o guia Especificar uma query.

Para saber como chamar funções de data/hora em uma query, consulte o guia Como usar funções de data/hora em queries.

Para saber mais sobre como usar HQL e JPQL para executar queries, consulte Um guia para a linguagem de query do Hibernate na documentação do Hibernate ORM.

Voltar

Funções de data/hora em queries

Unir entidades em coleções