RVN014 - Index Map fans out over a collection
-
RVN014 reports index maps that iterate over a nested collection using
SelectManyor a nestedfromclause,
producing an index-entry for each element of the collection instead of a single index-entry per document. -
Default severity: Info
Automated code fix: No -
In this article:
Description
What is a fanout index?
An index whose map iterates over a nested collection is a fanout index:
it produces an index-entry for each element of the collection, instead of a single index-entry per document.
For example, an index that maps the lines of each order produces one index-entry per order line,
so an order with 50 lines produces 50 index-entries.
A fanout index is the right choice when a query must match several conditions on the same element,
such as an order line with a specific product and a quantity above 10 (see RVN015).
Performance and paging
The cost of a fanout index grows with the size of the collection:
- Indexing takes longer and uses more CPU and memory, and the index takes more storage.
- When a query returns full documents,
TotalResultsin the query statistics counts the matching index-entries,
not the documents.
Paging must account for the duplicate results the server skips (see Paging through tampered results).
Runtime performance hint and RVN014
When a single document produces more index-entries than the PerformanceHints.Indexing.MaxIndexOutputsPerDocument threshold (1024 by default),
the server raises a "High indexing fanout ratio" performance hint at runtime.
RVN014 is reported at compile time when the map contains a fanout pattern detected by the C# analyzer
(see Trigger condition).
RVN014 does not check the collection's runtime size, so it is reported even when the server's performance-hint threshold is not exceeded.
Trigger condition
When is RVN014 reported?
RVN014 checks the map lambdas in the constructors of the index class:
Mapassignments (includingthis.Map = …andbase.Map = …), in indexes that derive fromAbstractIndexCreationTask<TDocument>orAbstractIndexCreationTask<TDocument, TReduceResult>.AddMapandAddMapForAllcalls, in multi-map indexes, including multi-map time-series and counters indexes.
In these lambdas, RVN014 reports:
- A
SelectManycall in the lambda's method chain, such asorders.SelectMany(order => order.Lines),
or in the source of afromclause, such asfrom line in orders.SelectMany(order => order.Lines).
Reported on theSelectManymethod name. - A
fromclause that follows the firstfromclause of the query expression, such asfrom line in order.Lines,
including afromclause that follows anintocontinuation.
This is also reported when the query expression is wrapped in parentheses or followed by a method call,
such as(from order in orders from line in order.Lines select …).Where(…).
Reported on thefromkeyword.
Each detected fanout operation is reported separately.
When is RVN014 not reported?
-
Reducelambdas. A reduce function aggregates the index-entries that the map produced, so it does not add index-entries per document. -
A query expression or a
SelectManycall inside the projection,
such asselect new { Products = from line in order.Lines select line.Product }.
It computes a value for the document's single index-entry. -
In multi-map time-series indexes, the
fromclause that expands each time-series segment into its entries,
such asfrom entry in ts.Entries.
A further nestedfrom, such asfrom value in entry.Values, is reported. -
JavaScript indexes (
AbstractJavaScriptIndexCreationTask), which define their maps as strings.
How to resolve
Decide whether the index needs an index-entry per element:
-
If the fanout is intentional, for example to match several conditions on the same element,
make sure the collection size is acceptable for your workload, and suppress RVN014 for that index with
#pragma warning disable RVN014.
See Suppress diagnostics for how to disable and restore a diagnostic around a specific code block.Setting
dotnet_diagnostic.RVN014.severity = nonein.editorconfigdisables RVN014 for all files matched by that configuration section, which can also hide unintended fanout maps. -
If the fanout is not needed, produce a single index-entry per document:
-
To query documents by values from a nested collection, index the values as a collection in one index-field,
such asProducts = order.Lines.Select(line => line.Product).
A query on that index-field matches a document when any element holds the value,
but conditions on two such index-fields can be matched by different elements. -
To query by a value computed over the collection, aggregate it,
such asTotalQuantity = order.Lines.Sum(line => line.Quantity).
-
Fanout map (triggers RVN014)
public class Orders_ByProduct : AbstractIndexCreationTask<Order>
{
public class IndexEntry
{
// The index-fields
public string Product { get; set; }
public int Quantity { get; set; }
}
public Orders_ByProduct()
{
// Triggers RVN014: SelectMany produces an index-entry per order line.
Map = orders => orders.SelectMany(
order => order.Lines,
(order, line) => new IndexEntry
{
Product = line.Product,
Quantity = line.Quantity
});
}
}
public class Orders_ByProduct : AbstractIndexCreationTask<Order>
{
public class IndexEntry
{
// The index-fields
public string Product { get; set; }
public int Quantity { get; set; }
}
public Orders_ByProduct()
{
Map = orders => from order in orders
// Triggers RVN014: the nested 'from' produces an index-entry per order line.
from line in order.Lines
select new IndexEntry
{
Product = line.Product,
Quantity = line.Quantity
};
}
}
Intentional fanout (suppress RVN014 with a pragma)
public class Orders_ByProductAndQuantity : AbstractIndexCreationTask<Order>
{
public class IndexEntry
{
// The index-fields
public string Product { get; set; }
public int Quantity { get; set; }
}
public Orders_ByProductAndQuantity()
{
// The fanout is intentional: each order line is a separate index-entry,
// so a query can match the product and the quantity on the same line.
// Suppress RVN014 for this intentional fanout map.
#pragma warning disable RVN014
Map = orders => from order in orders
from line in order.Lines
select new IndexEntry
{
Product = line.Product,
Quantity = line.Quantity
};
#pragma warning restore RVN014
}
}
// Orders that have a line with more than 10 units of products/1-A
var orders = session
.Query<Orders_ByProductAndQuantity.IndexEntry, Orders_ByProductAndQuantity>()
.Where(x => x.Product == "products/1-A" && x.Quantity > 10)
.OfType<Order>()
.Take(50)
.ToList();
Avoid fanout by indexing collection values in a single entry
public class Orders_ByProducts : AbstractIndexCreationTask<Order>
{
public class IndexEntry
{
// The index-fields
public IEnumerable<string> Products { get; set; }
}
public Orders_ByProducts()
{
// A single index-entry per order:
// the 'Products' index-field holds the products of all order lines.
Map = orders => from order in orders
select new IndexEntry
{
Products = order.Lines.Select(line => line.Product)
};
}
}
// Orders that have a line with products/1-A
var orders = session
.Query<Orders_ByProducts.IndexEntry, Orders_ByProducts>()
.Where(x => x.Products.Contains("products/1-A"))
.OfType<Order>()
.Take(50)
.ToList();
Limitations
-
RVN014 checks only lambdas in constructor bodies.
AMapassigned in a method is not checked (see RVN001). -
The map lambda must appear directly in the
Mapassignment or theAddMap/AddMapForAllcall.
A map expression stored in a variable and then assigned or passed to the call is not checked. -
Single-map time-series and counters indexes are not checked.
Related C# analyzers
- RVN015
Dynamic queries that need a fanout index to match conditions on the same element of a nested collection.