JPQL: Domine consultas no Spring Boot com Java Persistence Query Language
Descubra por que JPQL é a chave para fazer queries poderosas com entidades em projetos Java, acabe de vez com a confusão entre SQL, tabelas e classes no framework mais usado do mundo.
Por que isso é importante
Sua capacidade de consultar dados determina a produtividade, a escalabilidade e a manutenibilidade do seu projeto Java. O JPQL, padrão central do Spring Boot e JPA, permite consultas orientadas a entidades – e não a tabelas. Entenda por que domina-lo evita erros, dores de cabeça e acelera entregas.
Entidades ou Tabelas? JPQL muda tudo.
Você programa Java e já pensou que consultas dinâmicas seriam só adaptação do SQL? Não é bem assim. O JPQL (Java Persistence Query Language) te força a pensar diferente: tudo gira em torno de entidades, atributos e classes – nunca em tabelas, nunca em colunas. Essa sacada influencia toda lógica de acesso a dados.
⚠️Atenção
Misturar nomes de tabelas ou colunas com entidades em queries JPQL resulta em erros difíceis de depurar. Sempre use nomes de classes e campos Java!
Por dentro do JPQL: o que realmente significa?
JPQL é a linguagem de consultas do JPA (Java Persistence API) – o núcleo de persistência do Java moderno. Ela se parece com SQL, mas traduz comandos escritos para nomes de entidades e propriedades em SQL nativo, tornando-se assim independente do banco usado.
JPQL não é SQL tradicional
Enquanto SQL puro manipula tabelas e colunas, o JPQL trabalha com entidades (suas classes anotadas com @Entity) e atributos (os campos das suas classes). O próprio JPA/hibernate converte JPQL para a sintaxe real do banco em tempo de execução.
ℹ️Dica técnica
Vai criar queries manuais em Spring Data? Sempre cheque o nome real da sua entidade Java, não o nome da tabela do banco!
Estrutura básica de uma query JPQL
A sintaxe típica de JPQL é previsível: SELECT alias FROM Entidade alias WHERE alias.atributo = :parametro
O alias é o apelido para você acessar atributos. O parametro permite consultas personalizadas e seguras. Tudo sempre referente a classes – esqueça as tabelas.
Comparando: JPQL vs SQL básico
Por exemplo, para listar todos clientes:SQL: SELECT * FROM clientesJPQL: SELECT c FROM Cliente c
O que muda? Usamos o nome da entidade (Cliente) no JPQL, e não o da tabela. Fique atento aos detalhes.
⚠️Evite confusão
O nome da entidade não precisa nem deve ser igual ao da tabela. O que interessa para JPQL é o nome da classe Java mapeada pelo @Entity.
Como criar uma entidade mínima para JPQL
Crie uma classe Java anotada com @Entity. Exemplo clássico: @Entity<br/>
public class Cliente {<br/>
@Id private Long id;<br/>
private String nome;<br/>
private String email;<br/>
}
E pronto. Esse nome (“Cliente”) será usado nas queries JPQL.
Repositório e uso do @Query
No repositório, defina métodos e adicione @Query. Exemplo:@Query("SELECT c FROM Cliente c WHERE c.nome = :nome")
List<Cliente> buscarPorNome(@Param("nome") String nome);
✅Boa prática
Use parâmetros nomeados com : (por exemplo, :nome) em vez de concatenar strings em queries – isso previne SQL Injection.
Queries de projeção: pegando só o email
Quer retornar apenas um campo? JPQL lida fácil com isso.@Query("SELECT c.email FROM Cliente c WHERE c.id = :id")
String buscarEmailPorId(@Param("id") Long id);
O resultado é direto e limpo.
Lembrete: consultas são sempre de entidade
Por padrão, qualquer query de JPQL devolve instâncias completas da classe mapeada, a não ser que selecione campos específicos. Não existe SELECT * nem consulta para “tabela”.
❌Alerta comum
Esqueça de vez a notação SELECT * FROM tabela dentro de @Query usando JPQL. Sempre use nomes e apelidos das suas classes Java!
JPQL é portável – o SQL muda sozinho
O JPQL não te força a reescrever queries para MySQL, Oracle ou PostgreSQL: o provider converte a consulta para o SQL ideal do banco em execução. Você ganha portabilidade.
Sintaxe JPQL poderosa: COUNT, LIKE, ORDER BY e JOIN
- COUNT: SELECT COUNT(c) FROM Cliente c
- LIKE / Busca textual: WHERE c.email LIKE :email
- ORDER BY: ORDER BY c.nome
- JOIN: SELECT p FROM Pedido p JOIN p.cliente c WHERE c.nome = :nome
Todas seguem lógica de entidade, nunca tabelas.
ℹ️Alternativa avançada
Precisa do SQL bruto do banco? Basta setar nativeQuery = true no @Query, mas aí você perde portabilidade e cai no mundo das tabelas SQL.
Nativo é possível, mas só com necessidade real
Casos de performance extrema, sintaxe exclusiva ou migração podem requerer queries nativas. Mas, em 99% dos casos, resolva com JPQL puro – e ganhe flexibilidade no tempo de vida do projeto.
Resumo rápido: nunca mais erre em JPQL
- JPQL fala a linguagem das entidades Java, não das tabelas SQL.
- A sintaxe lembra SQL, mas usa nome de classe e atributo.
- Queries são portáveis entre bancos, rodando com qualquer provedor compatível (Hibernate, EclipseLink etc).
- Não tente usar nomes de tabela nem SELECT * em JPQL – só funciona com SQL nativo.
- Use parâmetros nomeados e sempre consulte atributos, não colunas.
✅Pulo do Gato
Para nunca errar: sempre confira se está usando o nome da entidade e o atributo Java, e não os nomes do banco.
Quer ver mais exemplos na prática?
Confira o vídeo completo no canal do Dev Doido para ver todas as queries rodando ao vivo, com explicações visuais, debugging e dicas bônus para quem programa Spring Boot no dia a dia.
Acesse: https://www.youtube.com/@DevDoido
Aprofunde-se e compartilhe conhecimento
Dominar JPQL vai muito além de copiar queries. É questão de arquitetura, portabilidade e código limpo. Salve este artigo, envie para quem vai dev no Spring, e marque presença para mais dicas avançadas!