Breaking Changes & Known Limitations

DynamicWhere.ex is intentionally opinionated about how queries are shaped. The twenty-nine points below cover constraints, surprises, and corner cases — read them before designing an API around the library so you can pick the right entry points and avoid runtime exceptions in production.

1. Parameterless Constructor Required for Select Projection

Select<T>(fields) requires T to have a parameterless (default) constructor. If T does not have one, a LogicException is thrown, with SelectTypeMustHaveParameterlessConstructor as its Message and the type's name on Subject — see point 17 for what that message used to be. Most EF Core entity classes have parameterless constructors by default.

2. Segment Operations are Async-Only

ToListAsync<T>(Segment) is the only entry point for segment queries. There is no synchronous ToList<T>(Segment) variant. The condition sets are combined into one query that the database orders and pages (point 19). Under ApplyPolicy, DwCaps.MaxConditionSets (default 10) bounds how many sets one request may carry.

3. Case-Insensitive Operators use .ToLower()

All I* operators (e.g., IContains, IEqual) normalize both sides via .ToLower(). This works correctly with SQL Server (COLLATE is typically case‑insensitive), but be aware of potential performance or behavior differences on case‑sensitive database collations (e.g., PostgreSQL with C locale).

4. Enum Filtering Matches the Member Name, Whatever the Column Stores

DataType.Enum compares the member name you send ("Pending"), and it works whether the column stores names or integers: the dynamic LINQ parser converts the name to the enum value before EF Core translates the comparison. DataType.Enum has no value-format check at all, so nothing is rejected at validation time.

5. Having Clause Fields Reference Aliases, Not Entity Properties

In a Summary, Having is itself a ConditionGroup, so the path is Having.Conditions[].Field — and each field in its nested SubConditionGroups as well. Every one of them must match an AggregateBy.Alias, not an entity property path.

6. GroupBy Flattens Dotted Field Names in Results

Dotted GroupBy fields (e.g., Category.Name) produce flattened alias keys in the dynamic result objects (e.g., CategoryName). Order fields in Summary.Orders should use the dotted form; the library handles alias mapping internally.

7. Collection Navigation Auto-Wraps with .Any()

When a condition's Field path traverses a collection property, the library automatically inserts .Any() lambdas. This means the filter checks if any item in the collection matches — there is no built‑in .All() support.

8. Thread-Safe Cache, But Configuration Changes are Eventually Consistent

CacheExpose.Configure() is thread‑safe, but already‑in‑progress operations may use the previous configuration until they complete.

9. getQueryString Parameter Requires EF Core Provider

Passing getQueryString: true to ToList / ToListAsync calls .ToQueryString(), which needs an active EF Core database provider to produce SQL. On an in‑memory IEnumerable<T> it does not fail: QueryString holds a placeholder sentence where the SQL would be.

10. SelectDynamic / FilterDynamic / ToListDynamic / ToListAsyncDynamic Return Non-Generic Types

These methods return IQueryable or FilterResult<dynamic> instead of the strongly‑typed equivalents. Downstream code must work with dynamic objects. Property names in the dynamic result follow these rules:

• Non‑dotted paths (Name, Category, OrderItems, …) are projected as‑is — access them by their exact field name at runtime.
• Dotted paths through reference navigations (e.g., Category.Name) produce nested dynamic objects reflecting the navigation hierarchy — access them as result.Category.Name, not as a flat CategoryName.
• Dotted paths through collection navigations (e.g., Category.Vendors.Id) generate a Select lambda per collection segment — the result is a nested collection of dynamic objects accessible as result.Category.Vendors[0].Id.
• Multiple dotted fields sharing the same root segment (e.g., Category.Name + Category.Id) are merged into a single nested object: result.Category.Name and result.Category.Id.
• Mixed whole‑navigation + sub‑field paths: when both "Category" and "Category.Name" are requested, the sub‑field projection takes precedence and "Category" is silently dropped.

11. All Filter Extensions Apply Order and Page Before the Select Projection

All Filter extensions — both typed (Filter<T>, ToList<T>(Filter), ToListAsync<T>(Filter), and ToListAsync<T>(Segment) since 3.1.0) and dynamic (FilterDynamic<T>, ToListDynamic<T>, ToListAsyncDynamic<T>) — apply ordering and pagination on the typed IQueryable<T> before the select projection. This ensures that field names referenced in orders always resolve against the original entity type T, regardless of which fields are projected.

12. Condition Values Become Escaped Literals, Not Query Parameters

A condition's Values are written into the generated dynamic LINQ expression as string literals. Since 2.1.4 they are escaped first — a backslash is doubled and a double quote is backslash‑escaped — so any value matches literally, \ and " included, and a value can no longer break out of its literal to alter the predicate.

