Session: Loading entities

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

T Load<T>(string id);

T Load<T>(ValueType id);

TResult Load<TResult>(
	string id,
	string transformer,
	Action<ILoadConfiguration> configure);

TResult Load<TResult>(
	string id,
	Type transformerType,
	Action<ILoadConfiguration> configure = null);

TResult Load<TTransformer, TResult>(
	string id,
	Action<ILoadConfiguration> configure = null)
	where TTransformer : AbstractTransformerCreationTask, new();

Example I

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

Example II

// loading 'employees/1'
// and transforming result using 'Employees_NoLastName' transformer
// which returns 'LastName' as 'null'
Employee employee = session.Load<Employees_NoLastName, Employee>("employees/1");

Non string identifiers

The above examples show how to load a document by its string key. What if a type of your entity's identifier is not a string? You need to use an overload of the Load method that takes a parameter which type is ValueType.

Example III

If you have an entity where an identifier is an integer number:

public class EntityWithIntegerId
{
	public int Id { get; set; }
	/*
	...
	*/
}

you can load it by specifying an integer value as the identifier:

EntityWithIntegerId entity = session.Load<EntityWithIntegerId>(1);

Converting to string identifier

Even if the identifier is a string, you can use the Load<T>(ValueType) overload. The client is aware of the ID generation conventions (collectionName/number), so you could load the entity with key employees/1 by using the code:

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

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, object>> path);

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

Example I

// 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

Example II

// 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 III

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

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

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

TResult[] Load<TResult>(IEnumerable<string> ids);

TResult[] Load<TResult>(IEnumerable<ValueType> ids);

TResult[] Load<TResult>(params ValueType[] ids);

TResult[] Load<TResult>(
	IEnumerable<string> ids,
	string transformer,
	Action<ILoadConfiguration> configure = null);

TResult[] Load<TResult>(
	IEnumerable<string> ids,
	Type transformerType,
	Action<ILoadConfiguration> configure = null);

TResult[] Load<TTransformer, TResult>(
	IEnumerable<string> ids,
	Action<ILoadConfiguration> configure = null)
	where TTransformer : AbstractTransformerCreationTask, new();

Example I

Employee[] employees = session.Load<Employee>(new List<string> { "employees/1", "employees/2" });
Employee employee1 = employees[0];
Employee employee2 = employees[1];

Example II

// loading 'employees/1' and 'employees/2'
// and transforming results using 'Employees_NoLastName' transformer
// which returns 'LastName' as 'null'
Employee[] employees = session
	.Load<Employees_NoLastName, Employee>(new List<string> { "employees/1", "employees/2" });
Employee employee1 = employees[0];
Employee employee2 = employees[1];

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

TResult[] LoadStartingWith<TResult>(
	string keyPrefix,
	string matches = null,
	int start = 0,
	int pageSize = 25,
	string exclude = null,
	RavenPagingInformation pagingInformation = null,
	string skipAfter = null);

TResult[] LoadStartingWith<TTransformer, TResult>(
	string keyPrefix,
	string matches = null,
	int start = 0,
	int pageSize = 25,
	string exclude = null,
	RavenPagingInformation pagingInformation = null,
	Action<ILoadConfiguration> configure = null,
	string skipAfter = null);

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);

Example III

// return up to 128 entities with Id that starts with 'employees/' 
// and rest of the Id have length of 3, begins and ends with "1" 
// and contains any character at 2nd position e.g. employees/101, employees/1B1
// and transform results using 'Employees_NoLastName' transformer
Employee[] result = session
	.Advanced
	.LoadStartingWith<Employees_NoLastName, Employee>("employees/", "1?1", 0, 128);

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

IEnumerator<StreamResult<T>> Stream<T>(
	Etag fromEtag,
	int start = 0,
	int pageSize = int.MaxValue,
	RavenPagingInformation pagingInformation = null,
	string skipAfter = null);

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

Example I

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

Remarks

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

If you try to load a document that does not exist with the Load method, IsLoaded will return true because that document load has already been attempted.

bool IsLoaded(string id);

Example

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