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.

ILoaderWithInclude include(String path);

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

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