The literal then reaches the provider as a constant, so EF Core inlines it into the SQL rather than binding a parameter — a Contains on "الثانية\" renders as instr(lower("p"."Name"), 'الثانية\') > 0. EF Core escapes that literal for SQL itself, so this is not a SQL injection path.

13. AggregateBy.Alias Must Be a Plain Identifier

The alias is emitted verbatim into the generated Select projection, so since 2.1.4 it must be a leading letter or underscore followed by letters, digits, or underscores. Letters are matched by Unicode category, so a non‑Latin alias such as "المجموع" stays valid.

14. Date Comparisons Resolve the Member's Type

Before 3.1.0 every DataType.Date and DataType.DateTime condition produced the same string per operator, whatever the member actually was — for GreaterThanOrEqual, {field} != null && {field} >= DateTime.Parse("…"). The builder now reads the member's CLR type first and emits the null guard, the literal, and the .Date access that type can actually take.

• The null guard is emitted only for a member that can be null. A non-nullable member reached through a navigation — Approval.ApprovedAt — guards each navigation instead: Approval != null && ….
• A DateTimeOffset member is compared against a DateTimeOffset literal; a DateTime member against a DateTime literal; a DateOnly member against a DateOnly, as a day under both data types.
• A nullable member is unwrapped with .Value under its guard, so DataType.Date emits {field}.Value.Date — or {field}.Value on a DateOnly?, which is already a day.
• A Having condition names an aggregate alias rather than a member, so the type comes from what the alias stands for: a Minimum, Maximum, FirstOrDefault or LastOrDefault returns one of the values it read, so it has that member's type — nullable if the member is. On PostgreSQL a Having on Maximum of a timestamptz column becomes HAVING max(col) > TIMESTAMPTZ '…'.

15. Date Values Are ISO 8601, Year-First, or a Declared Format

Condition values for the two date types are now read against an explicit list of formats, never the lenient .NET parser, and re-emitted in round-trip form — at validation and in the builder alike, as the member's own date type. Every deployment accepts ISO 8601 extended calendar dates (2026-09-01, optionally with a time after a T or a space, a fraction, and Z or an offset) and year-first dates with / or . (2026/09/01, 2026.09.01), plus any format the deployment declares. The other ISO 8601 forms are InvalidFormat: basic (20260901), week (2026-W36-2), ordinal (2026-244) and reduced precision (2026-09, 2026-09-01T12). The shipped predicate used to carry your raw text into a DateTime.Parse that the runtime evaluated in the host's culture, so the same filter meant different days on two servers; the host's culture and calendar now play no part.

16. PageCount on an Unpaged Result Is 1

When a Filter or Summary carries no Page, PageCount is now 1 — the one page the whole result occupies — and 0 when nothing matched. It used to equal TotalCount: the calculation divided by a page size of 1 whenever none was sent, so a 5,000-row result reported 5,000 pages of one row each.

17. Select's Constructor Refusal Is Now a Stable Code

The refusal in point 1 used to arrive as an English sentence — Select projection requires a parameterless constructor on type '{T}'. — which a caller could not match on, because the type name was interpolated into it. The Message is now the fixed code SelectTypeMustHaveParameterlessConstructor, and the type's name rides on a new property, LogicException.Subject (string?). LogicException gained a second constructor for it, LogicException(string message, string? subject).

18. A Guarded Query Requires a Prepared Context

A query guarded through ApplyPolicy whose DwPolicyContext never went through DwPolicy.PrepareAsync is refused with a PolicyException carrying PolicyContextNotPrepared — whether or not a policy store is configured, and at the ApplyPolicy call itself, before any terminal runs. A store provider already refused one, because it had no pinned snapshot to answer from; with attributes alone nothing refused it, so the same missing call was a failure in one deployment and silence in another. DwPolicyContext.IsPrepared is public, so you can assert it yourself.

19. A Segment's Sets Are Combined in the Database

ToListAsync(Segment) turns its condition sets into one query. Union and Intersect join the sets' conditions with OR and AND; Except removes its set's rows with NOT EXISTS on the primary key; and a type with no primary key uses SQL UNION / INTERSECT / EXCEPT. The combined query is then ordered, paged, projected and counted exactly like a Filter.

Until 3.1.0 each set was loaded into a list, and the lists were combined in memory by object reference. That was right only for a tracking query with no Selects. With AsNoTracking(), with Selects, and under ApplyPolicy, which always runs untracked, Intersect returned nothing, Except removed nothing and Union counted a row once for every set that matched it. Every row of every set was read before the page was cut.

