---
paths:
  - "*QueryableProvider*.cs"
  - "*AlterQueryable*.cs"
  - "*DynamicQuery*.cs"
  - "*Interceptor*.cs"
---

# Dynamic Queries — The Default Query Pattern

**99% of queries should be dynamic queries.** They provide pagination, filtering, sorting, grouping, and aggregation for free.

## The Standard Pattern: IQueryableProviderOverride

```csharp
// File: Features/Orders/OrderQueryableProvider.cs
public class OrderQueryableProvider : IQueryableProviderOverride<Order>
{
    private readonly AppDbContext _db;
    public OrderQueryableProvider(AppDbContext db) => _db = db;

    public Task<IQueryable<Order>> GetQueryableAsync(object query, CancellationToken ct = default)
        => Task.FromResult(_db.Orders.AsQueryable());
}
```

Registration — one line:
```csharp
builder.Services.AddDynamicQueryWithProvider<Order, OrderQueryableProvider>();
```

This automatically creates endpoints with full filtering, sorting, and pagination support.

## Required Dependencies

These must be registered before `AddSvrntyCqrs`:
```csharp
builder.Services.AddTransient<IAsyncQueryableService, SimpleAsyncQueryableService>();
builder.Services.AddTransient<IQueryHandlerAsync, QueryHandlerAsync>();
```

## Alter Queryable Services (Security Filters, Tenant Isolation)

Use `IAlterQueryableService` to modify the queryable before execution — for security filters, tenant isolation, default ordering, etc.

```csharp
public class OrderTenantFilter : IAlterQueryableService<Order, Order>
{
    private readonly ITenantContext _tenant;
    public OrderTenantFilter(ITenantContext tenant) => _tenant = tenant;

    public Task<IQueryable<Order>> AlterQueryableAsync(
        IQueryable<Order> query,
        IDynamicQuery dynamicQuery,
        CancellationToken ct = default)
    {
        return Task.FromResult(query.Where(o => o.TenantId == _tenant.Id));
    }
}
```

Registration:
```csharp
builder.Services.AddAlterQueryable<Order, Order, OrderTenantFilter>();
```

## Interceptors

Up to 5 interceptors per query type. These modify the PoweredSoft DynamicQuery criteria at query build time.

```csharp
builder.Services.AddDynamicQueryInterceptor<Order, Order, OrderInterceptor>();
```

## Source to Destination Mapping

When the entity type differs from the DTO:
```csharp
// Provider returns the source entity queryable
public class OrderQueryableProvider : IQueryableProviderOverride<Order> { ... }

// Registration maps source -> destination
builder.Services.AddDynamicQueryWithProvider<Order, OrderDto, OrderQueryableProvider>();
```

## Key Interfaces

```csharp
IQueryableProvider<TSource>
    Task<IQueryable<TSource>> GetQueryableAsync(object query, CancellationToken ct)

IQueryableProviderOverride<TSource> : IQueryableProvider<TSource>
    // Marker interface — same method, signals override registration

IAlterQueryableService<TSource, TDestination>
    Task<IQueryable<TSource>> AlterQueryableAsync(IQueryable<TSource> query, IDynamicQuery dynamicQuery, CancellationToken ct)
```