---
title: "Session: Loading Entities"
url: "https://docs.ravendb.net/6.2/client-api/session/loading-entities"
version: "6.2"
language: "python"
---

# Session: Loading Entities

> Client language: Python. Also available for [C#](https://docs.ravendb.net/6.2/client-api/session/loading-entities.md), [Java](https://docs.ravendb.net/6.2/client-api/session/loading-entities.java.md), [PHP](https://docs.ravendb.net/6.2/client-api/session/loading-entities.php.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/loading-entities.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - There are several methods that allow users to load documents from the database and convert them to entities.
>
> - This article covers the following methods:
>
>   - [load](#load)
>   - [load with includes](#load-with-includes)
>   - [load\_starting\_with](#load_starting_with)
>   - [load\_starting\_with\_into\_stream](#load_starting_with_into_stream)
>   - [conditional\_load](#conditional_load)
>   - [stream](#stream)
>   - [is\_loaded](#is_loaded)
>
> - For loading entities lazily see [perform requests lazily](https://docs.ravendb.net/6.2/client-api/session/how-to/perform-operations-lazily.python.md).
>
> > **Warning**
> >
> > From RavenDB version 4.x onward, only string identifiers are supported.  
> > If you are upgrading from 3.x, this is a major change, because in 3.x non-string identifiers are supported as well.

## load

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

```python
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]: ...
```

| Parameter | Type | Description |
| - | - | - |
| **key\_or\_keys** | `str` or `List[str]` | Identifier or a list of identifiers of entities to load |
| **object\_type**<br />(optional) | `[Type[_T]` | Entity type to load (optional) |
| **includes**<br />(optional) | `Callable[[IncludeBuilder], None]` | A **consumer function** that takes an [include builder](https://docs.ravendb.net/6.2/client-api/how-to/handle-document-relationships.md#includes) argument.<br />The user should use the builder inside this function to *include* all the data needed within a load. |

| Return Type | Description |
| - | - |
| `_T` | If a single document was requested, return an instance of the document or `None` if no document was found |
| `Dict[str, _T]` | If multiple documents were requested, return a dictionary of document instances or `None` if no documents were found |

### Examples

- Load an entiry

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

- Load multiple entities:

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

## load with includes

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](https://docs.ravendb.net/6.2/client-api/how-to/handle-document-relationships.md).

> **Note**
>
> Also see:
>
> - [Including Counters](https://docs.ravendb.net/6.2/document-extensions/counters/counters-and-other-features.python.md#including-counters)
> - [Including Time Series](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/session/include/overview.md)
> - [Including Compare Exchange Values](https://docs.ravendb.net/6.2/client-api/operations/compare-exchange/include-compare-exchange.md)
> - [Including Document Revisions](https://docs.ravendb.net/6.2/document-extensions/revisions/client-api/session/including.md)

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

| Parameter | Type | Description |
| - | - | - |
| **path** | `str` | Search path that the server will use to look for the 'referenced' documents |

| Return Type | Description |
| - | - |
| `LoaderWithInclude` | The ` include` method by itself does not materialize any requests but returns loader containing methods such as `load`. |

### Example I

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

```python
# 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

```python
# 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)
```

## load\_starting\_with

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

```python
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]: ...
```

| Parameter | Type | Description |
| - | - | - |
| **id\_prefix** | `str` | Prefix to return the documents to |
| **object\_type**<br />(optional) | `Type[_T]` | The object type |
| **matches**<br /> | `str` | Pipe ('\|') separated values for which document IDs (after 'id\_prefix') should be matched ('?' any single character, '\*' any characters) |
| **start**<br />(optional) | `int` | Number of documents that should be skipped |
| **page\_size**<br />(optional) | `int` | Maximum number of documents that will be retrieved |
| **exclude**<br />(optional) | `str` | Pipe ('\|') separated values for which document IDs (after 'id\_prefix') should **not** be matched ('?' any single character, '\*' any characters) |
| **start\_after**<br />(optional) | `str` | Skip document fetching until given ID is found and return documents after that ID (default: `None`) |

| Return Type | Description |
| - | - |
| `List[_T]` | An array of entities matching the given parameters |

### Example I

```python
# return up to 128 entities with Id that starts with 'employees'
result = session.advanced.load_starting_with("employees/", Employee, None, 0, 128)
```

### Example II

```python
# 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)
```

## load\_starting\_with\_into\_stream

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

```python
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: ...
```

| Parameter | Type | Description |
| - | - | - |
| **id\_prefix** | `str` | Prefix to return the documents to |
| **matches**<br /> | `str` | Pipe ('\|') separated values for which document IDs (after 'id\_prefix') should be matched ('?' any single character, '\*' any characters) |
| **start** | `int` | Number of documents that should be skipped |
| **page\_size** | `int` | Maximum number of documents that will be retrieved |
| **exclude** | `str` | Pipe ('\|') separated values for which document IDs (after 'id\_prefix') should **not** be matched ('?' any single character, '\*' any characters) |
| **start\_after** | `str` | Skip document fetching until given ID is found and return documents after that ID (default: `None`) |

| Return Type | Description |
| - | - |
| `bytes` | The retrieved entities, returned as a stream of bytes |

### Example

To stream entities from the `employees` collection, use:

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

## conditional\_load

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](https://docs.ravendb.net/6.2/server/clustering/replication/change-vector.md).
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.

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

| Parameter | Type | Description |
| - | - | - |
| **key** | `str` | The identifier of a document to be loaded |
| **change\_vector** | `str` | The change vector you want to compare with the server-side change vector. If the change vectors match, the document is not loaded. |
| **object\_type**<br />(optional) | `Type[_T]` | Object type |

| Return Type | Description |
| - | - |
| `ConditionalLoadResult[_T]` | If the given change vector and the server side change vector do not match, the method returns the requested entity and its current change vector. <br /> If the change vectors match, the method returns `default` as the entity, and the current change vector. <br /> If the specified document, the method returns only `default` without a change vector. |

### Example

```python
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)
```

\<!--

## stream

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

Streaming query results does not support the [`include` feature](https://docs.ravendb.net/6.2/client-api/how-to/handle-document-relationships.md#includes).
Learn more in [How to Stream Query Results](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-stream-query-results.md).

> **Info**
>
> Entities loaded using `stream` will be transient (not attached to session).

```python
# waiting for merge, will be supported from 5.4 client release (https://pypi.org/project/ravendb/)
```

| Parameter | Type | Description |
| - | - | - |
| **starts\_with** | `str` | prefix for which documents should be streamed |
| **matches** | `str` | pipe ('\|') separated values for which document IDs should be matched ('?' any single character, '\*' any characters) |
| **start** | `int` | number of documents that should be skipped |
| **page\_size** | `int` | maximum number of documents that will be retrieved |
| **start\_after** | `str` | skip document fetching until a given ID is found and returns documents after that ID (default: `None`) |
| **stream\_query\_stats** | `streamQueryStats` (out parameter) | Information about the streaming query (amount of results, which index was queried, etc.) |

| Return Type | Description |
| - | - |
| `IEnumerator<`[StreamResult](https://docs.ravendb.net/6.2/glossary/stream-result.md)`>` | Enumerator with entities. |
| `streamQueryStats` (out parameter) | Information about the streaming query (amount of results, which index was queried, etc.) |

### Example I

Stream documents for a ID prefix:

```python
# unsupported, will be supported from 5.4 client release (https://pypi.org/project/ravendb/)
```

## Example 2

Fetch documents for a ID prefix directly into a stream:

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

\-->

## is\_loaded

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

> **Note**
>
> `is_loaded` checks if an attempt to load a document has been already made
> during the current session, and returns `True` even if such an attemp was
> made and failed.  
> If, for example, the `load` method was used to load `employees/3` during
> this session and failed because the document has been previously deleted,
> `is_loaded` will still return `True` for `employees/3` for the remainder
> of the session just because of the attempt to load it.

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

| Parameter | Type | Description |
| - | - | - |
| **key** | `str` | ID of the entity whose status is checked |

| Return Type | Description |
| - | - |
| `bool` | Indicates if the given entity is loaded |

### Example

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

## See also

- [What is a Session and How Does it Work](https://docs.ravendb.net/6.2/client-api/session/what-is-a-session-and-how-does-it-work.python.md)
- [Opening a Session](https://docs.ravendb.net/6.2/client-api/session/opening-a-session.python.md)
- [Deleting Entities](https://docs.ravendb.net/6.2/client-api/session/deleting-entities.python.md)
- [Saving Changes](https://docs.ravendb.net/6.2/client-api/session/saving-changes.python.md)
- [Query Overview](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.python.md)
- [Querying an Index](https://docs.ravendb.net/6.2/indexes/querying/query-index.python.md)
- [What is a Document Store](https://docs.ravendb.net/6.2/client-api/what-is-a-document-store.md)
