Skip to content

Soporte del Generador de Consultas para Proyectos API

Descripción General

Esta guía describe cómo implementar Modelos y Utilidades del Generador de Consultas en su Proyecto API para permitir consultas definidas por el usuario. La implementación implica crear un controlador, definir modelos del Generador de Consultas y agregar utilidades para ejecutar y generar instrucciones SQL a partir de estas consultas. La personalización resultante permitirá a los usuarios construir consultas complejas con soporte de subconsultas, filtrado, operadores lógicos y selección de campos, ejecutados eficientemente contra una fuente de datos.

Opciones de Implementación

Hay dos enfoques para implementar el soporte del Generador de Consultas en su proyecto API:

EnfoqueIdeal ParaNivel de Esfuerzo
Paquete NuGet (Infragistics.QueryBuilder. Executor)Integración rápida, casos de uso estándarBajo
Implementación ManualPersonalización completa, requisitos complejosMedio-Alto

Opción 1: Usar el Paquete NuGet Infragistics.QueryBuilder. Executor (Recomendado)

El paquete Infragistics.QueryBuilder. Executor proporciona clases listas para usar, condiciones y métodos que puede integrar directamente en su proyecto API existente con mínima configuración.

NuGet

Requisitos Previos

  • .NET 8 o .NET 9
  • Microsoft.EntityFrameworkCore
  • AutoMapper
  • Un proyecto ASP.NET Core API existente

Paso 1: Instalar el Paquete

dotnet add package Infragistics.QueryBuilder.Executor

Paso 2: Configurar Servicios

En su Program.cs o Startup.cs, registre el servicio QueryBuilder con su DbContext y DTO de resultado:

// Program.cs
builder.Services.AddQueryBuilder<MyDbContext, MyResultDto>();

// Requerido para compatibilidad con SwaggerUI
builder.Services.AddControllers().AddNewtonsoftJson(o => 
    o.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore);

Paso 3: Exponer el Punto Final de Consulta

Configure el enrutamiento de punto final para exponer la funcionalidad del Generador de Consultas:

app.UseEndpoints(endpoints => 
{ 
    endpoints.UseQueryBuilder<MyDbContext, MyResultDto>("/api/query"); 
});

Paso 4: Enviar Consultas

Su API ahora está lista para aceptar cargas de consultas. Aquí hay un ejemplo de solicitud:

{
    "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"
        }
    ]
}

Paso 5: Generación SQL (Opcional)

Para diagnósticos o análisis, puede generar SQL a partir del modelo de consulta:

var sql = SqlGenerator.GenerateSql(query);
Console.WriteLine(sql);
// Output: SELECT Id, Name, Email FROM Users WHERE IsActive = 1 AND CreatedDate > '2024-01-01'

Opción 2: Implementación Manual

Para proyectos que requieren personalización completa o asignaciones de entidades complejas, puede implementar el Generador de Consultas manualmente. La implementación se demuestra en el proyecto NorthwindAPI REST API.

Requisitos Previos

  • Un proyecto .NET Core o .NET API
  • Familiaridad con LINQ, Entity Framework u otro ORM para consultas de datos
  • Conocimiento básico de C# y controladores ASP.NET Core

Paso 1: Crear el QueryBuilderController

El QueryBuilderController sirve como punto de entrada para manejar solicitudes de consultas. Recibe un objeto Query del cliente, lo procesa utilizando QueryExecutor y devuelve los resultados.

Cree un archivo llamado QueryBuilderController.cs en su directorio 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 un ejemplo completo, vea NorthwindAPI QueryBuilderController.

Paso 2: Definir Modelos del Generador de Consultas

El Generador de Consultas se basa en un conjunto de modelos para representar la estructura de consulta. Coloque estos en un directorio o espacio de nombres QueryBuilder.

Enumeración FilterType

Define operadores lógicos para combinar filtros:

public enum FilterType
{
    And = 0,
    Or = 1,
}

Clase Query

Representa la estructura general de la consulta:

public class Query
{
    public string Entity { get; set; }
    public string[] ReturnFields { get; set; }
    public FilterType Operator { get; set; }
    public QueryFilter[] FilteringOperands { get; set; }
}
PropiedadDescripción
EntityLa entidad/tabla de destino que se consulta (por ejemplo, “Products”)
ReturnFieldsCampos a incluir en el resultado (por ejemplo, ["Name", "Price"] o ["*"] para todos)
OperatorOperador lógico (And u Or) para combinar filtros
FilteringOperandsMatriz de objetos QueryFilter que definen condiciones

Clase QueryFilter

Representa una condición de filtrado individual:

public class QueryFilter
{
    // Condición 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; }
    // Y/O
    public FilterType?  Operator { get; set; }
    public QueryFilter[] FilteringOperands { get; set; }
}

Clase QueryFilterCondition

Define condiciones de filtrado disponibles:

