Session: Loading Entities

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

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

Example

Employee employee = session.load(Employee.class, "employees/1");

When there is a 'relationship' between documents, those documents can be loaded in a single request call using the include + load methods. Learn more in How To Handle Document Relationships.
See also including counters and including time series.

ILoaderWithInclude include(String path);

<TResult> Map<String, TResult> load(Class<TResult> clazz, String... ids);

<TResult> Map<String, TResult> load(Class<TResult> clazz, Collection<String> ids);

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

Example I

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

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

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

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

<TResult> Map<String, TResult> load(Class<TResult> clazz, String... ids);

<TResult> Map<String, TResult> load(Class<TResult> clazz, Collection<String> ids);

Map<String, Employee> employees
    = session.load(Employee.class,
    "employees/1", "employees/2", "employees/3");

To load multiple entities that contain a common prefix, use the loadStartingWith method from the advanced session operations.

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

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

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

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

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

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

Example I

// return up to 128 entities with Id that starts with 'employees'
Employee[] result = 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);

The conditionalLoad method takes a document's change vector. If the entity is tracked by the session, this method returns the entity. If the entity is not tracked, it checks if the provided change vector matches the document's current change vector on the server side. If they match, the entity is not loaded. If the change vectors do not match, the document is loaded.

In other words, this method can be used to check whether a document has been modified since the last time its change vector was recorded, so that the cost of loading it can be saved if it has not been modified.

The method is accessible from the session.advanced() operations.

<T> ConditionalLoadResult<T> conditionalLoad(Class<T> clazz, String id, String changeVector);

Example

try (IDocumentSession session = store.openSession()) {

    String changeVector;
    User user = new User("Bob");

    session.store(User.class, "users/1");
    session.saveChanges();

    changeVector = session.advanced().getChangeVectorFor(user);
}

User user = new User("Bob");
String changeVector = "a";

try (IDocumentSession session = store.openSession()) {
    // New session which does not track our User entity

    // The given change vector matches
    // the server-side change vector
    // Does not load the document
    ConditionalLoadResult<User> result1 = session.advanced()
        .conditionalLoad(User.class, "users/1", changeVector);

    // Modify the document
    user.setName("Bob Smith");
    session.store(user);
    session.saveChanges();

    // Change vectors do not match
    // Loads the document
    ConditionalLoadResult<User> result2 = session.advanced()
        .conditionalLoad(User.class, "users/1", changeVector);
}

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

<T> CloseableIterator<StreamResult<T>> stream(IDocumentQuery<T> query);

<T> CloseableIterator<StreamResult<T>> stream(IDocumentQuery<T> query, Reference<StreamQueryStatistics> streamQueryStats);

<T> CloseableIterator<StreamResult<T>> stream(IRawDocumentQuery<T> query);

<T> CloseableIterator<StreamResult<T>> stream(IRawDocumentQuery<T> query, Reference<StreamQueryStatistics> streamQueryStats);

<T> CloseableIterator<StreamResult<T>> stream(Class<T> clazz, String startsWith);

<T> CloseableIterator<StreamResult<T>> stream(Class<T> clazz, String startsWith, String matches);

<T> CloseableIterator<StreamResult<T>> stream(Class<T> clazz, String startsWith, String matches, int start);

<T> CloseableIterator<StreamResult<T>> stream(Class<T> clazz, String startsWith, String matches, int start, int pageSize);

<T> CloseableIterator<StreamResult<T>> stream(Class<T> clazz, String startsWith, String matches, int start, int pageSize, String startAfter);

Example I

Stream documents for a ID prefix:

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

Example 2

Fetch documents for a ID prefix directly into a stream:

ByteArrayOutputStream baos = new ByteArrayOutputStream();
session
    .advanced()
    .loadStartingWithIntoStream("employees/", baos);

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.

boolean isLoaded(String id);

Example

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