Para criar as consultas ao banco de dados, o Cronapp

possui seu Assistente de consulta visual

As consultas são realizadas em JPQL (Java Persistence Query Language), que é uma linguagem de consulta ORM que atua sobre classes e objetos, diferentemente do SQL que realiza as consultas baseadas em tabelas. Apesar de a diferença estrutural, a linguagem JPQL é bem semelhante ao SQL, porém a primeira possui a vantagem de que a mesma consulta pode ser realizada em todos os bancos de dados.

O Cronapp possui um assistente de consulta visual para facilitar a criação de consultas JPQL. O assistente de consulta é utilizado tanto em blocos de programação quanto em fontes de dados, mas existem pequenas diferenças entre o assistente de consulta do bloco e da fonte de dados. O assistente permite criar consultas de forma visual ou manual, além disso, possui outras funcionalidades que auxiliam na obtenção de dados do banco.

Image RemovedFigura 1 - Assistente de consulta visual (Bloco de programação)

1. Estrutura de Consulta - Possui as opções de criação da consulta, como adicionar a entidade desejada, selecionar campos desejados na consulta, criar regras e outros.
2. Testar Consulta - Realiza o teste da consulta criada e retorna os dados correspondentes a ela em uma nova janela (A forma de exibição é influenciada pelo modo de consulta escolhido).
3. Editar como Texto - Faz a edição da consulta visual em formato de texto (Após alterar uma consulta visual já criada nesse formato, não é possível alterar a consulta novamente em formato visual).
4. Visualizar como Texto - Exibe a consulta feita no formato visual em forma de texto.
5. Modo de Consulta - Altera a exibição da consulta, que pode ser por tabelas ou objetos (Figuras 1.1 e 1.2). 
6. Aplicar dados da requisição - Aplica as requisições (paginação, ordenação e outros) diretamente na consulta (Disponível apenas em consultas via bloco de programação).
7. Habilitar Paginação - Realiza a paginação dos dados em uma página de forma automática (Disponível apenas em consultas via bloco de programação).   
8. OK e Cancelar - Salva ou cancela a consulta.

Image Removed

   Figura 1.1 - Exibição de consulta em modo objetos

Image Removed

Figura 1.2 - Exibição de consulta em modo tabela

Estrutura da consulta

Agora vamos entender melhor as opções disponíveis na estrutura da consulta. 

Image RemovedFigura 2 - Estrutura visual da consulta

1. Entidade: Permite adicionar uma nova entidade a consulta. Para isso deve-se clicar nos "..." e selecionar a classe desejada.

• Alias: É o apelido dado a entidade, por exemplo, se nossa classe fosse Pessoas o nosso alias poderia ser p (Pode ser o nome desejado). Nas próximas opções a entidade será referenciada pelo alias.

Para confirmar a adição da entidade, basta clicar em adicionar. E para adicionar uma nova entidade deve-se repetir o processo acima.

Image Removed

Figura x - Estrutura visual da consulta (campos)

2. Campos: Define quais campos serão buscados na consulta. É possível adicionar os campos desejados através do botão "Novo Campo"ou adicionar todos os campos da entidade de uma só vez clicando em "Adicionar Todos". 

• Tipo de retorno: Define como o valor do campo será retornado. Os tipos são:
  • Obter:  Retorna o valor do campo como está no banco;  
  • MIN: Retorna o menor valor do campo;
  • MAX: Retorna o maior valor do campo;
  • AVG: Retorna a média aritmética dos valores do campo registrados no banco;
  • SUM: Retorna a soma dos valores do campo;
  • COUNT: Retorna a quantidade de registros do campo.
• Campo selecionado: Seleciona qual o campo será consultado. 

Para adicionar novos campos na consulta o processo acima deve ser repetido.

Image Removed

Figura x - Estrutura visual da consulta (Regra)

3. Regra: Nessa propriedade é definida a regra que será considerada ao buscar os dados no banco. É possível ir adicionando regras, por meio do botão "Nova Regra" (Figura x - elemento 1) ou adicionar um grupo de regras, através do botão "Novo Grupo" (Figura x - elemento 2).  

• Campo da entidade: Aqui é decidido qual o campo da entidade que será utilizado para a criação da regra.
• Condição: Escolhe-se qual é a condição que deve existir entre o campo e o parâmetro.
• Parâmetro: Define-se o nome do parâmetro que será comparado com o campo da entidade.
• Não: Adiciona uma negação (not) a condição criada.
• Inverter: Inverte a condição definida na regra.

É possível também adicionar um grupo de regras. O funcionamento é semelhante ao citado anteriormente, entretanto para criar um grupo de regras primeiramente deve-se clicar em "Novo Grupo".

Image RemovedFigura x - Estrutura visual da consulta (Agrupar)

4. Agrupar: Aqui é possível agrupar os dados retornados na consulta. Para isso deve-se clicar no botão "Novo Campo".

Campo de referência:  Seleciona qual o campo que será a referência para criar os grupos.

Image Removed