public class QueryFilterCondition
{
    public string Name { get; set; }
    public bool IsUnary { get; set; }
    public string IconName { get; set; }
}

Para referencia, vea NorthwindAPI QueryBuilder Models.

Paso 3: Implementar QueryExecutor

La clase QueryExecutor procesa objetos Query y los traduce en expresiones LINQ para ejecutarlos contra fuentes de datos 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
    {
        // Manejar grupos de filtros anidados
        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);
    }
}

Condiciones de Filtrado Compatibles

Ambas opciones de implementación soportan las siguientes condiciones de filtrado, que se alinean con el componente Angular Query Builder (IgxQueryBuilderComponent):

Condiciones de Cadena

CondiciónDescripción
containsEl campo contiene el valor de búsqueda
doesNotContainEl campo no contiene el valor de búsqueda
startsWithEl campo comienza con el valor de búsqueda
endsWithEl campo termina con el valor de búsqueda
equalsEl campo es igual al valor de búsqueda
doesNotEqualEl campo no es igual al valor de búsqueda
emptyEl campo está vacío
notEmptyEl campo no está vacío
nullEl campo es nulo
notNullEl campo no es nulo

Condiciones Numéricas

CondiciónDescripción
equalsEl campo es igual al valor de búsqueda
doesNotEqualEl campo no es igual al valor de búsqueda
greaterThanEl campo es mayor que el valor de búsqueda
lessThanEl campo es menor que el valor de búsqueda
greaterThanOrEqualToEl campo es mayor que o igual al valor de búsqueda
lessThanOrEqualToEl campo es menor que o igual al valor de búsqueda
emptyEl campo está vacío/cero
notEmptyEl campo no está vacío/cero
nullEl campo es nulo
notNullEl campo no es nulo

Condiciones de Fecha/Hora

CondiciónDescripción
equalsEl campo es igual al valor de búsqueda
doesNotEqualEl campo no es igual al valor de búsqueda
beforeEl campo es anterior al valor de búsqueda
afterEl campo es posterior al valor de búsqueda
todayEl campo coincide con la fecha de hoy
yesterdayEl campo coincide con la fecha de ayer
thisMonthEl campo está dentro del mes actual
lastMonthEl campo está dentro del mes anterior
nextMonthEl campo está dentro del próximo mes
thisYearEl campo está dentro del año actual
lastYearEl campo está dentro del año anterior
nextYearEl campo está dentro del próximo año
nullEl campo es nulo
notNullEl campo no es nulo

Condiciones Booleanas

CondiciónDescripción
trueEl campo es verdadero
falseEl campo es falso
nullEl campo es nulo
notNullEl campo no es nulo

Condiciones de Subconsulta

CondiciónDescripción
inQueryEl valor del campo existe en los resultados de la subconsulta
notInQueryEl valor del campo no existe en los resultados de la subconsulta

Integración del Frontend Angular

La API del Generador de Consultas está diseñada para funcionar sin problemas con el componente Generador de Consultas de Ignite UI para Angular (IgxQueryBuilderComponent). El componente genera estructuras de consulta que coinciden con el formato de carga útil API esperado.

Componentes Angular Clave

Del repositorio IgniteUI/igniteui-angular:

import {
    FilteringExpressionsTree,
    FilteringLogic,
    IgxQueryBuilderComponent,
    IExpressionTree,
    IgxNumberFilteringOperand,
    IgxStringFilteringOperand,
    IgxBooleanFilteringOperand,
    IgxDateFilteringOperand,
    IgxTimeFilteringOperand,
    IgxDateTimeFilteringOperand
} from 'igniteui-angular';

Ejemplo: Crear un Árbol de Expresión de Consulta

// Definir entidades y 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 una consulta compleja con 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'
});

Usar el 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>

Ejemplo: Consulta Compleja con Subconsulta

Carga Útil 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"
    ]
}

Salida SQL Generada

SELECT * 
FROM products 
WHERE categoryId = {{selectedCategory}} 
AND productId IN ( 
    SELECT productId 
    FROM orderDetails 
    WHERE quantity >= {{quantityGreaterThan}} 
    AND quantity <= {{quantityLessThan}} 
)

Punto Final API

POST https://data-northwind.appbuilder.dev/QueryBuilder/ExecuteQuery
Content-Type: application/json

Soporte de Localización

El componente Angular Query Builder incluye soporte de localización integrado para etiquetas de condiciones de filtrado. El repositorio igniteui-angular proporciona cadenas de recursos en varios idiomas incluyendo:

  • English (EN) - Predeterminado
  • French (FR)
  • German (DE)
  • Spanish (ES)
  • Italian (IT)
  • Portuguese (PT)
  • Polish (PL)
  • Swedish (SV)
  • Y más…

Ejemplo de cadenas 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',
    // ... más cadenas
};

Referencias Adicionales