See Milestones for release notes.

Detects overly complex Entity Framework Core queries and either logs them or throws. Each check has two levels: the level a query is logged at, which has defaults, and the level a query throws at, which is opt in.

Entity Framework has no limits of its own on the size or shape of a query, and the team closed the request for unbounded result set warnings as not planned. Limits like these usually sit in front of Entity Framework, in an OData or GraphQL layer, and so only cover queries that arrive that way.

An API that lets the client shape the query, such as GraphQL or OData, hands part of the query to whoever sends the request. One small request can ask for every row of a table, nest navigations many levels deep, or send a Contains list with thousands of values. Each costs the database and the server far more than it costs the client to send, so a handful of them, repeated, is enough to make the API slow or unavailable. This is a denial of service by resource exhaustion, and it needs no bug in the API to work, only a query the API did not expect.

The checks bound what one query can ask for, whichever layer built it:

Only throw levels stop a query. Log levels report it and let it run. A practical rollout is to log first, see which levels real clients reach, then set throw levels above that.

These checks limit the cost of each query. They do not replace limits on how often a client can send one, so still use authentication, rate limiting, and request and command timeouts.

Background:

• OWASP API Security Top 10: API4:2023 Unrestricted Resource Consumption
• OWASP GraphQL Cheat Sheet: DoS Prevention, which covers query depth, amount and cost limits
• CWE-770: Allocation of Resources Without Limits or Throttling

https://nuget.org/packages/EfQueryComplexity/

• Two levels per check: a query is logged at one level and throws at another
• Measured once: shape is measured while a query is compiled, so each distinct query costs it once
• Values checked every execution: Take counts and the lists a query sends only exist while it runs
• Per query overrides: raise a level for one query, or skip every check for it
• Standard logging: warnings go through the Entity Framework pipeline, so LogTo, ILoggerFactory and ConfigureWarnings all work
• SQL Server cost limit: hand the decision to SQL Server's own query governor

protected override void OnConfiguring(DbContextOptionsBuilder builder) =>
    builder.UseQueryComplexity();

snippet source | anchor

With no levels passed, a query is logged when it exceeds QueryComplexityLimits.LogDefaults, and no query throws.

protected override void OnConfiguring(DbContextOptionsBuilder builder) =>
    builder.UseQueryComplexity(
        logAt: QueryComplexityLimits.LogDefaults with
        {
            MaxTake = 500,
            RejectUnbounded = false
        });

snippet source | anchor

Throwing is opt in, and every level has to be given, so nothing is enforced by accident:

protected override void OnConfiguring(DbContextOptionsBuilder builder) =>
    builder.UseQueryComplexity(
        throwAt: new(
            MaxNodes: 4096,
            MaxDepth: 64,
            MaxOperators: 64,
            MaxNavigationDepth: 4,
            MaxIncludes: 16,
            MaxIncludeDepth: 4,
            MaxTake: 1000,
            MaxInValues: 1000,
            RejectUnbounded: true));

snippet source | anchor

A query that exceeds a throw level throws QueryComplexityException, which carries every level it exceeded in Violations.

A query is checked against the throw levels before the log levels, so a throw level below its log level would leave that log level unreachable. That is rejected as the context is constructed, rather than quietly logging nothing. Passing the same levels for both is allowed, and is how to say "only throw".

A check fires when the measured value is greater than the level. A level of null turns that check off.

A single SQL query joins every collection it loads, so each multiplies the rows returned for the others. Loading 10 departments with 50 employees and 20 projects each returns 10,000 rows for 710 entities. This is a cartesian explosion.

MaxSingleQueryCollections counts:

• Collection navigations in Include and ThenInclude, including string paths. A collection restated to ThenInclude something below it counts once.
• Collections a projection returns, for example Employees = _.Employees.ToList(), including collections nested in them.

It does not count:

• Reference navigations.
• A collection only read by an aggregate, like _.Employees.Count() or _.Employees.Any(), which is a subquery rather than a join.
• Any collection in a split query, from AsSplitQuery() or UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery), since each collection is then loaded by its own query. AsSingleQuery() overrides the default.
• An Include that Entity Framework ignores, because the query returns no entity for it to load into. A Select returning no entity, like Select(_ => _.Name) or Select(_ => new { _.Name }), or an aggregate like Count(), makes Entity Framework ignore the Includes before it. A projection that could return an entity keeps them counted, including one that passes the entity to a method.