• Results. Untracked, projected and guarded segments return the rows their sets describe. A tracking query without Selects returns the same rows it did.
• Ordering. Sorting runs in the database, so text follows its collation rather than .NET's string comparison, and NULLs fall where the provider puts them. Orders apply before Selects, so an order field no longer has to be selected. A segment with no Orders comes back in whatever order the database chooses, as a filter does.
• Reads. Only the requested page is read, plus one COUNT for TotalCount.
• Providers. On a type with a primary key, only Except needs the provider to translate a correlated EXISTS. A type with no primary key needs every column to be comparable — not PostgreSQL json or SQL Server xml — and support for the SQL set operators its sets use.

20. Members Named Root, It or Parent Are Read as Members

System.Linq.Dynamic.Core reads it, root and parent as keywords, in any letter case, wherever an identifier can stand, and the library writes member paths into its expressions as they are named. Before 3.1.0 it parsed with those keywords on:

• A navigation named Root or It was read as the row itself. Root.Name filtered, sorted, grouped and aggregated — and through SelectDynamic projected — the row's own Name.
• A navigation named Parent threw ParseException.
• An AggregateBy.Alias named root, it or parent failed in Having and in Summary.Orders.

Every expression is now parsed with a ParsingConfig the library owns: the parser's defaults with AreContextKeywordsEnabled = false, so it, root and parent name members like any other identifier. No setting restores the keyword reading.

21. MaxConditionDepth and MaxConditionSets Refuse Guarded Requests 3.0 Ran

Two caps are new in 3.1.0. Only a query guarded through ApplyPolicy enforces them; an unguarded call is not affected. Both default to 10, refuse a value below 1, freeze with the rest of the posture, and bind from configuration as Caps:MaxConditionDepth and Caps:MaxConditionSets.

Nothing bounded either shape before. MaxConditions counts conditions and says nothing about how deeply their groups nest, and a set with no conditions passes every other cap while still adding to the one statement a segment becomes.

DwPolicy.Configure(new DwPolicyOptions
{
    Caps = { MaxConditionDepth = 20, MaxConditionSets = 25 },
}, providers);

{
  "DynamicWhere": {
    "Policies": {
      "Caps": { "MaxConditionDepth": 20, "MaxConditionSets": 25 }
    }
  }
}

22. The Strict Tier Keeps the Policy Trace Off the Result

On 3.0.0 every guarded terminal put its PolicyTrace on the result, in both tiers: FilterResult<T>.Policy from ToList, ToListAsync, ToListDynamic and ToListAsyncDynamic with a Filter, SummaryResult.Policy from ToList and ToListAsync with a Summary, and SegmentResult<T>.Policy from ToListAsync with a Segment. The trace names every field a policy dropped, the attribute or rule that sealed each one, and every predicate injected on the caller's behalf — the detail the strict tier already refuses to hand over through getQueryString — and an API that serializes a result sends it to the caller.

DwPolicyOptions.IncludeTraceInResult (bool?, default null) now decides. null follows the tier: off under DwTier.Strict, on under DwTier.Convenience. true or false overrides the tier in either one. It freezes with the posture and binds from the configuration key IncludeTraceInResult.

var guarded = db.Employees.ApplyPolicy(caller);
var result  = await guarded.ToListAsync(filter);

PolicyTrace? sent     = result.Policy;      // null under DwTier.Strict, unless IncludeTraceInResult = true
PolicyTrace? recorded = guarded.LastTrace;  // recorded whatever the setting says

23. The Strict Tier Answers an Unknown Field and a Denied Field Alike

On 3.0.0 a guarded query told a field that does not exist from one the caller may not use. A name that matched nothing on T failed validation with LogicException ConditionMustHasValidFieldName before any policy decision was made, and a denied field was refused with a PolicyException naming the field — and, where one source decided, that rule or attribute on RuleId and SourceOrigin. A caller probing the strict tier learned which columns exist, including the ones they may never read, one guess at a time, and each refusal confirmed the guess.

Under DwTier.Strict, outside a dry run, the two now answer alike:

