Session: Loading Entities

The most basic way to load a single entity is to use session's load() method.

await session.load(id, [documentType]);

Example

const employee = await session.load("employees/1");

When there is a relationship between documents, those documents can be loaded in a single request call using the include() and load() methods.

session.include(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
const product = await session
    .include("supplier")
    .load("products/1");

const supplier = await session.load(product.supplier); // this will *not* make a server call

To load multiple entities at once, use one of the following ways to call load().

await session.load(idsArray, [documentType]);
await session.load(idsArray, [options]);

const employees = await session.load(
    ["employees/1", "employees/2", "employees/3"]);
// {
//     "employees/1": { ... },
//     "employees/2": { ... }
//     "employees/3": { ... }
// }

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

await session.advanced.loadStartingWith(idPrefix, [options]);

await session.advanced.loadStartingWithIntoStream(idPrefix, output, [options]);

Example I

// return up to 128 entities with Id that starts with 'employees'
const result = await session
    .advanced
    .loadStartingWith("employees/", {
        start: 0,
        pageSize: 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
const result = await session
    .advanced
    .loadStartingWith("employees/", {
        matches: "1*|2*",
        start: 0,
        pageSize: 128
    });

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

The method is accessible from the session.Advanced operations.

await session.advanced.conditionalLoad(id, changeVector, clazz);

Example

const session = store.openSession();
const user = new User("Bob");
await session.store(user, "users/1");
await session.saveChanges();

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

{
    // New session which does not track our User entity
    // The given change vector matches
    // the server-side change vector
    // Does not load the document
    const session = store.openSession();
    const result1 = await session.advanced
        .conditionalLoad("users/1", changeVector, User);

    // Modify the document
    user.name = "Bob Smith";
    await session.store(user);
    await session.saveChanges();

    // Change vectors do not match
    // Loads the document
    const result2 = await session.advanced
        .conditionalLoad("users/1", changeVector, User);

Entities can be streamed from the server using the stream() method from the advanced session operations.

// stream query results
await session.stream(query, [statsCallback]);

// stream documents with ID starting with
await session.stream(idPrefix, [options]);

Example I

Stream documents for a ID prefix:

// stream() returns a Node.js Readable
const stream = await session.advanced.stream("employees/");

stream.on("data", data => {
    // Employee { name: 'Anna', id: 'employees/1-A' }
});

stream.on("error", err => {
    // handle errors
});

stream.on("end", () => {
    // stream ended
});

Example 2

Fetch documents for a ID prefix directly into a writable stream:

const employeesFile = fs.createWriteStream("employees.json");
await session.advanced.loadStartingWithIntoStream("employees/", employeesFile);

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.

session.advanced.isLoaded(id);

Example

session.advanced.isLoaded("employees/1"); // false
const employee = await session.load("employees/1");
session.advanced.isLoaded("employees/1"); // true