see on GitHub

Session : Loading entities

There are various methods with many overloads that allow user to download a documents from database and convert them to entities. This article will cover following methods:

Load

The most basic way to load single entity is to use one of Load methods.



 TResult Load<TResult>(string id);

Parameters
id string or ValueType Identifier of a document that will be loaded.
Return Value
TResult Instance of TResult or null if document with given Id does not exist.

Example

Employee employee = session.Load<Employee>("employees/1");

Note

In 4.x RavenDB, only string identifiers are supported. If you are upgrading from 3.x, this is a major change, because in 3.x non-string identifiers are supported.

Load with Includes

When there is a 'relationship' between documents, then those documents can be loaded in a single request call using Include + Load methods.

ILoaderWithInclude<object> Include(string path);

ILoaderWithInclude<T> Include<T>(Expression<Func<T, string>> path);

ILoaderWithInclude<T> Include<T>(Expression<Func<T, IEnumerable<string>>> path);

ILoaderWithInclude<T> Include<T, TInclude>(Expression<Func<T, string>> path);

ILoaderWithInclude<T> Include<T, TInclude>(Expression<Func<T, IEnumerable<string>>> path);

Parameters
path string or Expression Path in documents in which server should look for a 'referenced' documents.
Return Value
ILoaderWithInclude Include method by itself does not materialize any requests, but returns loader containing methods such as Load.

Example I

We can use this code to load also an employee which made the order.

// loading 'products/1'
// including document found in 'Supplier' property
Product product = session
    .Include("Supplier")
    .Load<Product>("products/1");

Supplier supplier = session.Load<Supplier>(product.Supplier); // this will not make server call

Example II

// loading 'products/1'
// including document found in 'Supplier' property
Product product = session
    .Include<Product>(x => x.Supplier)
    .Load<Product>("products/1");

Supplier supplier = session.Load<Supplier>(product.Supplier); // this will not make server call

Load - multiple entities

To load multiple entities at once use one of the following Load overloads.

Dictionary<string, TResult> Load<TResult>(IEnumerable<string> ids);

Parameters
ids IEnumerable Multiple document identifiers to load
Return Value
Dictionary<string, TResult> Instance of Dictionary which maps document identifiers to TResult or null if document with given Id does not exist.

Dictionary<string, Employee> employees = session.Load<Employee>(new[] { "employees/1", "employees/2", "employees/3" });

LoadStartingWith

To load multiple entities that contain common prefix use LoadStartingWith method from Advanced session operations.

T[] LoadStartingWith<T>(
          string idPrefix, 
          string matches = null, 
          int start = 0, 
          int pageSize = 25,
    string exclude = null,
    string startAfter = null);

void LoadStartingWithIntoStream(
          string idPrefix, 
          Stream output, 
          string matches = null, 
          int start = 0,
    int pageSize = 25, 
          string exclude = null,
    string startAfter = null);

Parameters
keyPrefix string prefix for which documents should be returned
matches string pipe ('|') separated values for which document keys (after 'keyPrefix') should be matched ('?' any single character, '*' any characters)
start int number of documents that should be skipped
pageSize int maximum number of documents that will be retrieved
exclude string pipe ('|') separated values for which document keys (after 'keyPrefix') should not be matched ('?' any single character, '*' any characters)
skipAfter string skip document fetching until given key is found and return documents after that key (default: null)
Return Value
TResult[] Array of entities matching given parameters.
Stream Output entities matching given parameters as a stream.

Example I

// return up to 128 entities with Id that starts with 'employees'
Employee[] result = session
    .Advanced
    .LoadStartingWith<Employee>("employees", null, 0, 128);

Example II

// return up to 128 entities with Id that starts with 'employees/' 
// and rest of the key begins with "1" or "2" e.g. employees/10, employees/25
Employee[] result = session
    .Advanced
    .LoadStartingWith<Employee>("employees/", "1*|2*", 0, 128);

Stream

Entities can be streamed from server using one of the following Stream methods from Advanced session operations.

IEnumerator<StreamResult<T>> Stream<T>(IQueryable<T> query);

IEnumerator<StreamResult<T>> Stream<T>(IQueryable<T> query, out StreamQueryStatistics streamQueryStats);

IEnumerator<StreamResult<T>> Stream<T>(IDocumentQuery<T> query);

IEnumerator<StreamResult<T>> Stream<T>(IRawDocumentQuery<T> query);

IEnumerator<StreamResult<T>> Stream<T>(IRawDocumentQuery<T> query, out StreamQueryStatistics streamQueryStats);

IEnumerator<StreamResult<T>> Stream<T>(IDocumentQuery<T> query, out StreamQueryStatistics streamQueryStats);

IEnumerator<StreamResult<T>> Stream<T>(string startsWith, string matches = null, int start = 0, int pageSize = int.MaxValue, string startAfter = null);

Parameters
startsWith string prefix for which documents should be streamed (mutually exclusive with 'fromEtag')
matches string pipe ('|') separated values for which document keys (after 'keyPrefix') should be matched ('?' any single character, '*' any characters)
start int number of documents that should be skipped
pageSize int maximum number of documents that will be retrieved
skipAfter string skip document fetching until given key is found and return documents after that key (default: null)
streamQueryStats (out parameter) Information about the streaming query (amount of results, which index was queried, etc.  
Return Value
IEnumerator<StreamResult> Enumerator with entities.
streamQueryStats (out parameter) Information about the streaming query (amount of results, which index was queried, etc.

Example I

Stream documents for a Id prefix

IEnumerator<StreamResult<Employee>> enumerator = session.Advanced.Stream<Employee>("employees/");
while (enumerator.MoveNext())
{
    StreamResult<Employee> employee = enumerator.Current;
}

Example 2

Fetch documents for a Id prefix directly into a stream

using (var outputStream = new MemoryStream())
{
    session.Advanced.LoadStartingWithIntoStream("employees/",outputStream);
}

Remarks

Information

Entities loaded using Stream will be transient (not attached to session).

IsLoaded

To check if entity is attached to session, e.g. has been loaded previously, use IsLoaded method from Advanced session operations.

bool IsLoaded(string id);

Parameters
id string Entity Id for which check should be performed.
Return Value
bool Indicates if entity with given Id is loaded.

Example

bool isLoaded = session.Advanced.IsLoaded("employees/1"); // false
Employee employee = session.Load<Employee>("employees/1");
isLoaded = session.Advanced.IsLoaded("employees/1"); // true