FlexQuery.NET.Parsers.Jql 3.0.1

FlexQuery.NET

Dynamic filtering, sorting, paging, and projection for IQueryable in .NET.

FlexQuery.NET is a lightweight and powerful dynamic query engine for .NET. It allows you to transform complex API query parameters into optimized, EF Core-translatable expression trees with a single line of code.

⚡ Key Features

• Dynamic Querying: Powerful DSL, JQL, and JSON-based filtering.
• IQueryable-Native: 100% server-side translation—no client-side evaluation.
• Advanced Projection: Automatic SQL SELECT optimization including nested includes.
• Governance & Security: Built-in field-level validation and operator restrictions.
• High Performance: Thread-safe expression caching for ultra-low latency.

🚀 Quick Start

1. Installation

dotnet add package FlexQuery.NET
dotnet add package FlexQuery.NET.EntityFrameworkCore
dotnet add package FlexQuery.NET.Dapper
dotnet add package FlexQuery.NET.AspNetCore
dotnet add package FlexQuery.NET.Adapters.AgGrid

2. Entity Framework Core (Default)

Securely execute a dynamic query directly from your controller against an EF Core DbContext. The provider handles translation, pagination, and async execution automatically.

[HttpGet("users")]
public async Task<IActionResult> GetUsers([FromQuery] FlexQueryParameters parameters)
{
    var result = await _context.Users.FlexQueryAsync(parameters, options => 
    {
        options.AllowedFields = new HashSet<string> { "Id", "Name", "Email", "Status" };
        options.StrictFieldValidation = true;
        options.UseNoTracking = true; // Optimization for read-only queries
    });

    return Ok(result);
}

3. Dapper & Raw SQL Integration

For high-performance API endpoints or non-EF Core projects, use the Dapper provider to generate secure, dialect-aware, fully parameterized SQL queries.

using FlexQuery.NET.Dapper;
using FlexQuery.NET.Dapper.Dialects;

[HttpGet("users")]
public async Task<IActionResult> GetUsersDapper([FromQuery] FlexQueryParameters parameters)
{
    using var connection = new SqlConnection("Server=...;");    
    // Generates parameterized SQL, handles dialects (SQL Server, Postgres, MySQL, etc.)
    var result = await connection.FlexQueryAsync<User>(parameters, options => 
    {
        options.Dialect = new SqlServerDialect(); 
        options.AllowedFields = new HashSet<string> { "Id", "Name", "Email" };
    });

    return Ok(result);
}

4. AG Grid Adapter

FlexQuery.NET.Adapters.AgGrid parses AG Grid's Enterprise Server-Side Row Model JSON payloads natively, translating pagination, filtering, sorting, row grouping, and aggregations into FlexQuery operations.

using FlexQuery.NET.Adapters.AgGrid.Parsers;

[HttpPost("grid")]
public async Task<IActionResult> GetGridData([FromBody] JsonElement agGridPayload)
{
    // 1. Parse AG Grid request into canonical QueryOptions
    var options = AgGridQueryOptionsParser.Parse(agGridPayload);

    // 2. Execute via EF Core or Dapper
    var result = await _context.Users.FlexQueryAsync<User>(options, opts =>
    {
        opts.AllowedFields = new HashSet<string> { "Id", "Name", "Status", "CreatedAt" };
    });

    // 3. Return format expected by AG Grid
    return Ok(new { rowData = result.Data, rowCount = result.TotalCount });
}

5. MiniOData Parser

Migrating from OData? FlexQuery.NET.Parsers.MiniOData acts as a drop-in bridge, automatically detecting and parsing OData syntax ($filter, $orderby, $top, $skip) on the same endpoint that handles JSON and JQL queries.

// Program.cs
builder.Services.AddFlexQueryMiniOData();

// Controller
[HttpGet("products")]
public async Task<IActionResult> GetProducts([FromQuery] FlexQueryParameters parameters)
{
    // Auto-detects OData parameters like:
    // ?$filter=Price gt 50 and Category eq 'Electronics'&$orderby=Name desc
    var result = await _context.Products.FlexQueryAsync(parameters);
    return Ok(result);
}

6. Example Query Requests

FlexQuery unifies multiple formats under the same API without configuration:

# Native DSL
GET /api/users?filter=age:gt:18&sort=createdAt:desc&page=1&pageSize=20

# JQL Syntax
GET /api/users?filter=Age > 18 AND Status = 'Active'

# OData Syntax (requires MiniOData package)
GET /api/users?$filter=Age gt 18 and Status eq 'Active'

📚 Documentation

For detailed guides, API references, and advanced scenarios, visit our documentation site:

👉 https://flexquery.vercel.app

Quick Links

• Getting Started
• Query Composition
• Security & Field Access
• Dapper Provider
• AG Grid Integration
• MiniOData Parser

📄 License

FlexQuery.NET is licensed under the MIT License.