In EF Core 10, what does EF.CompileAsyncQuery save on each call, and when is a compiled query worth adding to a hot search path?
answer
- EF already caches by tree shape
- the cache lookup still runs
- a static readonly delegate
- IAsyncEnumerable<T> or Task<T>
- EF.Constant inside throws since 9
basics
~20 sEF.CompileAsyncQuery compiles a LINQ query once into a reusable delegate, skipping the expression-tree comparison against EF Core's internal query cache on every call. It pays off only for hot, fixed-shape queries after bigger costs are gone.
solid answer
~40 sEF Core already caches each translated query by the shape of its expression tree, so a repeated query is not translated again. Each execution still builds the tree, extracts parameter values and compares the tree with cached entries. `EF.CompileAsyncQuery` does that work once and returns a thread-safe delegate, held in a `static readonly` field and invoked with any instance of that context type; a sequence query returns `IAsyncEnumerable<T>`, a single-result query `Task<T>`. The documented gain is modest, roughly a hundred microseconds and a few kilobytes per call, so it fits a hot search endpoint after projection, indexing and tracking are fixed. The shape is frozen: parameters must be simple scalars, conditional filters and tags cannot vary, and since EF Core 9 `EF.Constant` or `EF.Parameter` inside a compiled query throws.
code
csharp · 17 linespublic static class ProductQueries
{
public static readonly Func<GearContext, string, int, IAsyncEnumerable<ProductCard>> ByCategory =
EF.CompileAsyncQuery((GearContext db, string category, int take) =>
db.Products
.Where(p => p.Category == category && p.IsActive)
.OrderBy(p => p.PriceCents)
.Select(p => new ProductCard(p.Id, p.Name, p.Brand.Name, p.PriceCents, p.StockCount > 0))
.Take(take));
}
// in the endpoint, with the request's own context
var cards = new List<ProductCard>();
await foreach (var card in ProductQueries.ByCategory(db, "tents", 40))
{
cards.Add(card);
}go deeper
Recall that EF Core caches translated queries by shape and that EF.CompileAsyncQuery returns a reusable delegate for a fixed query.
Explain which per-call steps a compiled query skips, the delegate types it returns, and why the delegate can be static and shared.
Show when the saving matters: measure first, use the cache hit and miss metrics, and fix shape-changing queries before compiling hot ones.
Judge whether compiled queries are worth their rigidity across a codebase, against projection, pooling and caching that save far more per request.
## The cache EF Core already has When EF Core receives a LINQ query it must **compile** it: walk the expression tree, translate it into SQL and build the code that turns rows into objects. That is expensive, so EF keeps the result in its internal `IMemoryCache`, keyed by the **shape** of the tree. Two calls that differ only in parameter values, such as a captured `category` variable, reuse the same entry. Each compiled query occupies a cache size of 10 in a cache whose `SizeLimit` is 10240, and the metrics `microsoft.entityframeworkcore.compiled_query_cache_hits` and `microsoft.entityframeworkcore.compiled_query_cache_misses` show how well it works. Even on a cache hit, every execution still pays for: - building a new expression tree for the call; - extracting parameter values from the closures it captures; - comparing that tree recursively with cached keys to find the entry. ## What EF.CompileAsyncQuery does `EF.CompileAsyncQuery` takes the query as a lambda over the context and scalar parameters, compiles it once, and returns a **delegate** that runs it without the cache lookup. The delegate's type follows the lambda's body: | Lambda body | Delegate returned | |---|---| | an `IQueryable<T>` | `Func<TContext, TParam1, ..., IAsyncEnumerable<T>>` | | a single result, such as `FirstOrDefault(...)` | `Func<TContext, TParam1, ..., Task<T>>` | | a single result with a `CancellationToken` parameter | `Func<TContext, TParam1, CancellationToken, Task<T>>` | `EF.CompileQuery` is the synchronous twin, returning `IEnumerable<T>` or `T`. The delegate is **thread-safe**: store it once in a `static readonly` field and call it with whichever context instance the current request owns. ## How much it saves The EF Core documentation's benchmark of a one-row query measured about 564 microseconds with a compiled query against about 672 without, and 9 KB against 13 KB allocated. The saving is per call and fixed, while network and database time usually dominate. A compiled query is worth adding when: 1. the query is **hot**, such as a search or autocomplete endpoint called many times a second; 2. the query is **complex**, because the bigger the expression tree, the more the skipped comparison costs; 3. the bigger costs are already gone: projection instead of full entities, indexes, no tracking and context pooling. ## What a compiled query cannot do - Run against more than one model: all contexts calling it must share the same model. - Take complex parameter expressions: use simple scalar parameters, not member accesses on objects. - Change shape per call: a conditional `Where` or a user-chosen sort needs separate compiled queries or the normal path. - Take a `TagWith` tag as a parameter: tags are literals in the SQL. - Contain `EF.Constant` or `EF.Parameter`: since **EF Core 9** these throw `InvalidCastException` inside compiled queries. ## Compiled queries are not precompiled queries `dotnet ef dbcontext optimize --precompile-queries` generates C# interceptors with the SQL baked in at build or publish time, aimed at NativeAOT and marked experimental. `EF.CompileAsyncQuery` still compiles at runtime, once per process. ## Measuring before and after A compiled query is a micro-optimization, so prove it the same way: 1. Fix the query first: projection, a supporting index, no tracking. 2. Benchmark the endpoint or the query in isolation with realistic data and concurrency, recording time and allocations per call. 3. Compile only the queries that dominate the hot path, then rerun the same benchmark. 4. Keep the change only if the gain survives realistic load; otherwise the rigid delegate is a maintenance cost with nothing in return. Remember that a compiled query still sends the same SQL, so it cannot fix a slow plan, a missing index or a result set that is too large. ## A common misdiagnosis If `compiled_query_cache_misses` keeps climbing, a compiled query is not the cure. Something produces a **different tree shape on every call**, typically a dynamically built expression that embeds values as constants. Rebuild it with parameters so the existing cache can work; only then consider compiling the hottest fixed-shape queries.
- Why can one static compiled-query delegate be called from many concurrent requests?The delegate holds only the compiled query, not a context or connection. Each call receives the request's own `DbContext` instance as its first argument, and the EF Core docs state the delegate is thread-safe across context instances. What must not be shared is the context itself, which stays one-per-request.
- The search lets users filter optionally by brand and size; how do you use compiled queries there?A compiled query cannot add a `Where` conditionally, so either compile one delegate per filter combination that really is hot, or keep the normal LINQ path for the dynamic search. Build that dynamic query with captured variables rather than constants so EF's own query cache still gets hits.
- Without EF.CompileAsyncQuery, EF Core translates LINQ to SQL from scratch on every execution.
- A compiled query delegate must be created separately for each DbContext instance.
- A compiled query can have extra Where clauses appended at the call site.
- EF.CompileAsyncQuery caches the rows the query returned between calls.
- Using EF.Constant inside a compiled query inlines the value into the SQL in EF Core 10.
Assumes EF Core 10; since EF Core 9, EF.Constant and EF.Parameter inside EF.CompileQuery or EF.CompileAsyncQuery throw InvalidCastException.