Skip to content

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:

AbordagemMelhor ParaNível de Esforço
Pacote NuGet (Infragistics.QueryBuilder. Executor)Integração rápida, casos de uso padrãoBaixo
Implementação ManualCustomização completa, requisitos complexosMé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.

NuGet

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; }
}
PropriedadeDescrição
EntityA entidade/tabela alvo sendo consultada (ex: “Products”)
ReturnFieldsCampos a incluir no resultado (ex: ["Name", "Price"] ou ["*"] para todos)
OperatorOperador lógico (And ou Or) para combinar filtros
FilteringOperandsArray 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çãoDescrição
containsCampo contém o valor de pesquisa
doesNotContainCampo não contém o valor de pesquisa
startsWithCampo começa com o valor de pesquisa
endsWithCampo termina com o valor de pesquisa
equalsCampo é igual ao valor de pesquisa
doesNotEqualCampo não é igual ao valor de pesquisa
emptyCampo está vazio
notEmptyCampo não está vazio
nullCampo é nulo
notNullCampo não é nulo

Condições Numéricas

CondiçãoDescrição
equalsCampo é igual ao valor de pesquisa
doesNotEqualCampo não é igual ao valor de pesquisa
greaterThanCampo é maior que o valor de pesquisa
lessThanCampo é menor que o valor de pesquisa
greaterThanOrEqualToCampo é maior que ou igual ao valor de pesquisa
lessThanOrEqualToCampo é menor que ou igual ao valor de pesquisa
emptyCampo está vazio/zero
notEmptyCampo não está vazio/zero
nullCampo é nulo
notNullCampo não é nulo

Condições de Data/Hora

CondiçãoDescrição
equalsCampo é igual ao valor de pesquisa
doesNotEqualCampo não é igual ao valor de pesquisa
beforeCampo é anterior ao valor de pesquisa
afterCampo é posterior ao valor de pesquisa
todayCampo corresponde à data de hoje
yesterdayCampo corresponde à data de ontem
thisMonthCampo está dentro do mês atual
lastMonthCampo está dentro do mês anterior
nextMonthCampo está dentro do próximo mês
thisYearCampo está dentro do ano atual
lastYearCampo está dentro do ano anterior
nextYearCampo está dentro do próximo ano
nullCampo é nulo
notNullCampo não é nulo

Condições Booleanas

CondiçãoDescrição
trueCampo é verdadeiro
falseCampo é falso
nullCampo é nulo
notNullCampo não é nulo

Condições de Subconsulta

CondiçãoDescrição
inQueryValor do campo existe nos resultados da subconsulta
notInQueryValor 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
};

Referências Adicionais