Figura x - Estrutura visual da consulta (Having)

5. Having: A propriedade having funciona de forma semelhante a propriedade regra, entretanto ela cria uma regra para os grupos criados com a propriedade agrupar. Por isso, o having sempre deve ser usado junto com o agrupar. Para adicionar um novo clique em "Novo campo"

Image Removed

Figura x - Estrutura visual da consulta (Ordenar)

6. Ordenar: Nessa opção é definida a ordem de retorno dos itens. Por exemplo, é possível trazer os dados organizados do menor id para o maior ou o contrário.

• Tipo de dado: Define qual o tipo de dado que será utilizado para ordenar os dados.
• Campo: Campo que será utilizado como referência na ordenação.
• Tipo de ordenação: Define o tipo de ordenação que será considerada na propriedade. O tipo pode ser Asc ( ascendente, que é do valor mais baixo para o mais alto) e Desc (descendente, do valor mais alto para o mais baixo).

Passos

No nosso exemplo temos uma classe Cidade na qual será realizada uma consulta visual, para abrir o assistente de consultas clique no ícone de configuração do bloco Abrir consulta.

Observe a estrutura da consulta conforme a figuras 3 e 3.1: 

Image Removed

Figura 3 - Entidade e campos selecionados na consulta

Image Removed

Figura 3.1 - Definição da ordenação dos itens consultados

Siga os passos abaixo para obter a consulta das figuras 3 e 3.1: 

1. Entidade: Na propriedade entidade, clique no "..." e selecione a entidade desejada na consulta, após isso clique em "Adicionar". Nesse caso a entidade utilizada foi a Cidade que está sendo representada como 'c'.
2. Campos: Na propriedade campos, clique em "Novo Campo" e em seguida selecione o campo que deseja trazer na consulta , nesse exemplo utilizamos o campo estado (Para adicionar novos campos basta repetir o processo, ou se desejar trazer todos os campos selecione o objeto inteiro. No exemplo atual para trazer todos os campos seria necessário selecionar o campo 'c').
3. Regra: Na propriedade regra, clique em "Nova Regra" e selecione um filtro para a consulta (Ex: Selecionar os campos em que o id seja maior que 1). No exemplo atual a quantidade de habitantes deve ser diferente do valor do parâmetro 'minimo'.
4. Agrupar: Na propriedade agrupar, clique em "Novo Campo" e selecione o campo pelo qual os itens devem ser agrupados, nesse exemplo os itens são agrupados por estado.
5. Having: Na propriedade having, clique em "Novo Campo" e informe uma nova regra para a consulta, porém a regra utilizada em having possui opções diferentes da propriedade regra (São utilizados as opções Sum, Avg, Min, Max, Count). Em nosso exemplo, a soma da quantidade de habitantes dos estados deve ser maior que o valor do parâmetro 'quantidadeHabitantes' ( Lembrando que a propriedade having funciona em conjunto com a propriedade agrupar, primeiro os itens são agrupados e o having é aplicado nos grupos).
6. Ordenar: Na propriedade ordenar, clique em "Novo Campo" e selecione o campo pelo qual deseja ordenar e em qual ordem(Ascendente ou Descendente), nessa situação utilizamos o campo estado e a opção Asc (Ascendente).
7. Selecione a opção "OK" para salvar a consulta.

Exemplo da mesma consulta feita em SQL:

SELECT estado FROM   cidade 
WHERE  quantidadehabitantes > minimo 
GROUP  BY estado 
HAVING Sum(quantidadehabitantes) > quantidadehabitantes 
ORDER  BY estado ASC 

Realizando consultas entre duas tabelas

É possível também realizar consultas entre duas tabelas. No exemplo abaixo, iremos retornar o nome dos países em que as cidades possuem mais de 50 mil habitantes e a soma dos habitantes de todas as cidades do país devem ser iguais ou superiores a 1 milhão.

Image RemovedFigura 4 - Consulta visual JPQL (Bloco de programação)

Siga os passos abaixo para obter a consulta da figura 4:

1. Entidade:  Na propriedade entidade, utilizamos a entidade Cidade que é representada como 'c'.
2. Campos: Na propriedade campos, selecionamos a opção 'c.pais.nome' para podermos retornar o nome do país em que a cidade está relacionada.
3. Regra: Nessa propriedade a regra definida foi que a quantidade de habitantes das cidades retornadas deve ser maior que 0.
4. Agrupar: Os itens foram agrupados por país, por meio do campo 'c.pais.nome'.
5. Having: Na propriedade having, a regra definida foi que o número de habitantes dos países(O atributo utilizado no exemplo foi o 'c.quantidadeHabitantes', mas como as cidades estão agrupadas por país considera-se que essa soma dos habitantes das cidades representa o total de habitantes do país) deve ser maior ou igual a 1 milhão.

Exemplo da mesma consulta feita em SQL:

SELECT c.fk_pais, p.nome 
FROM Cidade as c 
INNER JOIN Pais as p 
ON p.id = c.fk_pais 
WHERE c.quantidadeHabitantes > quantidade 
GROUP BY p.nome 
HAVING SUM(c.quantidadeHabitantes) > quantidadeHabitantes