The log default of 1 matches the point where Entity Framework logs MultipleCollectionIncludeWarning. That warning only covers Include, and only when no splitting behavior is configured.

A query is bounded when it cannot return more rows than a Take, or a lookup by key, allows:

• A query that returns one row, an aggregate or a count is bounded, so First, Single, Count, Any, Sum and friends never fire.
• Take bounds everything below it, and so does a lookup by key.
• SelectMany, Join, GroupJoin, LeftJoin, RightJoin and Zip return more rows than their source, so a Take or a lookup below one of them bounds the source rather than the query.
• Concat and Union are bounded only when both sides are.
• Every other operator returns no more rows than its source.

The message names the types of the rows returned without a Take, and so does QueryComplexityViolation.RowTypes. A row type is the entity a query reads, not what it projects to, so Employees.Select(_ => _.Name) returns Employee rows. A query that joins in another sequence returns rows of both types: Departments.SelectMany(_ => _.Employees) returns Department and Employee rows.

A Where that compares the key of its rows with a value, like Employees.Where(_ => _.Id == id), returns at most one row, so it needs no Take:

• Other conditions can be added with &&. With ||, each side has to be a lookup.
• A composite key needs every part compared.
• The key is the primary key or an alternate key. A unique index does not count: a filter can make it unique among only some of the rows, and a column that allows null can hold null in many rows.
• ids.Contains(_.Id) returns a row for each value in ids, so it is only bounded when MaxInValues is set, which limits that list. The log and throw levels each decide this with their own MaxInValues. For a composite key, one part can be looked up in a list and the rest compared.
• Only the rows of a DbSet can be looked up by their key. Between the DbSet and the Where there can be filters, ordering, Skip, Take, Distinct, OfType, and options such as Include and AsNoTracking. After a Select, a SelectMany, a Join or a Concat, the same key can be in many rows, as it can in the rows FromSql returns.

Some apps have no large table at all. An admin or workflow app where every table holds hundreds or thousands of rows can return all of them, and this check only reports queries that are fine. Turn it off, and keep the rest:

protected override void OnConfiguring(DbContextOptionsBuilder builder) =>
    builder.UseQueryComplexity(
        logAt: QueryComplexityLimits.LogDefaults with
        {
            // Every table is small, so a query with no Take is fine
            RejectUnbounded = false
        });

snippet source | anchor

The other checks are unaffected, so query size, depth, operators, navigations, includes, Take counts and IN list sizes are still reported. Turn it on again if a table starts growing, and use Only to name that table.

Most apps know which tables stay small and which grow. RejectUnbounded takes an UnboundedEntities, so the check can cover only the types where returning every row is a problem. true converts to UnboundedEntities.All and false to UnboundedEntities.None.

Check every type except the ones known to have few rows:

protected override void OnConfiguring(DbContextOptionsBuilder builder) =>
    builder.UseQueryComplexity(
        logAt: QueryComplexityLimits.LogDefaults with
        {
            // Few rows, so returning all of them is fine
            RejectUnbounded = UnboundedEntities.AllExcept(
                typeof(User),
                typeof(AccessGroup))
        });

snippet source | anchor

Or check only the types known to have many rows:

protected override void OnConfiguring(DbContextOptionsBuilder builder) =>
    builder.UseQueryComplexity(
        logAt: QueryComplexityLimits.LogDefaults with
        {
            // Many rows, so every query for them needs a Take
            RejectUnbounded = UnboundedEntities.Only(
                typeof(Commitment))
        });

snippet source | anchor

• A query fires when it returns rows of any checked type. A query that joins in a type that is not listed still fires for that type, so both types of a SelectMany have to be skipped for it to pass.
• Naming a type also names the types derived from it, and naming an interface names the types that implement it, so a marker interface can list many types at once.
• A query for a base class returns rows of its derived types too. It is checked by Only when a derived type is named, and only skipped by AllExcept when the base class is.
• Rows that are not entities, such as SqlQuery<int> or a list of values, are checked by All and AllExcept, and not by Only.
• Only the rows of the query itself count. A collection loaded by Include, or by a projection, is not checked, so with AllExcept(typeof(User)), Users.Include(_ => _.Commitments) does not fire.

