You are currently browsing legacy 3.0 version of documentation. Click here to switch to the newest 6.2 version.
    We can help you with migration to the latest RavenDB
    Contact Us Now
    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.

    public <T> T load(Class<T> clazz, String id);

public <T> T load(Class<T> clazz, Number id);

public <T> T load(Class<T> clazz, UUID id);

public <TResult> TResult load(Class<TResult> clazz, String transformer, String id);

public <TResult> TResult load(Class<TResult> clazz, String transformer, String id, LoadConfigurationFactory configure);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult load(Class<TTransformer> tranformerClass,
  Class<TResult> clazz, String id);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult load(Class<TTransformer> tranformerClass,
  Class<TResult> clazz, String id, LoadConfigurationFactory configure);
    Parameters
    id String/UUID/Number Identifier of a document that will be loaded.
    transformer or transformerType String or Class Name or class of a transformer to use on a loaded document.
    configure LoadConfigurationFactory Additional configuration that should be used during operation e.g. transformer parameters can be added.
    Return Value
    TResult Instance of TResult or null if document with given Id does not exist.

    Example I

    Employee employee = session.load(Employee.class, "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.class, Employee.class, "employees/1");

    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.

    public ILoaderWithInclude include(String path);

public ILoaderWithInclude include(Path<?> path);

public ILoaderWithInclude include(Class<?> targetEntityClass, Path<?> path);
    Parameters
    path String or Path 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

    // loading 'products/1'
// including document found in 'supplier' field
QProduct p = QProduct.product;
Product product = session
  .include(p.supplier)
  .load(Product.class, "products/1");

Address supplier = session.load(Address.class, product.getSupplier()); //this will not make server call

    Example II

    // loading 'products/1'
// including document found in 'supplier' field
Product product = session
  .include("Supplier")
  .load(Product.class, "products/1");

Supplier supplier = session.load(Supplier.class, product.getSupplier()); //this will not make server call

    Example III

    // loading 'products/1'
// including document found in 'supplier' field
// transforming loaded product according to Products_Transformer
Product product = session
    .include("Supplier")
    .load(Products_Transformer.class, Product.class, "products/1", null);

Supplier supplier = session.load(Supplier.class, product.getSupplier()); //this will not make server call

    Load - multiple entities

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

    public <T> T[] load(Class<T> clazz, String...ids);

public <T> T[] load(Class<T> clazz, Collection<String> ids);

public <T> T[] load(Class<T> clazz, Number... ids);

public <T> T[] load(Class<T> clazz, UUID... ids);

public <TResult> TResult[] load(Class<TResult> clazz, String transformer, Collection<String> ids);

public <TResult> TResult[] load(Class<TResult> clazz, String transformer, Collection<String> ids, LoadConfigurationFactory configure);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] load(Class<TTransformer> tranformerClass,
  Class<TResult> clazz, String... ids);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] load(Class<TTransformer> tranformerClass,
  Class<TResult> clazz, List<String> ids, LoadConfigurationFactory configure);
    Parameters
    ids Collection<String>, String[], UUID[], Number[] Iterable or array of ids that should be loaded.
    transformer or transformerType String or Class Name or class of a transformer to use on a loaded documents.
    configure LoadConfigurationFactory Additional configuration that should be used during operation e.g. transformer parameters can be added.
    Return Value
    TResult[] Array of entities in the exact same order as given ids. If document does not exist, value at the appropriate position in array will be null.

    Example I

    Employee[] employees = session.load(Employee.class, Arrays.asList("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.class, Employee.class, "employees/1", "employees/2");
Employee employee1 = employees[0];
Employee employee2 = employees[1];

    LoadStartingWith

    To load multiple entities that contain common prefix use loadStartingWith method from advanced() session operations.

    public <T> T[] loadStartingWith(Class<T> clazz, String keyPrefix);

public <T> T[] loadStartingWith(Class<T> clazz, String keyPrefix, String matches);

public <T> T[] loadStartingWith(Class<T> clazz, String keyPrefix, String matches, int start);

public <T> T[] loadStartingWith(Class<T> clazz, String keyPrefix, String matches, int start, int pageSize);

public <T> T[] loadStartingWith(Class<T> clazz, String keyPrefix, String matches, int start, int pageSize, String exclude);

public <T> T[] loadStartingWith(Class<T> clazz, String keyPrefix, String matches, int start, int pageSize, String exclude, RavenPagingInformation pagingInformation);

public <T> T[] loadStartingWith(Class<T> clazz, String keyPrefix, String matches, int start, int pageSize, String exclude, RavenPagingInformation pagingInformation, String skipAfter);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] loadStartingWith(Class<TResult> clazz, Class<TTransformer> transformerClass,
  String keyPrefix);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] loadStartingWith(Class<TResult> clazz, Class<TTransformer> transformerClass,
  String keyPrefix, String matches);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] loadStartingWith(Class<TResult> clazz, Class<TTransformer> transformerClass,
  String keyPrefix, String matches, int start);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] loadStartingWith(Class<TResult> clazz, Class<TTransformer> transformerClass,
  String keyPrefix, String matches, int start, int pageSize);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] loadStartingWith(Class<TResult> clazz, Class<TTransformer> transformerClass,
  String keyPrefix, String matches, int start, int pageSize, String exclude);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] loadStartingWith(Class<TResult> clazz, Class<TTransformer> transformerClass,
  String keyPrefix, String matches, int start, int pageSize, String exclude,
  RavenPagingInformation pagingInformation);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] loadStartingWith(Class<TResult> clazz, Class<TTransformer> transformerClass,
  String keyPrefix, String matches, int start, int pageSize, String exclude,
  RavenPagingInformation pagingInformation, LoadConfigurationFactory configure);