Existem algumas diferenças entre o assistente de consulta JPQL da fonte de dados e o do bloco de programação. 

Image Removed

Figura 5 - Consulta visual JPQL (Bloco de programação)

Image Removed

Figura 5.1 - Consulta visual JPQL (Fonte de dados) 

O assistente visual do bloco de programação possui duas funcionalidades a mais que o assistente visual da fonte de dados. São elas, Aplicar Dados da Requisição e Habilitar Paginação.

É possível aplicar todos os parâmetros de uma requisição a uma fonte de dados em uma consulta usada com a função Abrir Consulta.

O Cronapp permite uso de um bloco como fonte de dados. Quando usamos isso, na maioria das vezes, o intuito é usar uma consulta com a função Abrir Consulta. Nas versões anteriores existia uma opção chamada Paginação Automática. Essa opção aplicava os dados de paginação da requisição da fonte de dados à consulta. O Cronapp evoluiu essa opção que passou a se chamar Aplicar Dados da Requisição. Essa opção agora aplica paginação, ordenação, filtros e qualquer outro dado da requisição ODATA à consulta. Com isso, todas as operações de interface serão enviadas à consulta e buscas, ordenações etc passam a funcionar com Fonte de Dados com Bloco de Programação.

Image Removed

Figura 5.2 - Opção de habilitar paginação 

Blocos que utilizam o assistente visual JPQL

Image Removed

1. Bloco Inserir:

Bloco do tipo servidor que adiciona uma nova entidade ao banco de dados por meio do assistente visual do JPQL ( consulte mais detalhes aqui).

2. Bloco Abrir consulta:

Bloco do tipo servidor que realiza uma consulta no banco de dados por meio do assistente visual do JPQL (consulte mais detalhes aqui).

3. Bloco Abrir consulta:

Bloco do tipo servidor que atualiza uma entidade no banco de dados por meio do assistente visual JPQL (consulte mais detalhes aqui).

4. Bloco Abrir consulta:

Bloco do tipo servidor que remove uma entidade do banco de dados por meio do assistente visual JPQL (consulte mais detalhes aqui).

que simplifica esse processo. 

Image Added

Figura 1 - Assistente de Consulta 

Acesso ao Assistente

Atualmente existem três formas de acesso ao Assistente de consulta visual:

• Por meio de alguns blocos de programação do tipo servidor, que estão na categoria Banco de Dados.
• Através do assistente de consulta de uma Fonte de Dados do tipo Entidade e SQL Nativo.
• Utilizando o Testador de Consultas JPQL.

Vamos detalhar abaixo cada uma dessas formas de acesso.

Blocos de programação

Uma das formas de acesso ao Assistente de consulta visual é por meio de alguns blocos de programação da categoria Banco de Dados. Para abrir o Assistente, basta clicar no ícone de engrenagem de cada bloco (Figura 1.1). O bloco Abrir consulta (destaque 1 da Figura 1.1) exibe a mesma estrutura do Assistente visual detalhada no tópico Estrutura da Consulta (Figura 2). Já os blocos de manipulação de dados (DML - Data Manipulation Language) possuem algumas diferenças. Para mais detalhes, consulte a documentação específica de cada bloco abaixo.

Image Added

Figura 1.1 - Blocos de acesso ao Assistente de consulta visual

Blocos do tipo servidor para acesso ao assistente visual:

1. Abrir consulta: cria uma consulta no banco de dados por meio do assistente visual.
2. Inserir: adiciona novos registros ao banco de dados por meio do assistente visual.
3. Atualizar: atualiza registros no banco de dados por meio do assistente visual.
4. Remover: remove registros do banco de dados por meio do assistente visual.

Fonte de Dados

O Assistente de consulta também pode ser acessado através de uma Fonte de Dados do tipo Entidade ou SQL Nativo. Na imagem abaixo, vemos como configurar uma Fonte de dados e acessar o Assistente de consulta por meio dela. 

Image Added

Figura 1.2 - Fonte de dados vinculada a uma entidade e sua consulta

Destaques da Figura 1.2:

1. Tipo da fonte: define o tipo da origem dos dados, podendo ser Entidade, SQL Nativo, Bloco de programação ou Web Services. Como informado anteriormente, apenas os tipos Entidade e SQL Nativo permitem o acesso ao Assistente de consulta, escolha uma dessas duas opções.
2. " ..." : seleciona a origem dos dados. Essa seleção irá variar a depender do tipo da fonte escolhida. Se for do tipo Entidade, será possível selecionar uma das classes de qualquer Diagrama de dados (namespace) do projeto. Por outro lado, se for do tipo SQL Nativo, poderá selecionar um dos namespaces do projeto.
3. Editar: abre o Assistente de consulta e permite personalizá-la. Esse botão estará desabilitado em Fontes de dados que não possuem o Assistente.
4. Consulta: exibe a consulta JPQL para a fonte do tipo Entidade, ou SQL para Fonte do tipo SQL Nativo.

