Perform a Lazy Query

Query execution can be deferred: the query can be defined as Lazy, and executed at a later time, when its results are actually needed.
This article contains examples for lazy queries. Prior to reading it, please refer to perform requests lazily for general knowledge about RavenDB's lazy behavior and other request types that can be executed lazily within a session.
In this page:

Lazy query

Lazy_query
Lazy_query_async
Lazy_documentQuery

// Define a lazy query
Lazy<IEnumerable<Employee>> lazyEmployees = session
  .Query<Employee>()
  .Where(x => x.FirstName == "Robert")
   // Add a call to 'Lazily'
  .Lazily();

IEnumerable<Employee> employees = lazyEmployees.Value; // Query is executed here

// Define a lazy query
Lazy<Task<IEnumerable<Employee>>> lazyEmployees = asyncSession
  .Query<Employee>()
  .Where(x => x.FirstName == "Robert")
   // Add a call to 'LazilyAsync'
  .LazilyAsync();

IEnumerable<Employee> employees = await lazyEmployees.Value; // Query is executed here

// Define a lazy DocumentQuery
Lazy<IEnumerable<Employee>> lazyEmployees = session.Advanced
  .DocumentQuery<Employee>()
  .WhereEquals(x => x.FirstName, "Robert")
   // Add a call to 'Lazily'
  .Lazily();

IEnumerable<Employee> employees = lazyEmployees.Value; // DocumentQuery is executed here

Learn more about queries in this query overview.

Lazy count query

Lazy_query
Lazy_query_async
Lazy_documentQuery

// Define a lazy count query
Lazy<int> lazyCount = session
  .Query<Employee>()
  .Where(x => x.FirstName == "Robert")
   // Add a call to 'CountLazily'
  .CountLazily();

int count = lazyCount.Value; // Query is executed here

// Define a lazy count query
Lazy<Task<int>> lazyCount = asyncSession
  .Query<Employee>()
  .Where(x => x.FirstName == "Robert")
   // Add a call to 'CountLazilyAsync'
  .CountLazilyAsync();

int count = await lazyCount.Value; // Query is executed here

// Define a lazy DocumentQuery
Lazy<int> lazyCount = session.Advanced
  .DocumentQuery<Employee>()
  .WhereEquals(x => x.FirstName, "Robert")
   // Add a call to 'CountLazily'
  .CountLazily();

int count = lazyCount.Value; // DocumentQuery is executed here

Lazy suggestions query

Lazy_query
Lazy_query_async
Lazy_documentQuery

// Define a lazy suggestion query
Lazy<Dictionary<string, SuggestionResult>> lazySuggestions = session
  .Query<Product>()
  .SuggestUsing(builder => builder.ByField(x => x.Name, "chaig"))
   // Add a call to 'ExecuteLazy'
  .ExecuteLazy();

Dictionary<string, SuggestionResult> suggest = lazySuggestions.Value; // Query is executed here
List<string> suggestions = suggest["Name"].Suggestions;

// Define a lazy suggestion query
Lazy<Task<Dictionary<string, SuggestionResult>>> lazySuggestions = asyncSession
  .Query<Employee>()
  .SuggestUsing(builder => builder.ByField("Name", "chaig"))
   // Add a call to 'ExecuteLazyAsync'
  .ExecuteLazyAsync();

Dictionary<string, SuggestionResult> suggest = await lazySuggestions.Value; // Query is executed here
List<string> suggestions = suggest["Name"].Suggestions;

// Define a lazy DocumentQuery
Lazy<Dictionary<string, SuggestionResult>> lazySuggestions = session.Advanced
  .DocumentQuery<Employee>()
  .SuggestUsing(builder => builder.ByField("Name", "chaig"))
   // Add a call to 'ExecuteLazy'
  .ExecuteLazy();

Dictionary<string, SuggestionResult> suggest = lazySuggestions.Value; // DocumentQuery is executed here
List<string> suggestions = suggest["FullName"].Suggestions;

Learn more about suggestions in query for suggestions.

Lazy_query
Lazy_query_async
Lazy_documentQuery
Facets_definition
Index_definition

// Define a lazy facets query
Lazy<Dictionary<string, FacetResult>> lazyFacets = session
  .Query<Product, Products_ByCategoryAndPrice>()
  .AggregateBy(facetsDefinition)
   // Add a call to 'ExecuteLazy'
  .ExecuteLazy();

Dictionary<string, FacetResult> facets = lazyFacets.Value; // Query is executed here

FacetResult categoryResults = facets["Product Category"];
FacetResult priceResults = facets["Price per Unit"];

