Guia Passo a Passo do Query Builder no App Builder
Visão Geral do Query Builder Variable e Component
O componente Query Builder no App Builder opera através de dois conceitos principais:
- Query Variable e Query Builder Component na caixa de ferramentas.
O Query Variable, atualmente disponível apenas como parte do Preview Environment, é uma variável especializada que interage com fontes de dados, projetada para lidar eficientemente com grandes conjuntos de dados filtrando dinamicamente dados através de requisições de API. Essas requisições utilizam filtragem no servidor, impulsionada por expressões avançadas como parâmetros, garantindo desempenho ideal ao lidar com dados extensos.
Essa variável se integra com o componente Query Builder, permitindo gerenciamento dinâmico de dados e filtragem orientada pela interface do usuário.
O conceito de Query Variable abrange as duas formas principais de como o componente Query Builder é usado:
- O componente Query Builder integrado ao App Builder como um editor Query Variable.
- O componente Query Builder como um elemento de interface do usuário que os usuários finais podem interagir diretamente a partir da Canvas do App Builder quando arrastado da Caixa de Ferramentas.
Introdução Passo a Passo
Passo 1. Defina uma história de usuário e a implemente
Vamos alcançar o seguinte caso de uso: recuperar todos os Produtos da tabela products que pertencem a uma categoria selecionada e foram solicitados em quantidades dentro de um intervalo especificado na tabela orderDetails.
Exemplo Sql:
SELECT *
FROM products
WHERE categoryId = "Beverages"
AND productId IN (
SELECT productId
FROM orderDetails
WHERE quantity >= 5
AND quantity <= 10
)
-
Consulta Principal (tabela Products):
- Seleciona todas as colunas (
*) da tabela products. - Filtra produtos onde categoryId = “Beverages” (apenas produtos da categoria Beverages).
- Seleciona todas as colunas (
-
Subconsulta (tabela OrderDetails):
- Recupera productId’s de orderDetails onde a quantity solicitada está entre 5 e 10 (inclusivo).
- Esses productId’s são então usados na cláusula IN da consulta principal para filtrar produtos.
Resultado Final:
O resultado será uma lista de produtos de bebida que foram solicitados em quantidades entre 5 a 10 unidades.
Passo 2. Crie uma Query Variable
Vamos começar criando uma Query Variable. Essa Variável será usada para lidar com grandes conjuntos de dados filtrando dinamicamente dados através de requisições de API.
-
Crie uma nova variável.
-
Escolha inicializá-la a partir de uma requisição de API de dados.
-
Selecione o endpoint Query Builder recém-adicionado. O Testing OpenAPI do App Builder agora suporta filtragem no servidor.
-
Procure por endpoints “query” e escolha ExecuteQuery.products. Isso servirá como a tabela base para nosso exemplo de consulta complexa.
🖼️ Visualizar seleção de endpoint Query Builder

Seleção de endpoint
Resultado:
Passo 3. Configure a Query Variable
Primeiro, abra o painel Edit Query.
Construa a consulta complexa que funcionará com duas tabelas:
- products – A tabela principal a partir da qual os dados são recuperados.
- orderDetails – Usada na subconsulta para filtrar produtos com base na quantidade dentro de um intervalo.
💡 Observação: Em vez de valores codificados, vamos vincular cada condição a variáveis que serão atualizadas dinamicamente pelo usuário através de App Components.
Filtrar produtos por categoria selecionada:
- Comece a construir a cláusula WHERE para definir condições de consulta.
- Crie uma variável numérica com um valor padrão de 1, que será usada por um componente Select.
🖼️ Visualizar configuração de filtro de categoria

Visualizar configuração de filtro de categoria
Configure uma condição para recuperar IDs de produtos para pedidos com quantidades em um intervalo especificado:
- Crie duas variáveis numéricas (quantityGreaterThan, quantityLessThan) com valores padrão de 10 e 15.
- Essas serão controladas por um componente Input.
🖼️ Visualizar configuração de quantidade mínima

Visualizar configuração de quantidade mínima
🖼️ Visualizar configuração de quantidade máxima

Visualizar configuração de quantidade máxima
💡 Observação: Valores codificados também podem ser usados, mas para este demo, vamos usar variáveis para filtragem dinâmica.
Passo 4. Aplique e Salve a Consulta
-
Clique em Save para armazenar a configuração da Complex Query Variable.
-
Teste a execução da consulta usando o botão SEND.
Visualizar teste de execução de consulta
Neste ponto, temos quatro variáveis:
- ComplexQuery → A Query Variable que trata da filtragem no servidor.
- selectedCategory → Contém o ID da categoria.
- quantityGreaterThan → Define a quantidade mínima.
- quantityLessThan → Define a quantidade máxima.
Passo 5. Adicione Componentes Interativos
Essas variáveis serão vinculadas a componentes em nosso aplicativo de exemplo:
- Componente Select para seleção de categoria.
- Dois componentes Input para especificar intervalo de quantidade.
Adicione um componente Select e dois componentes Input, vinculando-os às variáveis criadas na Etapa 3.
🖼️ Visualizar adição de componentes

Visualizar adição de componentes
Vinculá-los:
Componente Select: Foque no componente Select e clique no Select item. Aplique um data repeater a ele usando a tabela Category da fonte de dados Northwind.
🖼️ Visualizar configuração de data repeater

Visualizar configuração de data repeater
Vincule o Conteúdo e o Valor do elemento Select item a Category -> Name e CategoryID.
🖼️ Visualizar vinculação de item selecionado

Visualizar vinculação de item selecionado
Foque no componente Select e vincule-o à variável selectedCategory:
🖼️ Visualizar vinculação de componente select

Visualizar vinculação de componente select
Componente Input para Quantity greater than:
🖼️ Visualizar vinculação de entrada de quantidade mínima

Visualizar vinculação de entrada de quantidade mínima
Componente Input para Quantity less than:
🖼️ Visualizar vinculação de entrada de quantidade máxima

Visualizar vinculação de entrada de quantidade máxima
- Certifique-se de que a vinculação bidirecional para suas propriedades Value está habilitada.
- Adicione um componente Grid e vincule-o à Query Variable criada na Etapa 2.
🖼️ Visualizar vinculação de componente grid

Visualizar vinculação de componente grid
Resultado:
Visualizar resultado de componentes interativos
Passo 6. Exiba Produtos Solicitados em Quantidades Específicas
Até agora, nossa consulta retorna todos os produtos que pertencem à categoria Dairy Products e foram solicitados em quantidades entre 5 e 7.
🖼️ Visualizar resultados de consulta iniciais

Visualizar resultados de consulta iniciais
No entanto, as quantidades reais do pedido não são visíveis, já que nossa consulta apenas recupera dados da tabela products. Para validar os resultados, precisamos modificar a interface do usuário para exibir as quantidades de pedidos correspondentes.
Passo 7. Mostre Quantidades de Pedidos por Produto Usando Seleção de Linha de Grid
-
Adicione uma interação Grid Row Selection Changed e vincule uma variável a ela.
🖼️ Visualizar interação de seleção de linha de grid

Visualizar interação de seleção de linha de grid
-
Certifique-se de que a variável é do tipo ProductDTO
🖼️ Visualizar configuração de tipo de variável

Visualizar configuração de tipo de variável
-
Adicione um Dialog e um Grid dentro dele para exibir os dados relevantes.
🖼️ Visualizar configuração de diálogo e grid

Visualizar configuração de diálogo e grid
-
Configure outra Query Variable que recupere detalhes de pedidos para produtos dentro de uma categoria específica.
Exemplo de Consulta:
SELECT * FROM orderDetails WHERE productId IN ( SELECT productId FROM products WHERE categoryId = 1 ) AND Quantity BETWEEN 5 AND 15;Resultado:
Visualizar resultado de consulta de detalhes de pedidos
-
Vincule o componente Grid à OrdersComplexQuery Variable
🖼️ Visualizar vinculação de grid a detalhes de pedidos

Visualizar vinculação de grid a detalhes de pedidos
Passo 8. Visualize o Aplicativo
- Clique em Preview.
- Ajuste dinamicamente os resultados da consulta usando os componentes Input.
- Exemplo de caso de uso:
- Procure pela categoria Confections.
- Defina Quantity entre 4 e 8.
🖼️ Visualizar visualização de aplicativo com exemplo Confections

Visualizar visualização de aplicativo com exemplo Confections
Passo 9. Modifique Consultas em Tempo Real Usando o Query Builder
Esta etapa demonstra como a consulta pode ser modificada em tempo real. Em vez de filtrar pedidos dentro de um intervalo de quantidade, vamos alterá-lo para maior que ou igual a uma quantidade específica.
- Arraste e solte um componente Query Builder da Caixa de Ferramentas.
🖼️ Visualizar adição de componente Query Builder

Visualizar adição de componente Query Builder
-
Vincule-o à Complex Query Variable criada anteriormente.
-
Agora, o Componente Query está vinculado à Query Variable, tratando dinamicamente requisições de dados.
🖼️ Visualizar resultado de vinculação Query Builder

Visualizar resultado de vinculação Query Builder
Antes de Editar a Consulta - A consulta retorna todos os Confections com quantidades entre 5 e 11.
Visualizar resultados de consulta antes da edição
Após Editar a Consulta: - Modifique a cláusula WHERE para retornar pedidos com Quantity ≥ 10 removendo a segunda condição.
Visualizar resultados de consulta após edição
FAQs
- Por que o Query Builder não usa OData? OData não possui suporte para subconsultas, enquanto o Query Builder principalmente constrói uma árvore de condições, algumas expressões podem ser mapeadas para filtros compatíveis com OData. No entanto, o suporte completo não é garantido devido às limitações do OData.
O Query Builder fornece mais flexibilidade ao permitir controle direto sobre a lógica de filtragem, possibilitando melhor suporte para cenários complexos como subconsultas, que OData não suporta nativamente.
Problemas Conhecidos e Limitações
- Sem Geração de Código - você receberá a mensagem “Component not supported” ao tentar gerar código do aplicativo com Query Variable ou Query Builder
- Componente Query em Visualização - você tem controle total sobre as condições, mas perde as vinculações, obtém os valores atuais (5 e 10). Você tem que re-adicionar o componente e começar novamente se quiser trazer de volta o estado inicial da variável.
- Não estamos permitindo que você defina campos específicos ao fazer a requisição, você sempre receberá todos os campos, porque não temos um mecanismo para deixar outros componentes saberem sobre isso, o que levaria a inconsistências.
- Os campos de retorno do Query Builder estão desabilitados - Desabilitar a mudança de campos de retorno do query builder é necessário porque, embora selecionar um subconjunto de campos funcione em termos de dados, o App Builder não suporta estruturas dinâmicas. Consequentemente, ao instanciar um Grid, assume que todas as colunas estão disponíveis
- Se problemas ou inconsistências aparecerem, atualize a página (F5).
Suporte de Recurso Transversal
- Suporte a Repeater: Não disponível.
- Copiar e Colar:
- Dentro da mesma visualização: Suportado.
- Entre diferentes visualizações: Deveria trazer a Query Variable vinculada?
- Propriedades Vinculáveis: Apenas a propriedade “Query” suporta vinculação de variável.
Sensibilidade de Maiúsculas e Minúsculas no Servidor
- Se você implementar seu próprio servidor de dados, considere não configurar nomes de campos sensíveis a maiúsculas.
