Skip to main content

RVN014 - Index Map fans out over a collection

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, TotalResults in 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:

  • Map assignments (including this.Map = … and base.Map = …), in indexes that derive from AbstractIndexCreationTask<TDocument> or AbstractIndexCreationTask<TDocument, TReduceResult>.
  • AddMap and AddMapForAll calls, in multi-map indexes, including multi-map time-series and counters indexes.

In these lambdas, RVN014 reports:

  • A SelectMany call in the lambda's method chain, such as orders.SelectMany(order => order.Lines),
    or in the source of a from clause, such as from line in orders.SelectMany(order => order.Lines).
    Reported on the SelectMany method name.
  • A from clause that follows the first from clause of the query expression, such as from line in order.Lines,
    including a from clause that follows an into continuation.
    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 the from keyword.

Each detected fanout operation is reported separately.

When is RVN014 not reported?​

  • Reduce lambdas. 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 SelectMany call inside the projection,
    such as select 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 from clause that expands each time-series segment into its entries,
    such as from entry in ts.Entries.
    A further nested from, such as from 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 = none in .editorconfig disables 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 as Products = 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 as TotalQuantity = 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.
    A Map assigned in a method is not checked (see RVN001).

  • The map lambda must appear directly in the Map assignment or the AddMap/AddMapForAll call.
    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.

  • RVN015
    Dynamic queries that need a fanout index to match conditions on the same element of a nested collection.

In this article