---
title: "Perform a Lazy Query"
url: "https://docs.ravendb.net/6.2/client-api/session/querying/how-to-perform-queries-lazily"
version: "6.2"
language: "python"
---

# Perform a Lazy Query

> Client language: Python. Also available for [C#](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-perform-queries-lazily.md), [Java](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-perform-queries-lazily.java.md), [PHP](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-perform-queries-lazily.php.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-perform-queries-lazily.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**
>
> - Query execution can be deferred: the query can be defined as **Lazy**, and executed
>   at a later time, when its results are actually needed.
>
> - This article contains examples for lazy queries. Prior to reading it, please refer
>   to [perform requests lazily](https://docs.ravendb.net/6.2/client-api/session/how-to/perform-operations-lazily.python.md)
>   for general knowledge about RavenDB's lazy behavior and other request types that can be
>   executed lazily within a session.
>
> - In this page:
>   - [Lazy query](#lazy-query)
>   - [Lazy count query](#lazy-count-query)
>   - [Lazy suggestions query](#lazy-suggestions-query)
>   - [Lazy facets query](#lazy-facets-query)
>   - [Syntax](#syntax)

## Lazy query

To run a [regular query](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.python.md)
(not a [suggestions](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.python.md)
query or a [faceted search](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-perform-a-faceted-search.python.md))
lazily, use `.lazily()` as follows.

```python
# Define a lazy query
lazy_employees = (
  session.query(object_type=Employee).where_equals("first_name", "Robert")
  # Add a call to 'Lazily'
  .lazily()
)

employees = lazy_employees.value  # Query is executed here
```

## Lazy count query

To count query results lazily, use `count_lazily()` as follows.

```python
lazy_count = session.query(object_type=Employee).where_equals("first_name", "Robert").count_lazily()

count = lazy_count.value  # Query is executed here
```

## Lazy suggestions query

To run a suggestions search lazily, use [suggest\_using](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.python.md)
along with `.execute_lazy()` as shown below.

```python
lazy_suggestions = (
  session.query(object_type=Product).suggest_using(lambda builder: builder.by_field("name", "chaig"))
  # Add a call to 'execute_lazy'
  .execute_lazy()
)

suggest = lazy_suggestions.value  # Query is executed here
suggestions = suggest["name"].suggestions
```

## Lazy facets query

To run a faceted query lazily:

- Search a predefined static index (see *Index\_definition* below)
- Aggregate the results using a facets definition (see *Facets\_definition* below)
- Apply `.execute_lazy()` (see *Query* below)

### Query

```python
# Define a lazy facets query
lazy_facets = (
  session.query_index_type(
      Products_ByCategoryAndPrice, Products_ByCategoryAndPrice.IndexEntry
  ).aggregate_by_facets(facets_definition)
  # Add a call to 'execute_lazy'
  .execute_lazy()
)

facets = lazy_facets.value  # Query is executed here

category_results = facets["Product Category"]
price_results = facets["Price per Unit"]
```

### Facets\_definition

```python
# The facets definition used in the facets query
facet = Facet(field_name="CategoryName")
facet.display_field_name = "Product Category"

range_facet = RangeFacet()
range_facet.ranges = [
  "price_per_unit < 200",
  "price_per_unit between 200 and 400",
  "price_per_unit between 400 and 600",
  "price_per_unit between 600 and 800",
  "price_per_unit >= 800",
]
range_facet.display_field_name = "Price per Unit"

facets_definition = [facet, range_facet]

with store.open_session() as session:
  # region lazy_10
  # Define a lazy facets query
  lazy_facets = (
      session.query_index_type(
          Products_ByCategoryAndPrice, Products_ByCategoryAndPrice.IndexEntry
      ).aggregate_by_facets(facets_definition)
      # Add a call to 'execute_lazy'
      .execute_lazy()
  )

  facets = lazy_facets.value  # Query is executed here

  category_results = facets["Product Category"]
  price_results = facets["Price per Unit"]
```

### Index\_definition

```python
# The index definition used in the facets query
class Products_ByCategoryAndPrice(AbstractIndexCreationTask):
  def __init__(self):
      super().__init__()
      self.map = (
          "from p in docs.Products select new {"
          'CategoryName = LoadDocument(p.Category, "Categories").Name, PricePerUnit = p.PricePerUnit'
          "}"
      )

  class IndexEntry:
      def __init__(self, category_name: str, price_per_unit: int):
          self.category_name = category_name
          self.price_per_unit = price_per_unit
```

> **Note**
>
> Learn more about facets in [perform faceted search](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-perform-a-faceted-search.python.md).

## Syntax

```python
# Lazy query
def lazily(self, on_eval: Callable[[List[_T]], None] = None) -> Lazy[List[_T]]: ...
```

```python
# Lazy count query
def count_lazily(self) -> Lazy[int]: ...
```

```python
# Lazy suggestions query
def execute_lazy(
  self, on_eval: Optional[Callable[[Dict[str, SuggestionResult]], None]] = None
) -> "Lazy[Dict[str, SuggestionResult]]": ...
```

```python
# Lazy facet query
def execute_lazy(
  self, on_eval: Optional[Callable[[Dict[str, FacetResult]], None]] = None
) -> Lazy[Dict[str, FacetResult]]: ...
```

| Parameters | Type | Description |
| - | - | - |
| **on\_eval** | `Callable[[List[_T]], None]`<br />`Callable[[Dict[str, SuggestionResult]], None]` (optional)<br />`Callable[[Dict[str, FacetResult]], None]` (optional) | An action that will be performed on the query results when the query is executed. |

| Return Value | |
| - | - |
| `Lazy[List[_T]]`<br />`Lazy[Dict[str, SuggestionResult]]`<br />`Lazy[Dict[str, FacetResult]]` | A lazy instance that will evaluate the query only when needed. |
| `Lazy[int]` | The results of a lazy count query |

## See also

- [Query overview](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.python.md)
- [Perform requests lazily](https://docs.ravendb.net/6.2/client-api/session/how-to/perform-operations-lazily.python.md)
- [Querying: Basics](https://docs.ravendb.net/6.2/indexes/querying/query-index.python.md)
- [query for suggestions](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.python.md)