• A name that matches nothing is gated as a field denied for every feature, at the step where a denial is raised — after the caps — so it gets the code a [DwDenied] field gets in that clause: FieldDeniedForWhere, FieldDeniedForSelect, FieldDeniedForOrder, FieldDeniedForGroup or FieldDeniedForAggregate. A name padded with dots or blank segments — NoSuchColumn...., . . . . X — is normalized the way a real path is, so it gets the refusal a padded real field gets rather than failing MaxNavigationDepth.
• Inside a segment every field refusal is FieldDeniedForSegment, with Feature Segment, whichever clause refused it: a condition in any set, an order, a select, or the field taking part at all. Answered by clause, a field denied for every clause but not for segments would say FieldDeniedForOrder where a name that matches nothing says FieldDeniedForSegment. Filters and summaries keep their per-clause codes.
• Every refusal with one of those six codes carries FieldPath = "*", RuleId = null and SourceOrigin = null, whatever the field — a real denied field and an alias included — so the message is the same too: FieldDeniedForWhere: field '*', feature 'Where', tier 'Strict'.
• A CapExceeded refusal names no path either. MaxNavigationDepth and MaxAuditEvents, the two caps that named a field, used to report its canonical path, which confirmed that the path exists. They report "*", and SourceOrigin still names the cap.
• MaxQueryCost is checked after every field has passed its gate, not before. A field weighted by [DwCost] that the caller may not use is refused as denied before its weight can count, exactly as a name that does not exist is, so the budget cannot tell the two apart. An allowed weighted field is still refused with QueryCostExceeded.
• MissingContextValue has FieldPath "*" and a null SourceOrigin, so it names neither the scope's column nor the context key it reads — together they describe how rows are partitioned.
• The trace keeps the real path and reason: an unknown name is recorded as Denied, with the reason names nothing on followed by the type's name. With AuditRefusals on, the audit event names the field, the scoped field of a MissingContextValue, or the unknown name the caller sent.

24. MaxConditionValues and MaxAggregates Refuse Guarded Requests 3.0 Ran

Two more caps are new in 3.1.0. As with point 21, only a query guarded through ApplyPolicy enforces them; an unguarded call is not affected. MaxConditionValues defaults to 1000 and MaxAggregates to 50. Both refuse a value below 1, freeze with the rest of the posture, and bind from configuration as Caps:MaxConditionValues and Caps:MaxAggregates.

Nothing bounded either shape before. An In or a NotIn is one comparison per value, so a single condition could hand the database a predicate of any size while spending one condition from MaxConditions and one field from the cost budget. Every aggregate is a column of every group, and one with no field — a Count — named nothing a [DwCost] weight could be set on, so any number of them cost nothing.

That Count is now charged as well: an aggregate with no Field costs DwCaps.DefaultFieldCost toward MaxQueryCost, where it used to cost nothing. A guarded summary that sat just under its budget can now go over it and be refused with QueryCostExceeded.

Every count cap — MaxConditions, MaxConditionDepth, MaxConditionSets, MaxConditionValues, MaxAggregates, MaxOrderFields and MaxPageSize — is now checked before any field name is resolved, because resolving every name of an oversized request is the work the caps exist to refuse; MaxNavigationDepth still runs once names are resolved. A request that is too large and names a field that does not exist is refused with CapExceeded in both tiers, where 3.0.0 resolved names first and answered ConditionMustHasValidFieldName.

DwPolicy.Configure(new DwPolicyOptions
{
    Caps = { MaxConditionValues = 5000, MaxAggregates = 100, MaxQueryCost = 2000 },
}, providers);

{
  "DynamicWhere": {
    "Policies": {
      "Caps": { "MaxConditionValues": 5000, "MaxAggregates": 100, "MaxQueryCost": 2000 }
    }
  }
}

25. A Guarded Query That Sends No Selects Keeps What the Source Carries

A request with no Selects returns whole rows, denied fields included, so a guarded query synthesizes a projection when a denied field could reach the result. 3.2.0 changed when it does so and what the projection keeps. The rules are on Policy configuration.

• When. A field denied at the top of T asks for it whatever the field holds. A field denied beneath a member asks for it when its value can reach the result: on an entity, beneath a column, an owned or complex member, or a navigation the query loads through an Include, an automatic include or a lazy loader; on a projected row, beneath a member the initializer assigns; in memory, beneath any member. A chain that reaches its rows through a navigation, a SelectMany, a Join or a GroupBy counts every navigation as loaded when it also has an include, or a lambda that builds an object, gets one from an application's method, or captures a query with its own include or projection. A field a subtype of T declares, one a subtype of a member's type declares, and one beneath a member EF Core does not map, count too. A member that can hold an object of any type asks for nothing on its own. It does so in both tiers, typed and dynamic, for a Filter and a Segment. Until 3.2.0 only a simple field denied at the top of T asked for one. A denial beneath a navigation nothing loads never leaves the database, so an entity whose only denials sit there is read exactly as in 3.1.0.
• What. The allowed members, which replace the allowed scalars. A row a projection builds keeps the members its initializer assigns. An entity keeps its mapped columns, converted and JSON ones included except a converted one that can hold an object of any type, its owned and complex members, and every collection of simple values such as byte[] or List<string>. Rows in memory keep their values. A member holding an object is kept whole when nothing it can hold is denied, narrowed to the allowed fields where the core's narrowing translates, and otherwise left out whole.

