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:
| Enfoque | Ideal Para | Nivel de Esfuerzo |
|---|---|---|
Paquete NuGet (Infragistics.QueryBuilder. Executor) | Integración rápida, casos de uso estándar | Bajo |
| Implementación Manual | Personalización completa, requisitos complejos | Medio-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.
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; }
}
| Propiedad | Descripción |
|---|---|
Entity | La entidad/tabla de destino que se consulta (por ejemplo, “Products”) |
ReturnFields | Campos a incluir en el resultado (por ejemplo, ["Name", "Price"] o ["*"] para todos) |
Operator | Operador lógico (And u Or) para combinar filtros |
FilteringOperands | Matriz 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ón | Descripción |
|---|---|
contains | El campo contiene el valor de búsqueda |
doesNotContain | El campo no contiene el valor de búsqueda |
startsWith | El campo comienza con el valor de búsqueda |
endsWith | El campo termina con el valor de búsqueda |
equals | El campo es igual al valor de búsqueda |
doesNotEqual | El campo no es igual al valor de búsqueda |
empty | El campo está vacío |
notEmpty | El campo no está vacío |
null | El campo es nulo |
notNull | El campo no es nulo |
Condiciones Numéricas
| Condición | Descripción |
|---|---|
equals | El campo es igual al valor de búsqueda |
doesNotEqual | El campo no es igual al valor de búsqueda |
greaterThan | El campo es mayor que el valor de búsqueda |
lessThan | El campo es menor que el valor de búsqueda |
greaterThanOrEqualTo | El campo es mayor que o igual al valor de búsqueda |
lessThanOrEqualTo | El campo es menor que o igual al valor de búsqueda |
empty | El campo está vacío/cero |
notEmpty | El campo no está vacío/cero |
null | El campo es nulo |
notNull | El campo no es nulo |
Condiciones de Fecha/Hora
| Condición | Descripción |
|---|---|
equals | El campo es igual al valor de búsqueda |
doesNotEqual | El campo no es igual al valor de búsqueda |
before | El campo es anterior al valor de búsqueda |
after | El campo es posterior al valor de búsqueda |
today | El campo coincide con la fecha de hoy |
yesterday | El campo coincide con la fecha de ayer |
thisMonth | El campo está dentro del mes actual |
lastMonth | El campo está dentro del mes anterior |
nextMonth | El campo está dentro del próximo mes |
thisYear | El campo está dentro del año actual |
lastYear | El campo está dentro del año anterior |
nextYear | El campo está dentro del próximo año |
null | El campo es nulo |
notNull | El campo no es nulo |
Condiciones Booleanas
| Condición | Descripción |
|---|---|
true | El campo es verdadero |
false | El campo es falso |
null | El campo es nulo |
notNull | El campo no es nulo |
Condiciones de Subconsulta
| Condición | Descripción |
|---|---|
inQuery | El valor del campo existe en los resultados de la subconsulta |
notInQuery | El 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
};