// Define a lazy DocumentQuery
Lazy<Task<Dictionary<string,FacetResult>>> lazyFacets = asyncSession
  .Query<Product, Products_ByCategoryAndPrice>()
  .AggregateBy(facetsDefinition)
   // Add a call to 'ExecuteLazyAsync'
  .ExecuteLazyAsync();

Dictionary<string, FacetResult> facets = await lazyFacets.Value; // Query is executed here

FacetResult categoryResults = facets["Product Category"];
FacetResult priceResults = facets["Price per Unit"];

// Define a lazy DocumentQuery
Lazy<Dictionary<string, FacetResult>> lazyFacets = session.Advanced
  .DocumentQuery<Product, Products_ByCategoryAndPrice>()
  .AggregateBy(facetsDefinition)
   // Add a call to 'ExecuteLazy'
  .ExecuteLazy();

Dictionary<string, FacetResult> facets = lazyFacets.Value; //  DocumentQuery is executed here

FacetResult categoryResults = facets["Product Category"];
FacetResult priceResults = facets["Price per Unit"];

// The facets definition used in the facets query:
List<FacetBase> facetsDefinition = new List<FacetBase>
{
  new Facet
  {
      FieldName = "CategoryName",
      DisplayFieldName = "Product Category"
  },
  new RangeFacet<Product>
  {
      Ranges =
      {
          product => product.PricePerUnit < 25,
          product => product.PricePerUnit >= 25 && product.PricePerUnit < 50,
          product => product.PricePerUnit >= 50 && product.PricePerUnit < 100,
          product => product.PricePerUnit >= 100
      },
      DisplayFieldName = "Price per Unit"
  }
};

// The index definition used in the facets query:
public class Products_ByCategoryAndPrice :
  AbstractIndexCreationTask<Product, Products_ByCategoryAndPrice.IndexEntry>
{
  // The IndexEntry class defines the index-fields
  public class IndexEntry
  {
      public string CategoryName { get; set; }
      public decimal PricePerUnit { get; set; }
  }
      
  public Products_ByCategoryAndPrice()
  {
      // The 'Map' function defines the content of the index-fields
      Map = products => from product in products
          select new IndexEntry
          {
              CategoryName = LoadDocument<Category>(product.Category).Name,
              PricePerUnit = product.PricePerUnit
          };
  }
}

Learn more about facets in perform faceted search.

Syntax

// Lazy query overloads:
Lazy<IEnumerable<T>> Lazily<T>();
Lazy<IEnumerable<T>> Lazily<T>(Action<IEnumerable<T>> onEval);

Lazy<Task<IEnumerable<T>>> LazilyAsync<T>();
Lazy<Task<IEnumerable<T>>> LazilyAsync<T>(Action<IEnumerable<T>> onEval);

// Lazy count query overloads:
Lazy<int> CountLazily<T>();
Lazy<long> LongCountLazily<T>();

Lazy<Task<int>> CountLazilyAsync<T>(CancellationToken token = default(CancellationToken));
Lazy<Task<long>> LongCountLazilyAsync<T>(CancellationToken token = default(CancellationToken));

// Lazy suggestions query overloads:
Lazy<Dictionary<string, SuggestionResult>>
  ExecuteLazy(Action<Dictionary<string, SuggestionResult>> onEval = null);

Lazy<Task<Dictionary<string, SuggestionResult>>>
  ExecuteLazyAsync(Action<Dictionary<string, SuggestionResult>> onEval = null,
      CancellationToken token = default);

// Lazy facets query overloads:
Lazy<Dictionary<string, FacetResult>>
  ExecuteLazy(Action<Dictionary<string, FacetResult>> onEval = null);

Lazy<Task<Dictionary<string, FacetResult>>>
  ExecuteLazyAsync(Action<Dictionary<string, FacetResult>> onEval = null,
      CancellationToken token = default);

Parameters	Type	Description
onEval	`Action<IEnumerable<TResult>>` `Action<Dictionary<string, SuggestionResult>>` `Action<Dictionary<string, FacetResult>>`	An action that will be performed on the query results when the query is executed.

Return Value
`Lazy<IEnumerable<TResult>>` `Lazy<int>` `Lazy<Dictionary<string, SuggestionResult>>` `Lazy<Dictionary<string, FacetResult>>`	A lazy instance that will evaluate the query only when needed.

Lazy query​

Lazy count query​

Lazy suggestions query​

Lazy facets query​

Syntax​

Lazy query

Lazy count query

Lazy suggestions query

Lazy facets query

Syntax