Suporte do Query Builder para Projetos API
Visão Geral
Este guia descreve como implementar Models e Utilidades do Query Builder em seu Projeto API para permitir consultas definidas pelo usuário. A implementação envolve criar um controlador, definir models do Query Builder e adicionar utilidades para executar e gerar instruções SQL dessas consultas. A customização resultante permitirá que os usuários construam consultas complexas com suporte a subconsultas, filtragem, operadores lógicos e seleção de campos, executadas eficientemente em uma fonte de dados.
Opções de Implementação
Existem duas abordagens para implementar o suporte do Query Builder em seu projeto API:
| Abordagem | Melhor Para | Nível de Esforço |
|---|---|---|
Pacote NuGet (Infragistics.QueryBuilder. Executor) | Integração rápida, casos de uso padrão | Baixo |
| Implementação Manual | Customização completa, requisitos complexos | Médio-Alto |
Opção 1: Usando o Pacote NuGet Infragistics.QueryBuilder. Executor (Recomendado)
O pacote Infragistics.QueryBuilder. Executor fornece classes, condições e métodos prontos para uso que você pode plugar diretamente em seu projeto API existente com configuração mínima.
Pré-requisitos
- .NET 8 ou .NET 9
- Microsoft.EntityFrameworkCore
- AutoMapper
- Um projeto ASP.NET Core API existente
Etapa 1: Instalar o Pacote
dotnet add package Infragistics.QueryBuilder.Executor
Etapa 2: Configurar Serviços
Em seu Program.cs ou Startup.cs, registre o serviço QueryBuilder com seu DbContext e DTO de resultado:
// Program.cs
builder.Services.AddQueryBuilder<MyDbContext, MyResultDto>();
// Obrigatório para compatibilidade com SwaggerUI
builder.Services.AddControllers().AddNewtonsoftJson(o =>
o.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore);
Etapa 3: Expor o Endpoint de Consulta
Configure o roteamento de endpoint para expor a funcionalidade do query builder:
app.UseEndpoints(endpoints =>
{
endpoints.UseQueryBuilder<MyDbContext, MyResultDto>("/api/query");
});
Etapa 4: Enviar Consultas
Sua API agora está pronta para aceitar payloads de consulta. Aqui está um exemplo de solicitação:
{
"Entity": "Users",
"ReturnFields": ["Id", "Name", "Email"],
"Operator": "And",
"FilteringOperands": [
{
"FieldName": "IsActive",
"Condition": { "Name": "equals" },
"SearchVal": true
},
{
"FieldName": "CreatedDate",
"Condition": { "Name": "after" },
"SearchVal": "2024-01-01"
}
]
}
Etapa 5: Geração SQL (Opcional)
Para diagnósticos ou análise, você pode gerar SQL a partir do modelo de consulta:
var sql = SqlGenerator.GenerateSql(query);
Console.WriteLine(sql);
// Saída: SELECT Id, Name, Email FROM Users WHERE IsActive = 1 AND CreatedDate > '2024-01-01'
Opção 2: Implementação Manual
Para projetos que exigem customização completa ou mapeamentos de entidades complexos, você pode implementar o Query Builder manualmente. A implementação é demonstrada no projeto NorthwindAPI REST API.
Pré-requisitos
- Um projeto .NET Core ou .NET API
- Familiaridade com LINQ, Entity Framework ou outro ORM para consultas de dados
- Conhecimento básico de C# e controladores ASP.NET Core
Etapa 1: Criar o QueryBuilderController
O QueryBuilderController serve como o ponto de entrada para lidar com solicitações de consulta. Recebe um objeto Query do cliente, processa-o usando o QueryExecutor e retorna os resultados.
Crie um arquivo denominado QueryBuilderController.cs em seu diretório Controllers:
[ApiController]
[Route("[controller]")]
public class QueryBuilderController : ControllerBase
{
private readonly DataContext dataContext;
private readonly IMapper mapper;
private readonly ILogger<QueryBuilderController> logger;
public QueryBuilderController(DataContext dataContext, IMapper mapper, ILogger<QueryBuilderController> logger)
{
this.dataContext = dataContext;
this.mapper = mapper;
this.logger = logger;
}
[HttpPost("ExecuteQuery")]
[Consumes("application/json")]
[Produces("application/json")]
public ActionResult<QueryBuilderResult> ExecuteQuery(Query query)
{
var sanitizedEntity = query.Entity.Replace("\r", string.Empty).Replace("\n", string.Empty);
logger.LogInformation("Executing query for entity: {Entity}", sanitizedEntity);
var t = query.Entity.ToLower(CultureInfo.InvariantCulture);
return Ok(new Dictionary<string, object[]?>
{
{
t,
t switch
{
"addresses" => dataContext.Addresses.Run<AddressDb, AddressDto>(query, mapper),
"categories" => dataContext.Categories.Run<CategoryDb, CategoryDto>(query, mapper),
"products" => dataContext.Products.Run<ProductDb, ProductDto>(query, mapper),
"regions" => dataContext.Regions. Run<RegionDb, RegionDto>(query, mapper),
"territories" => dataContext.Territories. Run<TerritoryDb, TerritoryDto>(query, mapper),
"employees" => dataContext.Employees. Run<EmployeeDb, EmployeeDto>(query, mapper),
"customers" => dataContext.Customers.Run<CustomerDb, CustomerDto>(query, mapper),
"orders" => dataContext.Orders.Run<OrderDb, OrderDto>(query, mapper),
"orderdetails" => dataContext.OrderDetails.Run<OrderDetailDb, OrderDetailDto>(query, mapper),
"shippers" => dataContext.Shippers.Run<ShipperDb, ShipperDto>(query, mapper),
"suppliers" => dataContext.Suppliers.Run<SupplierDb, SupplierDto>(query, mapper),
_ => throw new InvalidOperationException($"Unknown entity {t}"),
}
},
});
}
}
Para um exemplo completo, consulte NorthwindAPI QueryBuilderController.
Etapa 2: Definir Models do Query Builder
O Query Builder se baseia em um conjunto de models para representar a estrutura da consulta. Coloque-os em um diretório ou namespace QueryBuilder.
Enum FilterType
Define operadores lógicos para combinar filtros:
public enum FilterType
{
And = 0,
Or = 1,
}
Classe Query
Representa a estrutura geral da consulta:
public class Query
{
public string Entity { get; set; }
public string[] ReturnFields { get; set; }
public FilterType Operator { get; set; }
public QueryFilter[] FilteringOperands { get; set; }
}
| Propriedade | Descrição |
|---|---|
Entity | A entidade/tabela alvo sendo consultada (ex: “Products”) |
ReturnFields | Campos a incluir no resultado (ex: ["Name", "Price"] ou ["*"] para todos) |
Operator | Operador lógico (And ou Or) para combinar filtros |
FilteringOperands | Array de objetos QueryFilter que definem condições |
Classe QueryFilter
Representa uma condição de filtragem individual:
public class QueryFilter
{
// Condição básica
public string? FieldName { get; set; }
public bool? IgnoreCase { get; set; }
public QueryFilterCondition? Condition { get; set; }
public object? SearchVal { get; set; }
public Query? SearchTree { get; set; }
// And/Or
public FilterType? Operator { get; set; }
public QueryFilter[] FilteringOperands { get; set; }
}
Classe QueryFilterCondition
Define as condições de filtragem disponíveis:
public class QueryFilterCondition
{
public string Name { get; set; }
public bool IsUnary { get; set; }
public string IconName { get; set; }
}
Para referência, consulte NorthwindAPI QueryBuilder Models.
Etapa 3: Implementar QueryExecutor
A classe QueryExecutor processa objetos Query e os traduz em expressões LINQ para execução em fontes de dados IQueryable.
private static Expression BuildConditionExpression<TEntity>(
DataContext db,
IQueryable<TEntity> source,
QueryFilter filter,
ParameterExpression parameter)
{
if (filter. FieldName is not null && filter.Condition is not null)
{
var property = source.ElementType.GetProperty(
filter.FieldName,
BindingFlags. IgnoreCase | BindingFlags.Public | BindingFlags. Instance)
?? throw new InvalidOperationException($"Property '{filter.FieldName}' not found");
var field = Expression.Property(parameter, property);
var targetType = property.PropertyType;
var searchValue = GetSearchValue(filter.SearchVal, targetType);
Expression condition = filter.Condition.Name switch
{
"null" => Expression.Equal(field, Expression.Constant(null)),
"notNull" => Expression.NotEqual(field, Expression.Constant(null)),
"empty" => Expression.Equal(field, Expression.Constant(string.Empty)),
"notEmpty" => Expression.NotEqual(field, Expression.Constant(string.Empty)),
"equals" => Expression.Equal(field, searchValue),
"doesNotEqual" => Expression.NotEqual(field, searchValue),
"inQuery" => BuildInExpression(db, filter.SearchTree, field),
"notInQuery" => Expression.Not(BuildInExpression(db, filter.SearchTree, field)),
"contains" => CallContains(field, searchValue),
"doesNotContain" => Expression.Not(CallContains(field, searchValue)),
"startsWith" => CallStartsWith(field, searchValue),
"endsWith" => CallEndsWith(field, searchValue),
"greaterThan" => Expression.GreaterThan(field, searchValue),
"lessThan" => Expression.LessThan(field, searchValue),
"greaterThanOrEqualTo" => Expression.GreaterThanOrEqual(field, searchValue),
"lessThanOrEqualTo" => Expression.LessThanOrEqual(field, searchValue),
"before" => Expression.LessThan(field, searchValue),
"after" => Expression.GreaterThan(field, searchValue),
"today" => BuildTodayExpression(field),
"yesterday" => BuildYesterdayExpression(field),
"thisMonth" => BuildThisMonthExpression(field),
"lastMonth" => BuildLastMonthExpression(field),
"nextMonth" => BuildNextMonthExpression(field),
"thisYear" => BuildThisYearExpression(field),
"lastYear" => BuildLastYearExpression(field),
"nextYear" => BuildNextYearExpression(field),
"true" => Expression.Equal(field, Expression.Constant(true)),
"false" => Expression.Equal(field, Expression.Constant(false)),
_ => throw new NotImplementedException($"Condition not implemented: {filter.Condition. Name}"),
};
return condition;
}
else
{
// Lidar com grupos de filtros aninhados
var subexpressions = filter.FilteringOperands?
.Select(f => BuildConditionExpression(db, source, f, parameter))
.ToArray();
if (subexpressions == null || ! subexpressions.Any())
return Expression. Constant(true);
return filter.Operator == FilterType.And
? subexpressions. Aggregate(Expression.AndAlso)
: subexpressions.Aggregate(Expression.OrElse);
}
}
Condições de Filtro Suportadas
Ambas as opções de implementação suportam as seguintes condições de filtro, que se alinham com o componente Angular Query Builder (IgxQueryBuilderComponent):
Condições de String
| Condição | Descrição |
|---|---|
contains | Campo contém o valor de pesquisa |
doesNotContain | Campo não contém o valor de pesquisa |
startsWith | Campo começa com o valor de pesquisa |
endsWith | Campo termina com o valor de pesquisa |
equals | Campo é igual ao valor de pesquisa |
doesNotEqual | Campo não é igual ao valor de pesquisa |
empty | Campo está vazio |
notEmpty | Campo não está vazio |
null | Campo é nulo |
notNull | Campo não é nulo |
Condições Numéricas
| Condição | Descrição |
|---|---|
equals | Campo é igual ao valor de pesquisa |
doesNotEqual | Campo não é igual ao valor de pesquisa |
greaterThan | Campo é maior que o valor de pesquisa |
lessThan | Campo é menor que o valor de pesquisa |
greaterThanOrEqualTo | Campo é maior que ou igual ao valor de pesquisa |
lessThanOrEqualTo | Campo é menor que ou igual ao valor de pesquisa |
empty | Campo está vazio/zero |
notEmpty | Campo não está vazio/zero |
null | Campo é nulo |
notNull | Campo não é nulo |
Condições de Data/Hora
| Condição | Descrição |
|---|---|
equals | Campo é igual ao valor de pesquisa |
doesNotEqual | Campo não é igual ao valor de pesquisa |
before | Campo é anterior ao valor de pesquisa |
after | Campo é posterior ao valor de pesquisa |
today | Campo corresponde à data de hoje |
yesterday | Campo corresponde à data de ontem |
thisMonth | Campo está dentro do mês atual |
lastMonth | Campo está dentro do mês anterior |
nextMonth | Campo está dentro do próximo mês |
thisYear | Campo está dentro do ano atual |
lastYear | Campo está dentro do ano anterior |
nextYear | Campo está dentro do próximo ano |
null | Campo é nulo |
notNull | Campo não é nulo |
Condições Booleanas
| Condição | Descrição |
|---|---|
true | Campo é verdadeiro |
false | Campo é falso |
null | Campo é nulo |
notNull | Campo não é nulo |
Condições de Subconsulta
| Condição | Descrição |
|---|---|
inQuery | Valor do campo existe nos resultados da subconsulta |
notInQuery | Valor do campo não existe nos resultados da subconsulta |
Integração do Angular Frontend
A API do Query Builder foi projetada para funcionar perfeitamente com o componente Ignite UI for Angular Query Builder (IgxQueryBuilderComponent). O componente gera estruturas de consulta que correspondem ao formato de payload de API esperado.
Componentes Angular Principais
Do repositório IgniteUI/igniteui-angular:
import {
FilteringExpressionsTree,
FilteringLogic,
IgxQueryBuilderComponent,
IExpressionTree,
IgxNumberFilteringOperand,
IgxStringFilteringOperand,
IgxBooleanFilteringOperand,
IgxDateFilteringOperand,
IgxTimeFilteringOperand,
IgxDateTimeFilteringOperand
} from 'igniteui-angular';
Exemplo: Criando uma Árvore de Expressão de Consulta
// Definir entidades e campos
const entities = [
{
name: 'Products',
fields: [
{ field: 'productId', dataType: 'number' },
{ field: 'productName', dataType: 'string' },
{ field: 'unitPrice', dataType: 'number' },
{ field: 'discontinued', dataType: 'boolean' },
{ field: 'categoryId', dataType: 'number' }
]
},
{
name: 'OrderDetails',
fields: [
{ field: 'productId', dataType: 'number' },
{ field: 'quantity', dataType: 'number' },
{ field: 'discount', dataType: 'number' }
]
}
];
// Construir uma consulta complexa com subconsulta
const innerTree = new FilteringExpressionsTree(
FilteringLogic. And,
undefined,
'OrderDetails',
['productId']
);
innerTree.filteringOperands. push({
fieldName: 'quantity',
condition: IgxNumberFilteringOperand. instance().condition('greaterThanOrEqualTo'),
conditionName: 'greaterThanOrEqualTo',
searchVal: 10
});
const mainTree = new FilteringExpressionsTree(
FilteringLogic.And,
undefined,
'Products',
['*']
);
mainTree.filteringOperands.push({
fieldName: 'productId',
condition: IgxStringFilteringOperand.instance().condition('inQuery'),
conditionName: 'inQuery',
searchTree: innerTree
});
mainTree.filteringOperands.push({
fieldName: 'discontinued',
condition: IgxBooleanFilteringOperand.instance().condition('false'),
conditionName: 'false'
});
Usando o Componente Query Builder
<igx-query-builder
#queryBuilder
[entities]="entities"
[expressionTree]="expressionTree"
(expressionTreeChange)="onQueryChange($event)">
<igx-query-builder-header [title]="'Product Query Builder'">
</igx-query-builder-header>
</igx-query-builder>
Exemplo: Consulta Complexa com Subconsulta
Payload de Consulta
{
"filteringOperands": [
{
"fieldName": "categoryId",
"condition": {
"name": "equals",
"isUnary": false,
"iconName": "filter_equal"
},
"conditionName": "equals",
"searchVal": 1,
"searchTree": null,
"ignoreCase": true
},
{
"fieldName": "productId",
"condition": {
"name": "inQuery",
"isUnary": false,
"isNestedQuery": true,
"iconName": "in"
},
"conditionName": "inQuery",
"searchVal": null,
"searchTree": {
"filteringOperands": [
{
"fieldName": "quantity",
"condition": {
"name": "greaterThanOrEqualTo",
"isUnary": false,
"iconName": "filter_greater_than_or_equal"
},
"conditionName": "greaterThanOrEqualTo",
"searchVal": 10,
"searchTree": null,
"ignoreCase": true
},
{
"fieldName": "quantity",
"condition": {
"name": "lessThanOrEqualTo",
"isUnary": false,
"iconName": "filter_less_than_or_equal"
},
"conditionName": "lessThanOrEqualTo",
"searchVal": 15,
"searchTree": null,
"ignoreCase": true
}
],
"operator": 0,
"entity": "orderDetails",
"returnFields": [
"productId"
]
},
"ignoreCase": true
}
],
"operator": 0,
"entity": "products",
"returnFields": [
"productId",
"productName",
"supplierId",
"categoryId",
"quantityPerUnit",
"unitPrice",
"unitsInStock",
"unitsOnOrder",
"reorderLevel",
"discontinued"
]
}
Saída SQL Gerada
SELECT *
FROM products
WHERE categoryId = {{selectedCategory}}
AND productId IN (
SELECT productId
FROM orderDetails
WHERE quantity >= {{quantityGreaterThan}}
AND quantity <= {{quantityLessThan}}
)
Endpoint da API
POST https://data-northwind.appbuilder.dev/QueryBuilder/ExecuteQuery
Content-Type: application/json
Suporte a Localização
O componente Angular Query Builder inclui suporte integrado de localização para rótulos de condição de filtro. O repositório igniteui-angular fornece strings de recursos em várias idiomas incluindo:
- English (EN) - Padrão
- French (FR)
- German (DE)
- Spanish (ES)
- Italian (IT)
- Portuguese (PT)
- Polish (PL)
- Swedish (SV)
- E mais…
Exemplo de strings de recursos:
export const QueryBuilderResourceStringsEN: IQueryBuilderResourceStrings = {
igx_query_builder_filter_contains: 'Contains',
igx_query_builder_filter_doesNotContain: 'Does Not Contain',
igx_query_builder_filter_startsWith: 'Starts With',
igx_query_builder_filter_endsWith: 'Ends With',
igx_query_builder_filter_equals: 'Equals',
igx_query_builder_filter_doesNotEqual: 'Does Not Equal',
igx_query_builder_filter_greaterThan: 'Greater Than',
igx_query_builder_filter_lessThan: 'Less Than',
// ... mais strings
};
