---
title: "Indexing Nested data"
url: "https://docs.ravendb.net/6.2/indexes/indexing-nested-data"
version: "6.2"
language: "csharp"
---

# Indexing Nested data

> Client language: C#. Also available for [Java](https://docs.ravendb.net/6.2/indexes/indexing-nested-data.java.md), [Python](https://docs.ravendb.net/6.2/indexes/indexing-nested-data.python.md), [PHP](https://docs.ravendb.net/6.2/indexes/indexing-nested-data.php.md), [Node.js](https://docs.ravendb.net/6.2/indexes/indexing-nested-data.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - JSON documents can have nested structures, where one document contains other objects or arrays of objects.
>
> - Use a static-index to facilitate querying for documents based on the nested data.
>
> - In this page:
>
>   - [Sample data](#sample-data)
>
>   - [Simple index - SINGLE index-entry per document](#simple-index---single-index-entry-per-document)
>     - [The index](#theIndex)
>     - [The index-entries](#theIndexEntries)
>     - [Querying the index](#queryingTheIndex)
>     - [When to use](#whenToUse)
>
>   - [Fanout index - MULTIPLE index-entries per document](#fanout-index---multiple-index-entries-per-document)
>     - [What is a fanout index](#whatIsFanoutIndex)
>     - [Fanout index - Map index example](#fanoutMapIndex)
>     - [Fanout index - Map-Reduce index example](#fanoutMapReduceIndex)
>     - [Performance hints](#performanceHints)
>     - [Paging](#paging)

## Sample data

- The examples in this article are based on the following **Classes** and **Sample Data**:

### Class

```csharp
public class OnlineShop
{
  public string ShopName { get; set; }
  public string Email { get; set; }
  public List<TShirt> TShirts { get; set; } // Nested data
}

public class TShirt
{
  public string Color { get; set; }
  public string Size { get; set; }
  public string Logo { get; set; }
  public decimal Price { get; set; }
  public int Sold { get; set; }
}
```

### Sample\_data

```csharp
// Creating sample data for the examples in this article:
// ======================================================

var onlineShops = new[]
{
// Shop1
new OnlineShop { ShopName = "Shop1", Email = "sales@shop1.com", TShirts = new List<TShirt> {
    new TShirt { Color = "Red", Size = "S", Logo = "Bytes and Beyond", Price = 25, Sold = 2 },
    new TShirt { Color = "Red", Size = "M", Logo = "Bytes and Beyond", Price = 25, Sold = 4 },
    new TShirt { Color = "Blue", Size = "M", Logo = "Query Everything", Price = 28, Sold = 5 },
    new TShirt { Color = "Green", Size = "L", Logo = "Data Driver", Price = 30, Sold = 3}
}},
// Shop2
new OnlineShop { ShopName = "Shop2", Email = "sales@shop2.com", TShirts = new List<TShirt> {
    new TShirt { Color = "Blue", Size = "S", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 12 },
    new TShirt { Color = "Blue", Size = "M", Logo = "Coffee, Code, Repeat", Price = 22, Sold = 7 },
    new TShirt { Color = "Green", Size = "M", Logo = "Big Data Dreamer", Price = 25, Sold = 9 },
    new TShirt { Color = "Black", Size = "L", Logo = "Data Mining Expert", Price = 20, Sold = 11 }
}},
// Shop3
new OnlineShop { ShopName = "Shop3", Email = "sales@shop3.com", TShirts = new List<TShirt> {
    new TShirt { Color = "Red", Size = "S", Logo = "Bytes of Wisdom", Price = 18, Sold = 2 },
    new TShirt { Color = "Blue", Size = "M", Logo = "Data Geek", Price = 20, Sold = 6 },
    new TShirt { Color = "Black", Size = "L", Logo = "Data Revolution", Price = 15, Sold = 8 },
    new TShirt { Color = "Black", Size = "XL", Logo = "Data Revolution", Price = 15, Sold = 10 }
}}
};

using (var session = store.OpenSession())
{
  foreach (var shop in onlineShops)
  {
      session.Store(shop);
  }

  session.SaveChanges();
}
```

## Simple index - Single index-entry per document

- &#x20;**The index**:

```csharp
public class Shops_ByTShirt_Simple : AbstractIndexCreationTask<OnlineShop>
{
  public class IndexEntry
  {
      // The index-fields:
      public IEnumerable<string> Colors { get; set; }
      public IEnumerable<string> Sizes { get; set; }
      public IEnumerable<string> Logos { get; set; }
  }
  
  public Shops_ByTShirt_Simple()
  {
      Map = shops => from shop in shops
          // Creating a SINGLE index-entry per document:
          select new IndexEntry
          {
              // Each index-field will hold a collection of nested values from the document
              Colors = shop.TShirts.Select(x => x.Color),
              Sizes = shop.TShirts.Select(x => x.Size),
              Logos = shop.TShirts.Select(x => x.Logo)
          };
  }
}
```

- &#x20;**The index-entries**:

  ![Simple - index-entries](https://docs.ravendb.net/assets/images/indexing-nested-data-1-3f0d67700246d2f350eb7781c7b3654d.png)

  1. The index-entries content is visible from the Studio [Query view](https://docs.ravendb.net/6.2/studio/database/queries/query-view.md).

  2. Check option: *Show raw index-entries instead of Matching documents*.

  3. Each row represents an **index-entry**.  
     The index has a single index-entry per document (3 entries in this example).

  4. The index-field contains a collection of ALL nested values from the document.  
     e.g. The third **index-entry** has the following values in the *Colors* **index-field**:  
     `{"black", "blue", "red"}`

- &#x20;**Querying the index**:

### Query

```csharp
// Query for all shop documents that have a red TShirt
var shopsThatHaveRedShirts = session
  .Query<Shops_ByTShirt_Simple.IndexEntry, Shops_ByTShirt_Simple>()
   // Filter query results by a nested value
  .Where(x => x.Colors.Contains("red"))
  .OfType<OnlineShop>()
  .ToList();
```

### Query\_async

```csharp
// Query for all shop documents that have a red TShirt
var shopsThatHaveRedShirts = await asyncSession
  .Query<Shops_ByTShirt_Simple.IndexEntry, Shops_ByTShirt_Simple>()
   // Filter query results by a nested value
  .Where(x => x.Colors.Contains("red"))
  .OfType<OnlineShop>()
  .ToListAsync();
```

### DocumentQuery

```csharp
// Query for all shop documents that have a red TShirt
var shopsThatHaveRedShirts = session.Advanced
  .DocumentQuery<Shops_ByTShirt_Simple.IndexEntry, Shops_ByTShirt_Simple>()
   // Filter query results by a nested value
  .ContainsAny(x => x.Colors, new[] { "Red" })
  .OfType<OnlineShop>()
  .ToList();
```

### RQL

```sql
from index "Shops/ByTShirt/Simple"
where Colors == "red"
```

```csharp
// Results will include the following shop documents:
// ==================================================
// * Shop1
// * Shop3
```

- &#x20;**When to use**:

  - This type of index structure is effective for retrieving documents when filtering the query by any of the inner nested values that were indexed.

  - However, due to the way the index-entries are generated, this index **cannot** provide results for a query searching for documents that contain
    specific sub-objects which satisfy some `AND` condition.  
    For example:

```csharp
// You want to query for shops containing "Large Green TShirts",
// aiming to get only "Shop1" as a result since it has such a combination,
// so you attempt this query:
var GreenAndLarge = session
  .Query<Shops_ByTShirt_Simple.IndexEntry, Shops_ByTShirt_Simple>()
  .Where(x => x.Colors.Contains("green") && x.Sizes.Contains("L"))
  .OfType<OnlineShop>()
  .ToList();

// But, the results of this query will include BOTH "Shop1" & "Shop2"
// since the index-entries do not keep the original sub-objects structure.
```

- To address this, you must use a **Fanout index** - as described below.

## Fanout index - Multiple index-entries per document

- &#x20;**What is a Fanout index**:

  - A fanout index is an index that outputs multiple index-entries per document.  
    A separate index-entry is created for each nested sub-object from the document.

  - The fanout index is useful when you need to retrieve documents matching query criteria  
    that search for specific sub-objects that comply with some logical conditions.

- &#x20;**Fanout index - Map index example**:

### LINQ\_index

```csharp
// A fanout map-index:
// ===================
public class Shops_ByTShirt_Fanout : AbstractIndexCreationTask<OnlineShop>
{
  public class IndexEntry
  {
      // The index-fields:
      public string Color { get; set; }
      public string Size { get; set; }
      public string Logo { get; set; }
  }
  
  public Shops_ByTShirt_Fanout()
  {
      Map = shops =>
          from shop in shops
          from shirt in shop.TShirts
          // Creating MULTIPLE index-entries per document,
          // an index-entry for each sub-object in the TShirts list
          select new IndexEntry
          {
              Color = shirt.Color,
              Size = shirt.Size,
              Logo = shirt.Logo
          };
  }
}
```

### JavaScript\_index

```csharp
public class Shops_ByTShirt_JS : AbstractJavaScriptIndexCreationTask
{
  public Shops_ByTShirt_JS()
  {
      Maps = new HashSet<string>
      {
          @"map('OnlineShops', function (shop){ 
                 var res = [];
                 shop.TShirts.forEach(shirt => {
                     res.push({
                         Color: shirt.Color,
                         Size: shirt.Size,
                         Logo: shirt.Logo
                     })
                  });
                  return res;
              })"
      };
  }
}
```

### Query

```csharp
// Query the fanout index:
// =======================
var shopsThatHaveMediumRedShirts = session
  .Query<Shops_ByTShirt_Fanout.IndexEntry, Shops_ByTShirt_Fanout>()
   // Query for documents that have a "Medium Red TShirt"
  .Where(x => x.Color == "red" && x.Size == "M")
  .OfType<OnlineShop>()
  .ToList();
```

### Query\_async

```csharp
// Query the fanout index:
// =======================
var shopsThatHaveMediumRedShirts = await asyncSession
  .Query<Shops_ByTShirt_Fanout.IndexEntry, Shops_ByTShirt_Fanout>()
   // Query for documents that have a "Medium Red TShirt"
  .Where(x => x.Color == "red" && x.Size == "M")
  .OfType<OnlineShop>()
  .ToListAsync();
```

### DocumentQuery

```csharp
// Query the fanout index:
// =======================
var shopsThatHaveMediumRedShirts = session.Advanced
  .DocumentQuery<Shops_ByTShirt_Fanout.IndexEntry, Shops_ByTShirt_Fanout>()
   // Query for documents that have a "Medium Red TShirt"
  .WhereEquals(x => x.Color, "red")
  .AndAlso()
  .WhereEquals(x=> x.Size, "M")
  .OfType<OnlineShop>()
  .ToList();
```

### RQL

```sql
from index "Shops/ByTShirt/Fanout" 
where Color == "red" and Size == "M"
```

```csharp
// Query results:
// ==============

// Only the 'Shop1' document will be returned,
// since it is the only document that has the requested combination within the TShirt list.
```

- &#x20;**The index-entries**:
  ![Fanout - index-entries](https://docs.ravendb.net/assets/images/indexing-nested-data-2-cf449e84d78e68d7c52a1600034a7ad3.png)

  1. The index-entries content is visible from the Studio [Query view](https://docs.ravendb.net/6.2/studio/database/queries/query-view.md).

  2. Check option: *Show raw index-entries instead of Matching documents*.

  3. Each row represents an **index-entry**.  
     Each index-entry corresponds to an inner item in the TShirt list.

  4. In this example, the total number of index-entries is **12**,  
     which is the total number of inner items in the TShirt list in all **3** documents in the collection.

- &#x20;**Fanout index - Map-Reduce index example**:

  - The fanout index concept applies to map-reduce indexes as well:

### LINQ\_index

```csharp
// A fanout map-reduce index:
// ==========================
public class Sales_ByTShirtColor_Fanout : 
  AbstractIndexCreationTask<OnlineShop, Sales_ByTShirtColor_Fanout.IndexEntry>
{
  public class IndexEntry
  {
      // The index-fields:
      public string Color { get; set; }
      public int ItemsSold { get; set; }
      public decimal TotalSales { get; set; }
  }

  public Sales_ByTShirtColor_Fanout()
  {
      Map = shops => 
          from shop in shops
          from shirt in shop.TShirts
          // Creating MULTIPLE index-entries per document,
          // an index-entry for each sub-object in the TShirts list
          select new IndexEntry
          {
              Color = shirt.Color,
              ItemsSold = shirt.Sold,
              TotalSales = shirt.Price * shirt.Sold
          };

      Reduce = results => from result in results
          group result by result.Color
          into g
          select new
          {
              // Calculate sales per color
              Color = g.Key,
              ItemsSold = g.Sum(x => x.ItemsSold),
              TotalSales = g.Sum(x => x.TotalSales)
          };
  }
}
```

### JavaScript\_index

```csharp
public class Product_Sales : AbstractJavaScriptIndexCreationTask
{
  public class Result
  {
      public string Product { get; set; }

      public int Count { get; set; }

      public decimal Total { get; set; }
  }

  public Product_Sales()
  {
      Maps = new HashSet<string>()
      {
          @"map('orders', function(order){
                  var res = [];
                  order.Lines.forEach(l => {
                      res.push({
                          Product: l.Product,
                          Count: 1,
                          Total:  (l.Quantity * l.PricePerUnit) * (1- l.Discount)
                      })
                  });
                  return res;
              })"
      };

      Reduce = @"groupBy(x => x.Product)
          .aggregate(g => {
              return {
                  Product : g.key,
                  Count: g.values.reduce((sum, x) => x.Count + sum, 0),
                  Total: g.values.reduce((sum, x) => x.Total + sum, 0)
              }
          })";
  }
}
```

### Query

```csharp
// Query the fanout index:
// =======================
var queryResult = session
  .Query<Sales_ByTShirtColor_Fanout.IndexEntry, Sales_ByTShirtColor_Fanout>()
   // Query for index-entries that contain "black"
  .Where(x => x.Color == "black")
  .FirstOrDefault();

// Get total sales for black TShirts
var blackShirtsSales = queryResult?.TotalSales ?? 0;
```

### Query\_async

```csharp
// Query the fanout index:
// =======================
var queryResult = await asyncSession
  .Query<Sales_ByTShirtColor_Fanout.IndexEntry, Sales_ByTShirtColor_Fanout>()
   // Query for index-entries that contain "black"
  .Where(x => x.Color == "black")
  .FirstOrDefaultAsync();

// Get total sales for black TShirts
var blackShirtsSales = queryResult?.TotalSales ?? 0;
```

### DocumentQuery

```csharp
// Query the fanout index:
// =======================
var queryResult = session.Advanced
  .DocumentQuery<Sales_ByTShirtColor_Fanout.IndexEntry, Sales_ByTShirtColor_Fanout>()
  // Query for index-entries that contain "black"
  .WhereEquals(x => x.Color, "black")
  .FirstOrDefault();

// Get total sales for black TShirts
var blackShirtsSales = queryResult?.TotalSales ?? 0;
```

### RQL

```sql
from index "Sales/ByTShirtColor/Fanout"
where Color == "black"
```

```csharp
// Query results:
// ==============

// With the sample data used in this article,
// The total sales revenue from black TShirts sold (in all shops) is 490.0
```

- &#x20;**Fanout index - Performance hints**:

  - Fanout indexes are typically more resource-intensive than other indexes as RavenDB has to index a large number of index-entries.
    This increased workload can lead to higher CPU and memory utilization, potentially causing a decline in the overall performance of the index.

  - When the number of index-entries generated from a single document exceeds a configurable limit,  
    RavenDB will issue a **High indexing fanout ratio** alert in the Studio notification center.

  - You can control when this performance hint is created by setting the
    [PerformanceHints.Indexing.MaxIndexOutputsPerDocument](https://docs.ravendb.net/6.2/server/configuration/performance-hints-configuration.md#performancehintsindexingmaxindexoutputsperdocument) configuration key
    (default is 1024).

  - So, for example, adding another OnlineShop document with a `tShirt` object containing 1025 items  
    will trigger the following alert:

    ![Figure 1. High indexing fanout ratio notification](https://docs.ravendb.net/assets/images/fanout-index-performance-hint-1-5cb0b8230389f290be80379208488835.png)

  - Clicking the 'Details' button will show the following info:

    ![Figure 2. Fanout index, performance hint details](https://docs.ravendb.net/assets/images/fanout-index-performance-hint-2-00a4e7bf96dfe54a8ac2de03a7853c03.png)

- &#x20;**Fanout index - Paging**:

  - A fanout index has more index-entries than the number of documents in the collection indexed.  
    Multiple index-entries "point" to the same document from which they originated,  
    as can be seen in the above [index-entries](#fanoutMapIndexIndexEntries) example.

  - When making a fanout index query that should return full documents (without projecting results),  
    then in this case, the `TotalResults` property (available via the `QueryStatistics` object) will contain  
    the total number of index-entries and Not the total number of resulting documents.

  - **To overcome this when paging results**, you must take into account the number of "duplicate"  
    index-entries that are skipped internally by the server when serving the resulting documents.

  - Please refer to [paging through tampered results](https://docs.ravendb.net/6.2/indexes/querying/paging.md#paging-through-tampered-results) for further explanation and examples.

## See also

- [What are Indexes](https://docs.ravendb.net/6.2/indexes/what-are-indexes.md)
- [Intersect queries](https://docs.ravendb.net/6.2/indexes/querying/intersection.md)