public <TResult, TTransformer extends AbstractTransformerCreationTask> TResult[] loadStartingWith(Class<TResult> clazz, Class<TTransformer> transformerClass,
  String keyPrefix, String matches, int start, int pageSize, String exclude,
  RavenPagingInformation pagingInformation, LoadConfigurationFactory configure, String skipAfter);
    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). Default: null
    start int number of documents that should be skipped. Default: 0
    pageSize int maximum number of documents that will be retrieved. Default: 25
    pagingInformation RavenPagingInformation used to perform rapid pagination on server side. Default: null
    exclude String pipe ('|') separated values for which document keys (after 'keyPrefix') should not be matched ('?' any single character, '*' any characters). Default: null
    configure LoadConfigurationFactory Additional configuration that should be used during operation e.g. transformer parameters can be added. Default: null
    Return Value
    TResult[] Array of entities matching given parameters.

    Example I

    // return up to 128 entities with id that starts with 'employees'
session.advanced().loadStartingWith(Employee.class, "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.class, "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
session.advanced().loadStartingWith(Employee.class, Employees_NoLastName.class, "employees/", "1?1", 0, 128);

    Stream

    Entities can be streamed from server using one of the following stream methods from advanced() session operations.

    public <T> CloseableIterator<StreamResult<T>> stream(Class<T> entityClass);

public <T> CloseableIterator<StreamResult<T>> stream(Class<T> entityClass, Etag fromEtag);

public <T> CloseableIterator<StreamResult<T>> stream(Class<T> entityClass, Etag fromEtag, String startsWith);

public <T> CloseableIterator<StreamResult<T>> stream(Class<T> entityClass, Etag fromEtag, String startsWith, String matches);

public <T> CloseableIterator<StreamResult<T>> stream(Class<T> entityClass, Etag fromEtag, String startsWith, String matches, int start);

public <T> CloseableIterator<StreamResult<T>> stream(Class<T> entityClass, Etag fromEtag, String startsWith, String matches, int start, int pageSize);

public <T> CloseableIterator<StreamResult<T>> stream(Class<T> entityClass, Etag fromEtag, String startsWith, String matches, int start, int pageSize, RavenPagingInformation pagingInformation);

public <T> CloseableIterator<StreamResult<T>> stream(Class<T> entityClass, Etag fromEtag, String startsWith, String matches, int start, int pageSize, RavenPagingInformation pagingInformation, String skipAfter);
    Parameters
    fromEtag Etag ETag of a document from which stream should start (mutually exclusive with 'startsWith')
    startsWith String prefix for which documents should be streamed (mutually exclusive with 'fromEtag'). Default: null
    matches String pipe ('|') separated values for which document keys (after 'keyPrefix') should be matched ('?' any single character, '*' any characters). Default: null
    start int number of documents that should be skipped. Default: 0
    pageSize int maximum number of documents that will be retrieved. Default: Integer.MAX_VALUE
    pagingInformation RavenPagingInformation used to perform rapid pagination on server side. Default: null
    Return Value
    CloseableIterator<StreamResult<T>> Enumerator with entities.

    Example I

    CloseableIterator<StreamResult<Employee>> iterator = session.advanced().stream(Employee.class, null, "employees/");
while (iterator.hasNext()) {
  StreamResult<Employee> employee = iterator.next();
}

    Remarks

    Information

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

    Caution

    fromEtag does not do any filtrations on server-side based on the specified in streaming function return type (e.g. Employee) and will return all documents from given Etag even if their Raven-Clr-Type does not match the return type, which may cause potential casting errors. Set return type to Object or RavenJObject to address situation when documents with different types might be returned.

    IsLoaded

    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. 

    public boolean isLoaded(String id);
    Parameters
    id String Entity Id for which check should be performed.
    Return Value
    boolean Indicates if entity with given Id is loaded.

    Example

    boolean isLoaded = session.advanced().isLoaded("employees/1"); //false
Employee employee = session.load(Employee.class, "employees/1");
isLoaded = session.advanced().isLoaded("employees/1"); //true

    related articlesRelated Articles

    Home / Docs / Client Api / Session / Loading Entities