A imagem a seguir apresenta o Assistente de consulta aberto após clicar no botão "Editar" (destaque 3 da Figura 1.2). Nele é possível personalizar a consulta realizada.

Image Added

Figura 1.3 - Assistente de consulta da Fonte de dados

Testador de Consultas

Outra forma de acessar o Assistente de consulta é utilizando o Testador de Consultas JPQL, acessível a partir do menu do sistema em Ferramentas > Testador de Consultas JPQL (Figura 1.4).

Image Added

Figura 1.4 - Testador de Consultas JPQL

Estrutura da Consulta

O Assistente de consulta visual gera consultas em: JPQL (Jakarta Persistence Query Language, conhecido antigamente como Java Persistence Query Language), uma linguagem de consulta ORM que atua sobre classes e objetos;  SQL (Structured Query Language), linguagem que trabalha com banco de dados relacionais e realiza as consultas sobre tabelas; e em requisições do tipo REST (Representational State Transfer), quando o assistente é utilizado em um bloco de programação ou no Testador de Consultas JPQL para gerar uma consulta a partir de uma Fonte de Dados, acesse o tópico REST para mais detalhes. 

É importante destacar que o Assistente de consulta pode apresentar diferenças,dependendo da forma de acesso e o tipo de consulta realizada. As funcionalidades apresentadas neste tópico se referem ao Assistente acessado por meio do bloco de programação Abrir consulta, visto que possui mais campos para configurar.

Image Added

Figura 2 - Assistente de consulta visual (Bloco de programação)

1. Entidade: adiciona as entidades, tabelas ou Fonte de dados que farão parte da consulta.
2. Campos: define quais campos serão buscados na consulta.
3. Join: combina colunas de uma ou mais entendidas ou tabelas, usando valores comuns a cada uma delas.
4. Regras: regra que será considerada ao buscar os registros.
5. Agrupar: agrupa linhas que possuem valores iguais nos mesmos campos.
6. Having: cria regras para serem usadas junto com os campos agrupados.
7. Ordenar: define a ordem em que os dados serão retornados.
8. SQL Nativo: permite o uso de consultas do tipo SQL nativo.
9. Modo de Consulta: altera a exibição dos dados em modo de teste da consulta, que pode ser por tabela ou objetos.
10. Aplicar dados da requisição: aplica as requisições (paginação, ordenação e outros) diretamente na consulta.
11. Habilitar Paginação: realiza a paginação dos dados em telas de forma automática.
12. Testar Consulta: exibe o resultado da consulta criada em uma nova janela, altere o campo Modo de Consulta para modificar a forma de exibição.
13. Editar como Texto: muda a janela para editar a consulta manualmente (high-code). Após alterar uma consulta manualmente, não será possível editar novamente em modo visual.
14. Visualizar como Texto: exibe a consulta gerada através da configuração visual.
15. OK e Cancelar: salva ou cancela a consulta.

Entidade

Adiciona as entidades, tabelas ou Fonte de dados que farão parte da consulta. Equivale a seleção de tabelas após a sentença "FROM" em uma consulta SQL. Dependendo do tipo de consulta selecionada no campo Entidade,alguns campos serão ou não exibidos. Veja o tópico Diferença entre consultas.

Image Added

Figura 2.1 - Área de seleção das entidades

Campos e botões:

• Entidade: exibe a entidade, tabela ou Fonte de dados recém selecionada.
• " ... " : abre a janela para seleção.
• Alias: permite adicionar um apelido.
• + Adicionar: confirma a selecionada na consulta.
• Excluir: remove a entidade, tabela ou Fonte de dados selecionada.

Destaques da Figura 2.1:

1. Exibe a entidade, tabela ou Fonte de dados selecionada.
2. Exibe o alias configurado para a entidade, tabela ou Fonte de dados selecionada.

Para adicionar à consulta, clique no botão "..." do campo Entidade, selecione a classe, tabela ou a Fonte de dados desejada e finalize clicando em "+ Adicionar".

JPQL e SQL Nativo

Para realizar consultas do tipo SQL Nativo no Assistente de consulta dos bloco de programação, será necessário selecionar a checkbox SQL Nativo. Consulte o tópico correspondente nesta documentação para mais informações. A consulta definida na Figura 2.1, em JPQL e SQL Nativo, ficará da seguinte forma:

FROM Login lg

Fonte de dados

É importante destacar que as consultas do tipo Fonte de dados gera uma requisição REST. Consulte o tópico correspondente nesta documentação para mais informações. A consulta definida na Figura 2.1 ficará da seguinte forma:

GET app/login

Campos

Define quais campos serão buscados na consulta. Equivale a seleção dos campos das tabelas após a sentença "SELECT" em uma consulta SQL. 

Image Added

Figura 2.2 - Área de seleção dos campos

É possível adicionar os campos desejados através do botão "+ Novo Campo" ou adicionar todos os campos da entidade de uma só vez, clicando em "+ Adicionar Todos". 