These values only exist while a query runs, so they are checked for every execution rather than once per query. That check needs Entity Framework's internal query compiler, which is registered when MaxTake or MaxInValues is set at either level. It is also registered whenever throwAt is passed, since it caches a query that throws, so the query is not measured again for every execution. Consequences:

• The package uses an internal API (EF1001), so it is tied to the Entity Framework major version it was built for.
• It conflicts with any other library that replaces IQueryCompiler, since the last one registered wins.
• A per query override cannot turn these checks on, since whether to check values is decided before any query exists. WithQueryComplexity that sets MaxTake or MaxInValues, for a context where neither is set, throws rather than leaving the query unchecked.

A value that is over a log level is logged the first time a compiled query exceeds it, rather than on every execution. A value over a throw level throws every time.

Skip every check for one query:

// Skips every check for this query
var employees = await context.Employees
    .IgnoreQueryComplexity()
    .ToListAsync();

snippet source | anchor

Or replace levels for one query:

// Replaces levels for this query only
var employees = await context.Employees
    .WithQueryComplexity(
        new()
        {
            MaxTake = 5000
        })
    .Take(5000)
    .ToListAsync();

snippet source | anchor

A marker is read from the query being executed, not from a subquery inside it. The levels are for the whole query, so a marker on a queryable that is later used inside another query would change the levels of that whole query, and every query composed over it would skip checks it never asked to skip. One there throws rather than being honored or quietly dropped.

Every level left null keeps the configured value, and a level that is set replaces both the log and the throw level for that check. An override never starts throwing for a context that was not given throw levels. To turn one check off for a query use int.MaxValue. RejectUnbounded is a bool for a query: true checks every type and false none, whichever types were configured.

MaxTake and MaxInValues can only be changed for a query when the configured levels set one of them, since the value checks are otherwise not set up at all. An override that sets one anyway throws.

Each distinct set of levels is a constant in the query, so a query using them is compiled and checked separately.

Warnings are logged as QueryComplexityEventId.LimitExceeded through the Entity Framework pipeline, so they reach LogTo, an ILoggerFactory, and a DiagnosticSource. That also means the usual configuration applies, including turning the warning into an error:

protected override void OnConfiguring(DbContextOptionsBuilder builder) =>
    builder
        .UseQueryComplexity()
        .ConfigureWarnings(
            _ => _.Throw(QueryComplexityEventId.LimitExceeded));

snippet source | anchor

Use Ignore instead of Throw to silence it.

The same configuration can turn the warning into an error without mentioning it. A context whose warnings all throw, such as one built by EfLocalDb, which uses Default(WarningBehavior.Throw), throws InvalidOperationException for any query over a log level, and the message starts with "An error was generated for warning 'EfQueryComplexity.LimitExceeded'". A behavior set for one event takes precedence over the default, so to keep only logging:

protected override void OnConfiguring(DbContextOptionsBuilder builder) =>
    builder
        .UseQueryComplexity()
        .ConfigureWarnings(
            _ => _
                .Default(WarningBehavior.Throw)
                .Log(QueryComplexityEventId.LimitExceeded));

snippet source | anchor

The message names every level that was exceeded and then prints the query, bounded to 1000 characters. The query that broke a level is the one that prints long, and without a bound every log line reporting it would carry the whole expression tree.

The levels above bound the shape of a query, not what it costs to run. An allowed query over a large unindexed table is still expensive. SQL Server can make that call itself:

protected override void OnConfiguring(DbContextOptionsBuilder builder) =>
    builder
        .UseSqlServer("connection-string")
        .UseQueryComplexity(sqlServerCostLimit: 300);

snippet source | anchor

SET QUERY_GOVERNOR_COST_LIMIT is applied to every connection as it opens, and SQL Server then refuses any statement whose estimated plan cost is greater than the limit, with error 8649.

