---
title: "Project Query Results"
url: "https://docs.ravendb.net/6.2/client-api/session/querying/how-to-project-query-results"
version: "6.2"
language: "csharp"
---

# Project Query Results

> Client language: C#. Also available for [Java](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-project-query-results.java.md), [Python](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-project-query-results.python.md), [PHP](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-project-query-results.php.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-project-query-results.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**
>
> - Applying a projection in a query allows you to shape the query results to meet specific requirements,  
>   delivering just the data needed instead of the original full document content.
>
> - This article provides examples of projecting query results when making a **dynamic-query**.  
>   For projecting results when querying a **static-index** see [project index query results](https://docs.ravendb.net/6.2/indexes/querying/projections.md).
>
> - In this article:
>   - [Projections overview](#projections-overview)
>   - [Projection Methods](#projection-methods)
>     - [Select](#select)
>     - [ProjectInto](#projectinto)
>     - [SelectFields](#selectfields)
>   - [Single projection per query](#single-projection-per-query)

## Projections overview

**What are projections**:

- A projection refers to the **transformation of query results** into a customized structure,  
  modifying the shape of the data returned by the server.

- Instead of retrieving the full document from the server and then picking relevant data from it on the client,  
  you can request a subset of the data, specifying the document fields you want to get from the server.

- The query can load [related documents](https://docs.ravendb.net/6.2/indexes/indexing-related-documents.md#what-are-related-documents) and have their data merged into the projection results.

- Objects and arrays, including content from nested structures, can be projected.  
  An alias name can be given to the projected fields, and any calculations can be applied within the projection.
  **When to use projections**:

- Projections allow you to tailor the query results specifically to your needs.  
  Getting specific details to display can be useful when presenting data to users or populating user interfaces.  
  Projection queries are also useful with [subscriptions](https://docs.ravendb.net/6.2/client-api/data-subscriptions/what-are-data-subscriptions.md)
  since all transformation work is done on the server side without having to send a lot of data over the wire.

- Returning partial document data from the server reduces network traffic,  
  as clients receive only relevant data required for a particular task, enhancing overall performance.

- Savings can be significant if you need to show just a bit of information from a large document. For example:  
  the size of the result when querying for all "Orders" documents where "Company" is "companies/65-A" is 19KB.  
  Performing the same query and projecting only the "Employee" and "OrderedAt" fields results in only 5KB.

- However, when you need to actively work with the complete set of data on the client side,  
  then do use a query without a projection to retrieve the full document from the server.
  **Projections are not tracked by the session**:

- On the client side, the resulting projected entities returned by the query are Not tracked by the Session.

- Any modification made to a projection entity will not modify the corresponding document on the server when *SaveChanges* is called.
  **Projections are the final stage in the query pipeline**:

- Projections are applied as the last stage in the query pipeline,  
  after the query has been processed, filtered, sorted, and paged.

- This means that the projection does Not apply to all the documents in the collection,  
  but only to the documents matching the query predicate.

- Within the projection you can only filter what data will be returned from the matching documents,  
  but you cannot filter which documents will be returned. That has already been determined earlier in the query pipeline.

- Only a single projection request can be made per Query (and DocumentQuery).  
  Learn more in [single projection per query](#single-projection-per-query).
  **The cost of projections**:

- Queries in RavenDB do not allow any computation to occur during the query phase.  
  However, you can perform any [calculations](#example---projection-with-calculations)
  inside the projection.

- But while calculations within a projection are allowed, having a very complex logic can impact query performance.  
  So RavenDB limits the total time it will spend processing a query and its projections.  
  Exceeding this time limit will fail the query. This is configurable, see the following configuration keys:
  - [Databases.QueryTimeoutInSec](https://docs.ravendb.net/6.2/server/configuration/database-configuration.md#databasesquerytimeoutinsec)
  - [Databases.QueryOperationTimeoutInSec](https://docs.ravendb.net/6.2/server/configuration/database-configuration.md#databasesqueryoperationtimeoutinsec)

## Projection Methods

## Select

- The most common way to perform a query with a projection is to use the `Select` method.

- You can specify what fields from the document you want to retrieve and even provide a complex expression.

> **Note**
>
> ##### Example I - Projecting individual fields of the document:
>
> ###### Query
>
> ```csharp
> var projectedResults = session
>    // Make a dynamic query on the Companies collection
>   .Query<Company>()
>    // Call Select to define the new structure that will be returned per Company document
>   .Select(x => new
>   {
>       Name = x.Name,
>       City = x.Address.City,
>       Country = x.Address.Country
>   })
>   .ToList();
>
> // Each resulting object in the list is Not a 'Company' entity,
> // it is a new object containing ONLY the fields specified in the Select.
> ```
>
> ###### Query\_async
>
> ```csharp
> var projectedResults = await asyncSession
>   // Make a dynamic query on the Companies collection
>   .Query<Company>()
>   // Call Select to define the new structure that will be returned per Company document
>   .Select(x => new {Name = x.Name, City = x.Address.City, Country = x.Address.Country})
>   .ToListAsync();
>
> // Each resulting object in the list is Not a 'Company' entity,
> // it is a new object containing ONLY the fields specified in the Select.
> ```
>
> ###### RQL
>
> ```sql
> from "Companies"
> select Name, Address.City as City, Address.Country as Country
> ```

> **Note**
>
> ##### Example II - Projecting arrays and objects:
>
> ###### Query
>
> ```csharp
> var projectedResults = session
>   .Query<Order>()
>   .Select(x => new
>   {
>       ShipTo = x.ShipTo,
>       // Retrieve all product names from the Lines array in an Order document
>       ProductNames = x.Lines.Select(y => y.ProductName)
>   })
>   .ToList();
> ```
>
> ###### Query\_async
>
> ```csharp
> var projectedResults = await asyncSession
>   .Query<Order>()
>   .Select(x => new
>   {
>       ShipTo = x.ShipTo,
>       // Retrieve all product names from the Lines array in an Order document
>       ProductNames = x.Lines.Select(y => y.ProductName)
>   })
>   .ToListAsync();
> ```
>
> ###### RQL
>
> ```sql
> // Using simple expression:
> from "Orders"
> select ShipTo, Lines[].ProductName as ProductNames
>
> // Using JavaScript object literal syntax:
> from "Orders" as x
> select {
>   ShipTo: x.ShipTo, 
>   ProductNames: x.Lines.map(y => y.ProductName)
> }
> ```

> **Note**
>
> ##### Example III - Projection with expression:
>
> ###### Query
>
> ```csharp
> var projectedResults = session
>   .Query<Employee>()
>   .Select(x => new
>   {
>       // Any expression can be provided for the projected content
>       FullName = x.FirstName + " " + x.LastName
>   })
>   .ToList();
> ```
>
> ###### Query\_async
>
> ```csharp
> var projectedResults = await asyncSession
>   .Query<Employee>()
>   .Select(x => new
>   {
>       // Any expression can be provided for the projected content
>       FullName = x.FirstName + " " + x.LastName
>   })
>   .ToListAsync();
> ```
>
> ###### RQL
>
> ```sql
> from "Employees" as e
> select {
>   FullName: e.FirstName + " " + e.LastName
> }
> ```

> **Note**
>
> ##### Example IV - Projection with calculations:
>
> ###### Query
>
> ```csharp
> var projectedResults = session
>   .Query<Order>()
>   .Select(x => new
>   {
>       // Any calculations can be done within a projection
>       TotalProducts = x.Lines.Count,
>       TotalDiscountedProducts = x.Lines.Count(x => x.Discount > 0),
>       TotalPrice = x.Lines.Sum(l => l.PricePerUnit * l.Quantity)
>   })
>   .ToList();
> ```
>
> ###### Query\_async
>
> ```csharp
> var projectedResults = await asyncSession
>   .Query<Order>()
>   .Select(x => new
>   {
>       // Any calculations can be done within a projection
>       TotalProducts = x.Lines.Count,
>       TotalDiscountedProducts = x.Lines.Count(x => x.Discount > 0),
>       TotalPrice = x.Lines.Sum(l => l.PricePerUnit * l.Quantity)
>   })
>   .ToListAsync();
> ```
>
> ###### RQL
>
> ```sql
> from "Orders" as x
> select {
>   TotalProducts: x.Lines.length,
>   TotalDiscountedProducts: x.Lines.filter(x => x.Discount > 0).length,
>   TotalPrice: x.Lines
>                 .map(l => l.PricePerUnit * l.Quantity)
>                 .reduce((a, b) => a + b, 0)
> }
> ```

> **Note**
>
> ##### Example V - Projecting using functions:
>
> ###### Query
>
> ```csharp
> // Use LINQ query syntax notation
> var projectedResults = (from e in session.Query<Employee>()
>   // Define a function
>   let format = (Func<Employee, string>)(p => p.FirstName + " " + p.LastName)
>   select new
>   {
>       // Call the function from the projection
>       FullName = format(e)
>   })
>   .ToList();
> ```
>
> ###### Query\_async
>
> ```csharp
> // Use LINQ query syntax notation
> var projectedResults = await (from e in asyncSession.Query<Employee>()
>   // Define a function
>   let format = (Func<Employee, string>)(p => p.FirstName + " " + p.LastName)
>   select new
>   {
>       // Call the function from the projection
>       FullName = format(e)
>   })
>   .ToListAsync();
> ```
>
> ###### RQL
>
> ```sql
> declare function output(e) {
>   var format = p => p.FirstName + " " + p.LastName;
>   return { FullName: format(e) };
> }
> from "Employees" as e select output(e)
> ```

> **Note**
>
> ##### Example VI - Projecting using a loaded document:
>
> ###### Query
>
> ```csharp
> // Use LINQ query syntax notation
> var projectedResults = (from o in session.Query<Order>()
>   // Use RavenQuery.Load to load the related Company document
>   let c = RavenQuery.Load<Company>(o.Company)
>   select new
>   {
>       CompanyName = c.Name, // info from the related Company document
>       ShippedAt = o.ShippedAt // info from the Order document
>   })
>   .ToList();
> ```
>
> ###### Query\_async
>
> ```csharp
> // Use LINQ query syntax notation
> var projectedResults = (from o in asyncSession.Query<Order>()
>   // Use RavenQuery.Load to load the related Company document
>   let c = RavenQuery.Load<Company>(o.Company)
>   select new
>   {
>       CompanyName = c.Name, // info from the related Company document
>       ShippedAt = o.ShippedAt // info from the Order document
>   })
>   .ToListAsync();
> ```
>
> ###### RQL
>
> ```sql
> from "Orders" as o
> load o.Company as c
> select {
>   CompanyName: c.Name,
>   ShippedAt: o.ShippedAt
> }
> ```

> **Note**
>
> ##### Example VII - Projection with dates:
>
> ###### Query
>
> ```csharp
> var projectedResults = session
>   .Query<Employee>()
>   .Select(e => new
>   {
>       DayOfBirth = e.Birthday.Day,
>       MonthOfBirth = e.Birthday.Month,
>       Age = DateTime.Today.Year - e.Birthday.Year
>   })
>   .ToList();
> ```
>
> ###### Query\_async
>
> ```csharp
> var projectedResults = await asyncSession
>   .Query<Employee>()
>   .Select(e => new
>   {
>       DayOfBirth = e.Birthday.Day,
>       MonthOfBirth = e.Birthday.Month,
>       Age = DateTime.Today.Year - e.Birthday.Year
>   })
>   .ToListAsync();
> ```
>
> ###### RQL
>
> ```sql
> from "Employees" as e 
> select { 
>   DayOfBirth: new Date(Date.parse(e.Birthday)).getDate(), 
>   MonthOfBirth: new Date(Date.parse(e.Birthday)).getMonth() + 1,
>   Age: new Date().getFullYear() - new Date(Date.parse(e.Birthday)).getFullYear() 
> }
> ```

> **Note**
>
> ##### Example VIII - Projection with raw JavaScript code:
>
> ###### Query
>
> ```csharp
> var projectedResults = session.Query<Employee>()
>   .Select(e => new
>   {
>       // Provide a JavaScript expression to the RavenQuery.Raw method
>       Date = RavenQuery.Raw<DateTime>("new Date(Date.parse(e.Birthday))"),
>       Name = RavenQuery.Raw(e.FirstName, "substr(0, 3)")
>   })
>   .ToList();
> ```
>
> ###### Query\_async
>
> ```csharp
> var projectedResults = await asyncSession.Query<Employee>()
>   .Select(e => new
>   {
>       // Provide a JavaScript expression to the RavenQuery.Raw method
>       Date = RavenQuery.Raw<DateTime>("new Date(Date.parse(e.Birthday))"),
>       Name = RavenQuery.Raw(e.FirstName, "substr(0, 3)")
>   })
>   .ToListAsync();
> ```
>
> ###### RQL
>
> ```sql
> from "Employees" as e 
> select {
>   Date: new Date(Date.parse(e.Birthday)), 
>   Name: e.FirstName.substr(0, 3)
> }
> ```

> **Note**
>
> ##### Example IX - Projection with metadata:
>
> ###### Query
>
> ```csharp
> var projectedResults = session.Query<Employee>()
>   .Select(e => new
>   {
>       Name = e.FirstName, Metadata = RavenQuery.Metadata(e) // Get the metadata
>   })
>   .ToList();
> ```
>
> ###### Query\_async
>
> ```csharp
> var projectedResults = await asyncSession.Query<Employee>()
>   .Select(e => new
>   {
>       Name = e.FirstName, Metadata = RavenQuery.Metadata(e) // Get the metadata
>   })
>   .ToListAsync();
> ```
>
> ###### RQL
>
> ```sql
> from "Employees" as e 
> select {
>    Name: e.FirstName, 
>    Metadata: getMetadata(e)
> }
> ```

> **Note**
>
> ##### Example X - Projection with include:
>
> When using `Include` in a projection query,  
> RavenDB includes the related document only if the included path is one of the fields in the projection.
>
> ###### Query
>
> ```csharp
> var projectedResults = session
>   .Query<Product>()
>    // NOTE:
>    // While the following 'Include' line compiles,
>    // the related Supplier document will NOT BE INCLUDED in the query results,
>    // because 'Supplier' is not one of the projected fields in the 'Select' clause.
>   .Include(x => x.Supplier)
>   .Select(x => new
>   {
>       Name = x.Name,
>       ProductCategory = x.Category
>   })
>    // The related Category document WILL BE INCLUDED in the query results,
>    // since 'ProductCategory' is one of the projected fields.
>   .Include(x => x.ProductCategory)
>   .ToList();
> ```
>
> ###### Query\_async
>
> ```csharp
> var projectedResults = await asyncSession
>   .Query<Product>()
>    // NOTE:
>    // While the following 'Include' line compiles,
>    // the related Supplier document will NOT BE INCLUDED in the query results,
>    // because 'Supplier' is not one of the projected fields in the 'Select' clause.
>   .Include(x => x.Supplier)
>   .Select(x => new
>   {
>       Name = x.Name,
>       ProductCategory = x.Category
>   })
>    // The related Category document WILL BE INCLUDED in the query results,
>    // since 'ProductCategory' is one of the projected fields.
>   .Include(x =>x.ProductCategory)
>   .ToListAsync();
> ```
>
> ###### RQL
>
> ```sql
> from "Products"
> select Name, Category as ProductCategory
> include Supplier, ProductCategory
>
> // NOTE:
> // Only the related Category document WILL BE INCLUDED in the query results.
>
> // The related Supplier document will NOT BE INCLUDED in the query results,
> // because 'Supplier' is Not one of the projected fields in the 'select' clause.
> ```

## ProjectInto

- Instead of `Select`, you can use `ProjectInto` to project all public fields from a generic type.

- The results will be projected into objects of the specified projection class.

### Query

```csharp
var projectedResults = session
  .Query<Company>()
  // Call 'ProjectInto' instead of using 'Select'
  // Pass the projection class
  .ProjectInto<ContactDetails>()
  .ToList();

// Each resulting object in the list is Not a 'Company' entity,
// it is an object of type 'ContactDetails'.
```

### Query\_async

```csharp
var projectedResults = await asyncSession
  .Query<Company>()
  // Call 'ProjectInto' instead of using 'Select'
  // Pass the projection class
  .ProjectInto<ContactDetails>()
  .ToListAsync();

// Each resulting object in the list is Not a 'Company' entity,
// it is an object of type 'ContactDetails'.
```

### Projection\_class

```csharp
public class ContactDetails
{
  // The projection class contains field names from the 'Company' document
  public string Name { get; set; }
  public string Phone { get; set; }
  public string Fax { get; set; }
}
```

### RQL

```sql
from "Companies"
select Name, Phone, Fax
```

## SelectFields

The `SelectFields` method can only be used by a [Document Query](https://docs.ravendb.net/6.2/client-api/session/querying/document-query/what-is-document-query.md).  
It has two overloads:

```csharp
// 1) Select fields to project by the projection class type
IDocumentQuery<TProjection> SelectFields<TProjection>();

// 2) Select specific fields to project
IDocumentQuery<TProjection> SelectFields<TProjection>(params string[] fields);
```

> **Note**
>
> ##### Using projection class type
>
> The projection class fields are the fields that you want to project from the document class.
>
> ###### DocumentQuery
>
> ```csharp
> // Make a dynamic DocumentQuery
> var projectedResults = session.Advanced
>   .DocumentQuery<Company>()
>   // Call 'SelectFields'
>   // Pass the projection class type
>   .SelectFields<ContactDetails>()
>   .ToList();
>
> // Each resulting object in the list is Not a 'Company' entity,
> // it is an object of type 'ContactDetails'.
> ```
>
> ###### DocumentQuery\_async
>
> ```csharp
> // Make a dynamic DocumentQuery
> var projectedResults = await asyncSession.Advanced
>   .AsyncDocumentQuery<Company>()
>   // Call 'SelectFields'
>   // Pass the projection class type
>   .SelectFields<ContactDetails>()
>   .ToListAsync();
>
> // Each resulting object in the list is Not a 'Company' entity,
> // it is an object of type 'ContactDetails'.
> ```
>
> ###### Projection\_class
>
> ```csharp
> public class ContactDetails
> {
>   // The projection class contains field names from the 'Company' document
>   public string Name { get; set; }
>   public string Phone { get; set; }
>   public string Fax { get; set; }
> }
> ```
>
> ###### RQL
>
> ```sql
> from "Companies"
> select Name, Phone, Fax
> ```

> **Note**
>
> ##### Using specific fields
>
> The fields specified are the fields that you want to project from the projection class.
>
> ###### DocumentQuery
>
> ```csharp
> // Define an array with the field names that will be projected
> var projectionFields = new string[]
> {
>   // Fields from 'ContactDetails' class:
>   "Name", "Phone"
> };
>
> // Make a dynamic DocumentQuery
> var projectedResults = session.Advanced
>   .DocumentQuery<Company>()
>   // Call 'SelectFields'
>   // Pass the projection class type & the fields to be projected from it
>   .SelectFields<ContactDetails>(projectionFields)
>   .ToList();
>
> // Each resulting object in the list is Not a 'Company' entity,
> // it is an object of type 'ContactDetails' containing data ONLY for the specified fields.
> ```
>
> ###### DocumentQuery\_async
>
> ```csharp
> // Define an array with the field names that will be projected
> var projectionFields = new string[]
> {
>   // Fields from 'ContactDetails' class:
>   "Name", "Phone"
> };
>
> // Make a dynamic DocumentQuery
> var projectedResults = await asyncSession.Advanced
>   .AsyncDocumentQuery<Company>()
>   // Call 'SelectFields'
>   // Pass the projection class type & the fields to be projected from it
>   .SelectFields<ContactDetails>(projectionFields)
>   .ToListAsync();
>
> // Each resulting object in the list is Not a 'Company' entity,
> // it is an object of type 'ContactDetails' containing data ONLY for the specified fields.
> ```
>
> ###### Projection\_class
>
> ```csharp
> public class ContactDetails
> {
>   // The projection class contains field names from the 'Company' document
>   public string Name { get; set; }
>   public string Phone { get; set; }
>   public string Fax { get; set; }
> }
> ```
>
> ###### RQL
>
> ```sql
> from "Companies"
> select Name, Phone
> ```

## Single projection per query

- As of RavenDB v6.0, each client-side `Query` or `DocumentQuery` instance can define its projection only once.  
  Projection methods modify the underlying query object by defining the shape of the results,  
  so applying another projection on the **same query instance** will throw an exception.  
  The validation is performed by the client before the query is sent to the server.

- The single-projection rule applies to the client query APIs:

  - Query:  
    Multiple `Select` calls, multiple `ProjectInto` calls, or a combination of `ProjectInto` with `Select`  
    will result in an exception.

  - DocumentQuery:  
    Multiple `SelectFields` calls will result in an exception.

  ### Query

  ```csharp
  // For example:
  try
  {
      var projectedResults = session
          .Query<Company>()
          // Make first projection
          .ProjectInto<ContactDetails>()
          // A second projection is not supported and will throw
          .Select(x => new {Name = x.Name})
          .ToList();
  }
  catch (Exception e)
  {
      // The following exception will be thrown:
      // "Projection is already done. You should not project your result twice."
  }
  ```

  ### DocumentQuery

  ```csharp
  // For example:
  try
  {
      var projectedResults = session.Advanced
          .DocumentQuery<Company>()
          // Make first projection
          .SelectFields<ContactDetails>()
          // A second projection is not supported and will throw
          .SelectFields<ContactDetails>()
          .ToList();
  }
  catch (Exception e)
  {
      // The following exception will be thrown:
      // "Projection is already done. You should not project your result twice."
  }
  ```

---

> **Note**
>
> #### Reusing the same base query for multiple projections
>
> - In the client API, if you need to run the same base query with projections more than once,  
>   keep the unprojected base query as a `DocumentQuery`,  
>   and call `ToQueryable()` before each projection so that each projection is applied to a separate query instance:
>
>   ##### Query
>
>   ```csharp
>   // Build a single base query without a projection
>       
>   var baseQuery = session
>       .Query<Company>()
>       .ToDocumentQuery();
>
>   // Call 'ToQueryable()' before each projection
>       
>   var results1 = baseQuery.ToQueryable()
>       .ProjectInto<ContactDetails>().ToList();
>           
>   var results2 = baseQuery.ToQueryable()
>       .ProjectInto<ContactDetails>().ToList();
>   ```
>
>   ##### Query\_async
>
>   ```csharp
>   // Build a single base query without a projection
>       
>   var baseQuery = asyncSession
>       .Query<Company>()
>       .ToAsyncDocumentQuery();
>
>   // Call 'ToQueryable()' before each projection
>       
>   var results1 = await baseQuery.ToQueryable()
>       .ProjectInto<ContactDetails>().ToListAsync();
>           
>   var results2 = await baseQuery.ToQueryable()
>       .ProjectInto<ContactDetails>().ToListAsync();
>   ```
>
> - In RQL, the projection is part of the query text and is defined by the `select` clause.  
>   To use a different projection, run a separate RQL query with a different `select` clause.

## See also

- [Query Overview](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.md)
- [How to Stream Query Results](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-stream-query-results.md)
- [Querying an index](https://docs.ravendb.net/6.2/indexes/querying/query-index.md)
- [Project index query results](https://docs.ravendb.net/6.2/indexes/querying/projections.md)
- [JavaScript Engine](https://docs.ravendb.net/6.2/server/kb/javascript-engine.md)