Botões:

• + Novo Campo: adiciona um campo das entidades selecionadas ou de entidades relacionadas.
• + Adicionar Todos: insere todos os campos das entidades selecionadas.
• Excluir: exclui o campo.

Destaques da Figura 2.2:

1. Tipo de retorno: define como o valor do campo será retornado. Os tipos são:
   • Obter: retorna o valor do campo como está no banco.
   • MIN: retorna o menor valor do campo selecionado.
   • MAX: retorna o maior valor do campo selecionado.
   • AVG: retorna a média aritmética dos valores do campo selecionado.
   • SUM: retorna a soma dos valores do campo selecionado.
   • COUNT: retorna a quantidade de registros do campo selecionado.
2. Campo selecionado: seleciona qual o campo será consultado. 

JPQL

Em consultas JPQL, a área de seleção dos campos já mapeia todos os campos das entidades relacionadas (terceiro "obter" da imagem abaixo), por isso não é necessário usar o JOIN. Por exemplo, imagine que uma entidade A tem relação com B, a entidade B tem relação com C e C possui um campo chamado "nome", dessa forma, basta selecionar a entidade A e na área Campos selecionar a opção "A.B.C.nome", criando um JOIN automaticamente.

Image Added

Figura 2.2.1 - Área de seleção dos campos de uma consulta JPQL

Destaques da Figura 2.2.1:

1. Para retornar todos os campos de uma entidade, basta selecionar o alias da entidade desejada.
2. Para retornar um campo específico, é necessário selecionar o alias da entidade com o campo desejado.
3. Caso queira obter um campo de uma entidade relacionada (JOIN), selecione o alias da entidade, junto com o nome da entidade relacionada e o nome do campo.

Por padrão, em consultas JQPL a caixa de seleção dos campos só exibe relacionamentos até o terceiro nível. Para relacionamentos maiores, informe manualmente. Exemplo: EntidadeA.EntidadeB.EntidadeC.EntidadeD.EntidadeE.atributo.

A consulta definida na Figura 2.2.1 ficará da seguinte forma:

SELECT lg, lg.providerDisplayName, lg.user.name FROM Login lg, User usr

SQL Nativo

Em consultas do tipo SQL Nativo, diferente de uma consulta JPQL, a área de seleção dos campos mapeia apenas em primeiro nível os campos das tabelas. 

Image Added

Figura 2.2.2 - Área de seleção dos campos de uma consulta SQL Nativo

A consulta definida na Figura 2.2.2 ficará da seguinte forma:

SELECT LG.ID, LG.PROVIDER_DISPLAY_NAME FROM LOGIN LG

Além disso, não é possível retornar todos os campos de uma tabela selecionando o alias, para lidar com vários níveis de relacionamento, será necessário utilizar o JOIN. Consulte o tópico correspondente para mais informações.

Fonte de dados

Em consultas do tipo Fonte de dados, a área de seleção dos campos mapeia apenas em primeiro nível os campos da Fonte de dados. Além disso, não é possível retornar todos os campos de uma tabela selecionando o alias. 

Image Added

Figura 2.2.3 - Área de seleção dos campos de uma consulta Fonte de dados

A consulta REST definida na Figura 2.2.3 ficará da seguinte forma:

GET app/login?$select=id%2CproviderDisplayName

Join

Essa opção é exibida apenas em consultas do tipo JPQL e SQL Nativo. É uma operação de junção que combina colunas de uma ou mais tabelas, usando valores comuns a cada uma delas. Equivale a sentença "JOIN" em uma consulta SQL. 

Como já informado, em consultas JPQL não é necessário usar o JOIN, pois a área de seleção dos campos já mapeia todos os campos das entidades relacionadas. No entanto, você pode utilizá-lo em consultas do tipo SQL Nativo, como no exemplo da imagem abaixo.

As cláusulas JOIN disponíveis são apenas as suportadas pelo EclipseLink, "JOIN" e "LEFT JOIN". Para mais detalhes, acesse os subtópicos do tópico FROM CLAUSE (Cláusula FROM) na documentação oficial. 

Image Added

Figura 2.3 - Área de seleção do Join

Campos e botões:

• Join: exibe a entidade recém selecionada.
• " ... " : abre a janela para seleção da entidade.
• Alias: permite adicionar um apelido.
• + Adicionar: adiciona a entidade selecionada à consulta.
• Excluir: exclui entidade adicionada.

Destaques da Figura 2.3:

1. Cláusula: tipo da cláusula JOIN utilizada. São elas:
   • JOIN: retorna apenas os registros que têm correspondências em ambas as entidades envolvidas na junção.
   • LEFT JOIN: retorna todos os registros da entidade à esquerda e os registros correspondentes da entidade à direita.
2. Entidade: exibe a entidade selecionada.
3. Alias: exibe o alias configurado para a entidade selecionada.
4. Campo da entidade: seleciona qual o campo da entidade será usado para consulta.
5. Condição: condição que será utilizada para comparar os valores das entidades. São elas:
   • Igual.
   • Diferente.
   • Menor.
   • Menor ou igual.
   • Maior.
   • Maior ou igual.
