---
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: "php"
---

# Perform a Lazy Query

> Client language: PHP. 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), [Python](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-perform-queries-lazily.python.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.php.md)
>   for general knowledge about RavenDB's lazy behavior and other request types that can be
>   executed lazily within a session.
>
> - Learn more about queries in this [query overview](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.php.md).
>
> - In this page:
>   - [Lazy query](#lazy-query)
>   - [Lazy count query](#lazy-count-query)
>   - [Lazy suggestions query](#lazy-suggestions-query)
>   - [Lazy Aggregation](#lazy-aggregation)
>   - [Syntax](#syntax)

## Lazy query

```php
/** @var Lazy<array<Employee>> $employeesLazy */
$employeesLazy = $session
  ->query(Employee::class)
  ->whereEquals("FirstName", "Robert")
  ->lazily();

/** @var array<Employee> $employees */
$employees = $employeesLazy->getValue(); // query will be executed here
```

## Lazy count query

```php
/** @var Lazy<int> $countLazy */
$countLazy = $session
  ->query(Employee::class)
  ->whereEquals("FirstName", "Robert")
  ->countLazily();

/** @var int $count */
$count = $countLazy->getValue(); // query will be executed here
```

## Lazy suggestions query

```php
/** @var Lazy<array<string, SuggestionResult>> $suggestLazy */
$suggestLazy = $session
  ->query(Employee::class, Query::index("Employees_ByFullName"))
  ->suggestUsing(function($builder) { $builder->byField("FullName", "johne"); })
  ->executeLazy();

/** @var array<string, SuggestionResult> $suggest */
$suggest = $suggestLazy->getValue(); // query will be executed here

/** @var array<string> $suggestions */
$suggestions = $suggest["FullName"]->getSuggestions();
```

- Learn more about suggestions in [query for suggestions](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.php.md).

## Lazy aggregation

```php
/** @var Lazy<array<string, FacetResult>> $facetsLazy */
$facetsLazy = $session
  ->query(Camera::class, Query::index("Camera/Costs"))
  ->aggregateUsing("facets/CameraFacets")
  ->executeLazy();

/** @var array<string, FacetResult> $facets */
$facets = $facetsLazy->getValue(); // query will be executed here

/** @var FacetResult $results */
$results = $facets["manufacturer"];
```

## Syntax

```php
/**
* Usage
*   - lazily();
*   - lazily(Closure $onEval)
*/
function lazily(?Closure $onEval = null): Lazy;
```

```php
function countLazily(): Lazy;
```

```php
/**
* Usage
*   - executeLazy();
*   - executeLazy(Closure $onEval)
*/
public function executeLazy(?Closure $onEval = null): Lazy;
```

| Parameter | Type | Description |
| - | - | - |
| **$onEval** | `?Closure` | An action to perform on the query results when the query is executed |

| Return Value | Description |
| - | - |
| `Lazy` | A lazy instance that will evaluate the query only when needed |

## See also

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