Session: Loading Entities

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

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

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

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

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.

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

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

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

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

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

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