6. Parâmetro: campo que será usado como comparação.

A consulta definida na Figura 2.3, em JPQL e SQL Nativo, ficará da seguinte forma:

JOIN LOGIN LG ON LG.USER_ID = USR.ID;

Regras

Essa opção é exibida apenas em consultas do tipo JPQL e SQL Nativo. Nessa propriedade é definida as regras que serão consideradas ao buscar os dados no banco. Por meio do botão "+ Nova Regra" é possível adicionar regras e selecionar um condicional único entre as regras, ou adicionar vários grupos de regras e selecionar condicionais para cada grupo individualmente através do botão "+ Novo Grupo". As regras equivalem ao filtro após a sentença "WHERE" em uma consulta SQL. Caso tenha alguma dúvida sobre a regra WHERE, acesse o tópico WHERE Clause (Cláusula WHERE) na documentação oficial.

Image Added

Figura 2.4 - Área de seleção das regras da consulta

Botões:

• + Nova Regra: adiciona uma regra vinculada ao campo selecionado.
• + Novo Grupo: insere um grupo com uma ou mais regras.
• Excluir: exclui a regra ou grupo selecionado.

Destaques da Figura 2.4:

1. Negação: nega a sentença vinculada, adicionando um "not" antes.
2. Operador lógico: define se o operador lógico entre as sentenças será "e" ou "ou".
3. Inverter: alterna o operador lógico e os campos condicionais das sentenças vinculadas, por exemplo: se estiver selecionado "ou", será substituído por "e", isso também ocorrerá no campo condicional (campo 5 da Figura 2.4), que alternará de "igual" para "diferente".
4. Campo da entidade: campo da entidade que será utilizado na criação da regra.
5. Condição: define a condição que deve existir entre o campo e o parâmetro, são elas:
   • Igual.
   • Diferente.
   • Contido.
   • Não contido.
   • Iniciando com.
   • Não iniciando com.
   • Contém.
   • Não contém.
   • Terminando com.
   • Terminado sem.
   • É vazio.
   • Não é vazio.
   • É nulo.
   • Não é nulo.
6. Tipo de parâmetro: tipo do parâmetro que será utilizado na consulta, são eles:
   • Parâmetro: ao selecionar esse tipo, no campo "Parâmetro" é possível definir uma variável adicionando ":" (dois pontos) no início dela (destaque 7). Ao inserir um conteúdo sem os ":" (dois pontos) no início, este conteúdo ficará entre aspas ('') e será tratado como uma string.
   • Personalizado: ao selecionar esse tipo, no campo "Parâmetro" também é possível definir uma variável adicionando ":" (dois pontos) no início dela (destaque 7). No entanto, deve ser utilizado com o objetivo de passar um conteúdo estático personalizado, como uma string ou uma lista de elementos. Nesse caso, as aspas ('') não serão inseridas automaticamente, o próprio usuário deverá realizar esse tratamento (destaque 9). 
7. Parâmetro: define o nome do parâmetro que será comparado com o campo da entidade. O conteúdo informado neste campo deve estar de acordo com o "Tipo de parâmetro" selecionado. Como informado anteriormente, neste campo é possível definir uma variável adicionando ":" (dois pontos) no início dela (destaque 7) ou um conteúdo estático personalizado (destaque 9). 

8. ↑ ↓ : clique e arraste o ícone ↑ ↓ para modificar a posição de uma regra ou grupo. 

A regra definida na Figura 2.4, em JPQL ou SQL Nativo, ficará da seguinte forma:

WHERE usr.phoneNumber = :phoneNumber AND (NOT (usr.name = ('Maria') ) )

Filtro

Essa opção é exibida apenas em consultas do tipo Fonte de dados. Este campo permite filtrar ou restringir os registros de uma consulta, semelhante ao campo Regras. No entanto, possui algumas limitações, já que sua consulta será convertida em uma requisição REST. A imagem abaixo detalha os recursos dessa funcionalidade.

Image Added

Figura 2.5 - Área de seleção dos filtros da consulta

Botões:

• + Nova Regra: adiciona um filtro vinculado ao campo selecionado.
• Excluir: exclui o filtro selecionado.

Destaques da Figura 2.5:

1. Campo da Fonte de dados: campo da Fonte de dados que será utilizado na criação do filtro.
2. Condição: define a condição que deve existir entre o campo e o parâmetro, são elas:
   • Igual.
   • Diferente.
   • Contido.
   • Não contido.
   • Iniciando com.
   • Não iniciando com.
   • Contém.
   • Não contém.
   • Terminando com.
   • Terminado sem.
   • É vazio.
   • Não é vazio.
   • É nulo.
   • Não é nulo.