26. Selects Naming a Member Is Gated Against Every Denial Beneath It

When Selects names a navigation with a denied field beneath it, the Convenience tier replaces the entry with the allowed fields beneath it, and the Strict tier refuses it. Since 3.2.0 the gate finds every denial beneath the member, and refuses, with FieldDeniedForSelect, a narrowing it cannot build as gated. See A navigation named in Selects.

A member that cannot be narrowed at all — a column, a complex property or a member stored as JSON, a member of a row in memory, or one a projection builds some way the core cannot narrow — is refused in both tiers when something beneath it is denied.

27. DefaultOrder Reaches a Projection That Builds T

In 3.1.0 a Select anywhere in the chain kept a guarded query in its own order, because a default applied after a projection could name a field the projection left out, which EF Core cannot translate. Since 3.2.0 only the outermost Select counts, because it makes the rows the default orders. When it builds T in an object initializer and assigns every field the [DwEntity(DefaultOrder)] names a column, at every level of a nested path, the default applies. A column is a member the EF Core model maps on the entity the Select reads, read directly, through reference navigations or through EF.Property; in memory any assigned field is one. A value the projection computes, by any method or operator, even one EF Core could translate, a member the model does not map, a constructor with arguments, a default field the initializer does not assign, or a nested path through anything but an initializer still leaves the query in its own order: ordering by it could fail where the unguarded query ran.

[DwEntity(DefaultOrder = "CreatedAt desc, Id")]
public class TicketRow
{
    public int Id { get; set; }
    public DateTime CreatedAt { get; set; }
    public string Title { get; set; } = string.Empty;
}

// 3.1.0: unordered. 3.2.0: ordered by CreatedAt desc, Id.
var rows = db.Tickets
    .Select(t => new TicketRow { Id = t.Id, CreatedAt = t.CreatedAt, Title = t.Title })
    .ApplyPolicy(caller)
    .ToList(new Filter());

• A projection composed on the guarded handle — the guarded Select, or a guarded Filter whose Selects is set — keeps the rest of the chain unordered, even when it keeps every default field. So guarded.Select(["Id", "Title"]).Page(page) pages as it did in 3.0.0, unordered.
• A Filter composed on the handle that sent orders gets no default later in the chain, even when the policy dropped every one of them, as a composed Order already did not.

28. Every Async Terminal Takes a CancellationToken

Since 3.2.0 every asynchronous terminal, guarded and unguarded, has overloads that take a CancellationToken: ToListAsync and ToListAsyncDynamic with a Filter, ToListAsync with a Summary, and ToListAsync with a Segment. The token reaches the count and the read. The overloads sit beside the 3.1 signatures, which are unchanged, so code compiled against 3.1 still binds. That brings the extension methods to 28. A reflection lookup by name alone finds more overloads than it did, and where it found one — ToListAsyncDynamic, on the extension class and on the guarded handle — it now finds several, so Type.GetMethod given only the name throws AmbiguousMatchException; pass the parameter types.

await query.ToListAsync(filter, default);              // CS0121 since 3.2.0
await query.ToListAsync(filter, false);                // as 3.1 read it
await query.ToListAsync(filter, cancellationToken);    // the new overload

29. A Type in a Namespace That Starts with System Is Policed

The attribute walker does not descend into the framework's own types, which carry no policy attributes. Until 3.2.0 it took any namespace whose name started with System for the framework's, so an application namespace such as SystemsCorp.Payroll or SystemX.Domain got no policy beneath its types. A [DwDenied] field on such a type, reached through a member, was returned, filterable and sortable. Only System and the namespaces beneath it are the framework's now.

See also

• Error Codes Reference → the 30 stable validation messages.
• DataType → context for points 14 and 15, and how a deployment declares its date formats.
• FilterResult<T> → context for point 16.
• Cache configuration → context for point 8.
• SelectDynamic → context for points 1 and 10.
• AggregateBy → context for point 13.
• Operator → context for the long-list fix in point 12.
• Policy configuration → context for points 21 to 26: the caps, the trace on a result, what a strict refusal carries, and what a denied field does to a projection.
• Security & k-anonymity → why the strict tier hides which fields exist (point 23), and the denials the gate could not see (points 25, 26 and 29).
• Default order → context for point 27.
• Materialization → context for point 28: every async terminal and its overloads.