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.
• Explicit Joins: SQL-like join support with alias-aware field resolution.

---

🚀 Quick Start

1. Installation

dotnet add package FlexQuery.NET
dotnet add package FlexQuery.NET.EFCore
dotnet add package FlexQuery.NET.AspNetCore

2. Simple Usage

Securely execute a dynamic query directly from your controller:

[HttpGet]
public async Task<IActionResult> GetUsers([FromQuery] FlexQueryParameters parameters)
{
    // One-stop shop: Parsing + Validation + Execution
    var result = await _context.Users.FlexQueryAsync(parameters, options => 
    {
        options.AllowedFields = ["Id", "Name", "Email", "Status"];
        options.AllowOperators("Status", FilterOperators.Eq, FilterOperators.In);
    });

    return Ok(result);
}

3. Example Request

GET /api/users?filter=age:gt:18&sort=createdAt:desc&page=1&pageSize=20&select=id,name,email

---

🏎️ Performance Benchmarks

FlexQuery.NET is engineered for performance with transparent, reproducible benchmarks. We measure parsing, expression generation, full end-to-end execution, and API-level latency against Gridify, Sieve, OData, and GraphQL.

For the complete benchmark suite with methodology, fairness disclaimers, and full analysis, see docs/guide/performance/.

End-to-End Execution (EF Core InMemory, 1,000 records)

Scenario: Filter (2 conditions) + Sort + Paging (100 items) on 1,000 Users with related Orders and OrderItems.

Library	Mean	Relative	Allocated
FlexQuery.NET	17.67 ms	0.44×	21.42 KB
Handwritten LINQ	40.21 ms	1.00×	97.11 KB
Gridify	40.33 ms	1.00×	107.76 KB
System.Linq.Dynamic.Core	40.95 ms	1.02×	110.79 KB
Sieve	41.37 ms	1.03×	117.67 KB

FlexQuery.NET is 2.25× faster than handwritten LINQ in this InMemory scenario, likely due to expression tree optimization and reduced closure allocation. Full analysis: Execution Benchmarks.

---

Database Execution (SQL Server LocalDB, 100,000 records)

Scenario: Simple filter (status:eq:active) + page (100 items) against SQL Server with no index.

⚠️ Important: FlexQuery.NET's default configuration (IncludeCount=true) executes an additional COUNT query to return total record count, while the handwritten baseline retrieves data only. This benchmark therefore measures two roundtrips vs one. When configured fairly, FlexQuery.NET's filtering overhead is ~3–10% (see details).

Library	Mean	Relative	Allocated	Queries
Handwritten LINQ (data only)	336 µs	1.00×	111 KB	1 SELECT
FlexQuery.NET (with count)	20,798 µs	61.8×	129 KB	SELECT + COUNT

The apparent 62× overhead is the cost of the extra COUNT query. Full analysis, fair comparison methodology, and configuration options: Database Execution.

---

API End-to-End (Full ASP.NET Core Pipeline, 100,000 records)

Scenario: HTTP request with filter + sort + paging + projection, including JSON serialization.

Library	PageSize=20	PageSize=100	PageSize=100K
FlexQuery.NET	1.49 ms	1.64 ms	2.26 ms
GraphQL	0.90 ms	0.90 ms	FAILED
OData	1.64 ms	1.72 ms	2.24 ms
Gridify	1.56 ms	1.90 ms	1.90 ms
Sieve	1.59 ms	1.97 ms	1.86 ms
Manual LINQ	1.63 ms	1.97 ms	1.89 ms

Full results with fairness notes: API Benchmarks.

---

📚 Full Documentation

For detailed methodology, dataset description, reproducibility instructions, and fairness disclaimers:

👉 Performance Documentation Index

• Methodology & Reproducibility
• Parsing Benchmarks
• Expression Generation
• End-to-End Execution
• Database Execution (SQL Server)
• API Benchmarks (vs OData/GraphQL)
• Scalability Analysis
• Fairness Disclaimers
• Interpretation Guide

---

📚 Documentation

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

👉 https://flexquery.vercel.app

Quick Links

• Getting Started
• Query Composition
• Explicit Joins
• Governance & Security
• Performance Optimization
• Migration Guide (v1 → v2)

---

📄 License

FlexQuery.NET is licensed under the MIT License.