3. Tipo de parâmetro: tipo do parâmetro que será utilizado na consulta, são eles:
   • Parâmetro: ao selecionar esse tipo, no campo "Parâmetro" é possível definir uma variável adicionando ":" (dois pontos) no início dela (destaque 4). Ao inserir um conteúdo sem os ":" (dois pontos) no início, este conteúdo ficará entre aspas ('') e será tratado como uma string.
   • Personalizado: ao selecionar esse tipo, no campo "Parâmetro" também é possível definir uma variável adicionando ":" (dois pontos) no início dela (destaque 7). No entanto, deve ser utilizado com o objetivo de passar um conteúdo estático personalizado, como uma string ou uma lista de elementos.
4. Parâmetro: define o nome do parâmetro que será comparado com o campo da entidade. Neste campo é possível definir uma variável adicionando ":" (dois pontos) no início dela (destaque 4) ou um conteúdo estático personalizado. 

A regra definida na Figura 2.5 ficará da seguinte forma na requisição REST:

filter=%28name%20eq%20%3Aname%29

Agrupar

Essa opção é exibida apenas em consultas do tipo JPQL e SQL Nativo. Possui a função de agrupar linhas que têm os mesmos valores em um ou mais campos específicos. Equivale a sentença "GROUP BY" em uma consulta SQL. Para mais detalhes sobre o agrupar, acesse o tópico GROUP BY Clause (Cláusula GROUP BY) na documentação oficial.

Image Added

Figura 2.6 - Área de seleção do Agrupar

Botões:

• + Novo Campo: adiciona outro campo para agrupar.
• Excluir: exclui o campo selecionado.

Destaques da Figura 2.6:

1. Campo a ser agrupado: seleciona qual o campo será agrupado.

A regra definida na Figura 2.6, em JPQL e SQL Nativo, ficará da seguinte forma:

GROUP BY user.emailConfirmed

Having

Essa opção é exibida apenas em consultas do tipo JPQL e SQL Nativo. A propriedade Having funciona de forma semelhante a propriedade Regras, entretanto ela cria uma regra para os grupos criados com a propriedade Agrupar. Por isso, o Having sempre deve ser usado junto com o Agrupar. Possui a mesma função do "HAVING" em consultas SQL. Para mais detalhes sobre a condição having, acesse o tópico HAVING Clause (Cláusula HAVING) na documentação oficial.

Image Added

Figura 2.7 - Área de seleção das regras do Having

Botões:

• + Novo Campo: adiciona outro campo para criar uma regra having.
• Excluir: exclui o campo selecionado.

Destaques da Figura 2.7:

1. Tipo de dados da condição: é definido qual o tipo será retornado do banco para ser comparado na regra criada pelo having. Os tipos são:
   
   • MIN: retorna o menor valor do campo selecionado.
   • MAX: retorna o maior valor do campo selecionado.
   • AVG: retorna a média aritmética dos valores do campo selecionado.
   • SUM: retorna a soma dos valores do campo selecionado.
   • COUNT: retorna a quantidade de registros do campo selecionado.
2. Campo: campo usado para a comparação com o parâmetro.
3. Condição: condição que será utilizada para comparar o valor obtido no campo e o parâmetro. São eles:
   • Igual.
   • Diferente.
   • Menor.
   • Menor ou igual.
   • Maior.
   • Maior ou igual.
4. Parâmetro: valor que será comparado com o tipo de dado retornado. Neste campo é possível definir uma variável adicionando ":" (dois pontos) no início dela (destaque 4) ou um conteúdo estático personalizado. 

A regra definida na Figura 2.7, em JPQL e SQL Nativo, ficará da seguinte forma:

HAVING MIN(usr.salario) >= 3.000,00

Ordenar

Define a ordem de retorno dos itens. Por exemplo, é possível trazer a lista de funcionários ordenada pelos maiores salários. Possui a mesma função do "ORDER BY" em consultas SQL. Para mais detalhes sobre a condição order by, acesse o tópico ORDER BY Clause (Cláusula ORDER BY) na documentação oficial.

Image Added

Figura 2.8 - Área de ordenação da consulta

Botões:

• + Novo Campo: adiciona outro campo para ordenar.
• Excluir: exclui o campo selecionado.

Destaques da Figura 2.8:

1. Tipo de dado: define qual o tipo de dado que será utilizado para ordenar os dados.
   • Obter: retorna o valor do campo como está no banco.  
   • MIN: retorna o menor valor do campo selecionado.
   • MAX: retorna o maior valor do campo selecionado.
   • AVG: retorna a média aritmética dos valores do campo selecionado.
   • SUM: retorna a soma dos valores do campo selecionado.
   • COUNT: retorna a quantidade de registros do campo selecionado.
2. Campo: campo que será utilizado para a ordenação.
3. Tipo de ordenação: define o tipo de ordenação que será considerada na propriedade.
   • Asc: ascendente.
   • Desc: descendente.

JPQL e SQL Nativo

A regra definida na Figura 2.8, em JPQL e SQL Nativo, ficará da seguinte forma:

ORDER BY user.email ASC

Fonte de dados

A regra definida na Figura 2.8, a partir de uma Fonte de dados, ficará da seguinte forma:

