Session: Loading Entities

Use the load method to load an entity or multiple entities.

def load(
    self,
    key_or_keys: Union[List[str], str],
    object_type: Optional[Type[_T]] = None,
    includes: Callable[[IncludeBuilder], None] = None,
) -> Union[Dict[str, _T], _T]: ...

Examples

• Load an entiry

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

• Load multiple entities:

  employees = session.load(["employees/1", "employees/2", "employees/3"], Employee)

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.

def include(self, path: str) -> LoaderWithInclude: ...

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
products_by_key = session.include("supplier").load("products/1", Product)
product = products_by_key["products/1"]

supplier = session.load(product.supplier)  # this will not make server call

Example II

# loading 'products/1'
# including document found in 'Supplier' property
products_by_key = session.include("Supplier").load("products/1", Product)
product = products_by_key["products/1"]

supplier = session.load(product.supplier, Supplier)

To load multiple entities with a common prefix, use the advanced session operation load_starting_with.

def load_starting_with(
    self,
    id_prefix: str,
    object_type: Optional[Type[_T]] = None,
    matches: Optional[str] = None,
    start: Optional[int] = None,
    page_size: Optional[int] = None,
    exclude: Optional[str] = None,
    start_after: Optional[str] = None,
) -> List[_T]: ...

Example I

# return up to 128 entities with Id that starts with 'employees'
result = session.advanced.load_starting_with("employees/", Employee, None, 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
result = session.advanced.load_starting_with("employees/", Employee, "1*|2*", 0, 128)

To output multiple entities with a common prefix into a stream, use the advanced session operation load_starting_with_into_stream.

def load_starting_with_into_stream(
    self,
    id_prefix: str,
    matches: str = None,
    start: int = 0,
    page_size: int = 25,
    exclude: str = None,
    start_after: str = None,
) -> bytes: ...

Example

To stream entities from the employees collection, use:

results_bytes = session.advanced.load_starting_with_into_stream("employees/")

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

def conditional_load(
    self, key: str, change_vector: str, object_type: Optional[Type[_T]] = None
) -> ConditionalLoadResult[_T]: ...

Example

change_vector: Optional[str] = None
user = User(name="Bob")

with store.open_session() as session:
    session.store(user, "users/1")
    session.save_changes()

    change_vector = session.advanced.get_change_vector_for(user)

# Now session which does not track our User entity
with store.open_session() as session:
    # The given change vector matches
    # the server-side change vector
    # Does not load the document
    result1 = session.advanced.conditional_load("users/1", change_vector)

    # Modify the document
    user.name = "Bob Smith"
    session.store(user)
    session.save_changes()

    # Change vectors do not natch
    # Loads the document
    result2 = session.advanced.conditional_load("user/1", change_vector)

Use the is_loaded method from the advanced session operations To check if an entity is attached to a session (e.g. because it's been previously loaded).

def is_loaded(self, key: str) -> bool: ...

Example

is_loaded = session.advanced.is_loaded("employees/1")  # False
employee = session.load("employees/1")
is_loaded = session.advanced.is_loaded("employees/1")  # True