• The cost is the optimizer's estimate in its own units, not a time, so treat it as relative. It is an estimate, so stale statistics can still let a slow query through.
• It has to be greater than zero. SQL Server reads a cost limit of zero as the query governor being off, so passing zero throws rather than silently allowing everything.
• It is applied on every open, because reusing a pooled connection resets session state.
• Entity Framework has to be the one opening the connection, since that is what the limit is applied by. A connection that was already open when Entity Framework was handed it never gets one, which covers a connection passed to UseSqlServer open, and one opened with context.Database.GetDbConnection().Open(). Use context.Database.OpenConnection(), which Entity Framework performs and so applies the limit to.
• It is a property of the connection, so IgnoreQueryComplexity() does not lift it for one query.
• SQL Server only, including Azure SQL. Other providers throw.

Shape is measured only when a query is compiled, which happens once for each distinct query. After that, each execution pays only for the value checks: reading the Take count, and counting each list the query sends, such as a Contains list.

Two benchmarks in src/Benchmarks run a query that is already compiled, with a Take and a 100 value Contains list, creating a new context for each execution, as each request does. Every configuration other than the baseline calls UseQueryComplexity:

• Shape checks only: the log defaults with MaxTake and MaxInValues off, so nothing is checked on each execution.
• Log defaults: UseQueryComplexity(), so the Take count and the Contains list are checked on each execution.
• Log and throw at the defaults: UseQueryComplexity(LogDefaults, LogDefaults).

DatabaseExecutionBenchmarks executes it against LocalDB, so these are the numbers for a whole request, including the round trip and materializing the rows:

Each configuration ran in three processes, and against LocalDB the time varied between them by up to 22 μs, more than the checks cost. That is also why shape checks only measures faster than the baseline. So ExecutionOverheadBenchmarks measures the cost without a database. It calls ToQueryString(), which runs the same cached query and value checks without connecting. It does different work from an execution, so only what each configuration adds is shown, compared with the baseline:

Without a database the processes varied by about 2.5 μs, and every configuration is within 1.5 μs of the baseline, so the checks add no time that can be measured, against a request of about 1.1 ms. The memory comes with creating each context, most of it what Entity Framework allocates for any options extension and interceptor. The value checks allocate nothing on each execution, and add 8 bytes to shape checks only. Memory is the lowest of the three processes: BenchmarkDotNet counts allocations on every thread, and some processes allocated up to about 290 bytes more, including with UseQueryComplexity not called. Measured on an AMD Ryzen 9 5900X, .NET 10, BenchmarkDotNet 0.15.8.

Compiling a query that has not been seen before costs one extra pass over its expression tree, and that happens once per distinct query.

• Shape is measured by an IQueryExpressionInterceptor, which runs only when a query shape is compiled. Each distinct query is measured once, and logged once. A query that throws does so every time it is used, but the failure is cached in place of the compiled query, so it is not measured again.
• Values are checked by a wrapper around the delegate Entity Framework caches for a query, so every execution is checked, including executions of compiled queries.
• Levels are part of the key for Entity Framework's internal service provider, and for its model, so contexts with different levels never share a compiled query. The service provider alone is not enough: Entity Framework keys a compiled query on the model it was compiled for, and caches both the models and the compiled queries in an IMemoryCache that UseMemoryCache can hand to more than one provider. Use a few fixed configurations rather than varying levels per request, or Entity Framework's ManyServiceProvidersCreatedWarning fires.

• Raw SQL is not analysed. FromSql, ExecuteSql and SqlQuery pass through, and only LINQ composed on top of them is measured.
• UseQueryComplexity replaces IModelCacheKeyFactory, so it cannot be used by an application that replaces that itself, for example to give each tenant its own model. It throws rather than quietly dropping either replacement.
• A context configured with UseModel, such as with a compiled model, is given that one model whatever its levels. Regular queries are still kept apart by the internal service provider, but a query compiled by EF.CompileQuery is held against the model rather than in that cache, so one shared between contexts configured with different levels is checked against the levels of whichever context compiled it. Give each set of levels its own compiled query.
• Navigation depth is measured per member access chain, not across separate lambdas.
• Using IgnoreQueryComplexity() or WithQueryComplexity() without calling UseQueryComplexity() gives Entity Framework's "could not be translated" error, since nothing removes the marker.

Pattern from The Noun Project