$orderby=email%20ASC

SQL Nativo

Funcionalidade presente apenas no Assistente de consulta dos blocos de programação. Por padrão, o Cronapp utiliza o JPQL para realizar consultas ao banco de dados. Porém ao ativar a opção SQL Nativo (destaque 8 da Figura 2) é possível utilizar consultas SQL nativas, possibilitando o uso de diversos recursos não suportados pelo JPQL. Ao selecionar a checkbox dessa funcionalidade, será possível escolher um diagrama de dados (namespace) da aplicação e as classes desse diagrama serão exibidas no campo Entidade para gerar uma consulta (Figura 2.9).

Image Added

 Figura 2.9 - Opção SQL Nativo selecionada

Modo de Consulta

Essa funcionalidade é exibida apenas ao acessar o Assistente visual por bloco de programação e pela Fonte de dados do tipo Entidade e SQL nativo. A opção Modo de Consulta (destaque 9 da Figura 2) altera a visualização dos dados ao testar a consulta, que pode ser por objetos (Figura 2.10) ou tabelas (Figura 2.11). 

Image Added

   Figura 2.10 - Exibição de consulta em modo objetos

Image Added

Figura 2.11 - Exibição de consulta em modo tabela

Aplicar dados da requisição

Funcionalidade presente apenas no Assistente de consulta do bloco de programação Abrir consulta. Nas versões anteriores do Cronapp existia uma opção chamada "Paginação Automática". Essa opção aplicava os dados de paginação da requisição da Fonte de dados à consulta. O Cronapp evoluiu essa opção que passou a se chamar Aplicar Dados da Requisição (destaque 10 da Figura 2). Essa nova opção aplica paginação, ordenação, filtros e qualquer outro dado da requisição ODATA à consulta. Com isso, todas as operações de interface serão enviadas à consulta, fazendo com que a Fonte de dados funcione integralmente com a consulta do bloco de programação.

Habilitar paginação

Assim como a anterior, essa funcionalidade está presente apenas no Assistente de consulta do bloco de programação Abrir consulta. Ela permite paginar os dados exibidos na tela. Para isso, utilize o bloco Abrir consulta e selecione a opção Habilitar paginação (destaque 11 da Figura 2), ao fazer isso, o bloco exibirá os parâmetros limit e offset (Figura 2.12).

• limit: define a quantidade de linhas retornadas na consulta.
• offset: define a partir de qual linha retornará.

Image Added

Figura 2.12 - Bloco com a opção Habilitar paginação ativa

Exemplo: Em uma consulta com 100 registros, ao definir os parâmetros limit com '20' e o offset com '10', o resultado retornará os registros de 10 a 30.

Diferença entre consultas

JPQL e SQL

Como informado anteriormente, o Assistente de consulta visual gera consultas em JPQL, que se parecem muito com consultas SQL.

A Figura 3 mostra um exemplo de consulta JPQL. O Assistente visual foi acessado a partir do bloco de programação Abrir Consulta. Importante destacar que no campo Entidade escolhemos uma entidade do tipo classe, em vez de uma Fonte de dados. Por isso, todos os campos da imagem são exibidos. Ao escolher uma Entidade do tipo Fonte de dados, uma quantidade menor de campos será exibida. Veja mais detalhes no tópico REST.

Image Added

Figura 3 - Exemplo de consulta JPQL

Consulta JPQL gerada pela configuração do assistente visual da Figura 3:

SELECT  	c.nome,c.estado.id FROM Cidade c
WHERE		c.quantidadeHabitantes <> :minimo
GROUP BY	c.nome
HAVING 		SUM(c.quantidadeHabitantes) > :quantidadeHabitantes
ORDER BY 	c.id ASC

A Figura 3.1 exibe uma consulta do tipo SQL Nativo que possui o mesmo resultado da consulta JPQL da Figura 3.

Image Added

Figura 3.1 - Exemplo de consulta SQL Nativo

Exemplo da consulta em SQL:

SELECT      c.nome,c.fk_estado FROM CIDADE c
JOIN		ESTADO e on (e.id= c.fk_estado)
WHERE       c.quantidadehabitantes <> :minimo
GROUP BY    c.nome
HAVING      SUM(c.quantidadehabitantes) > :quantidadeHabitantes
ORDER BY    c.id ASC

select SQL('NOW()') from User u

REST

A imagem abaixo exibe o Assistente visual com uma Fonte de dados selecionada no campo Entidade a partir do bloco Abrir Consulta. Observe que apenas quatro campos de configuração são exibidos. E um deles, o campo Filtro, é exibido apenas em consultas do tipo Fonte de dados.

Image Added

Figura 3.2 - Exemplo de consulta visual com entidade do tipo Fonte de dados

Além da diferença nos campos do Assistente visual, a consulta gerada a partir de uma Fonte de dados gera uma requisição REST:

GET app/query187311?$select=nome&$filter=%28estado_uf%20eq%20%3Aestado_uf%29&$orderby=nome%20ASC