Cursor implements IteratorAggregate, Countable
Iterator over the result of an AQL query.
Wraps the initial response returned by POST /_api/cursor and
automatically fetches subsequent batches (POST /_api/cursor/{id})
as the caller iterates through the results. The cursor is lazy:
a new batch is only fetched when the previous one has been fully
consumed.
Implements IteratorAggregate (yields each row exactly once during a
single pass — the underlying server-side cursor is not rewindable)
and Countable (returns the server-side total when the query was
created with the count: true option).
Example:
$cursor = $db->query
(
aql( 'FOR u IN users FILTER u.active == ? RETURN u' , true ) ,
options : [ 'count' => true ] ,
) ;
foreach ( $cursor as $user )
{
// ...
}
echo count( $cursor ) ; // server-side total
Tags
Table of Contents
Interfaces
- IteratorAggregate
- Countable
Properties
- $database : Database
- $batch : array<int, mixed>
- Current batch of rows (replaced on every fetched batch).
- $cursorId : string|null
- Server-side cursor identifier when more batches are available, null otherwise.
- $extra : array<string, mixed>
- Extra metadata (warnings, stats, profile, …) — overwritten on every fetched batch.
- $hasMore : bool
- Whether more batches remain to be fetched from the server.
- $totalCount : int|null
- Total count of result rows on the server, or null when the query was not created with `count: true`.
Methods
- __construct() : mixed
- all() : array<int, mixed>
- Eagerly fetches every remaining batch and returns the full result set.
- close() : void
- Closes the server-side cursor immediately (releases its resources).
- count() : int
- Returns the server-side total count of result rows.
- flatMap() : array<int, mixed>
- Depletes the cursor by applying `$callback` to each remaining row and concatenating the results into a single flat array.
- forEach() : bool
- Depletes the cursor by applying `$callback` to each remaining row.
- getExtra() : array<string, mixed>
- Returns the extra metadata sent by the server with the most recent batch (warnings, stats, profile, …).
- getFullCount() : int
- Returns the total number of result rows that would have been returned had the query been executed without a LIMIT clause.
- getId() : string|null
- Returns the server-side cursor identifier, or null when no further batch can be fetched.
- getIterator() : Generator<int, mixed>
- Lazy generator: yields each result row exactly once, fetching subsequent batches from the server as needed.
- hasMore() : bool
- Returns true when more batches remain to be fetched from the server.
- map() : Generator<int, mixed>
- Lazily transforms each row through `$callback` and yields the results one at a time.
- reduce() : mixed
- Depletes the cursor by folding it through `$reducer`, returning the accumulated value.
- fetchNextBatch() : void
- Fetches the next batch from the server and updates the internal state.
Properties
$database
public
Database
$database
$batch
Current batch of rows (replaced on every fetched batch).
private
array<int, mixed>
$batch
$cursorId
Server-side cursor identifier when more batches are available, null otherwise.
private
string|null
$cursorId
$extra
Extra metadata (warnings, stats, profile, …) — overwritten on every fetched batch.
private
array<string, mixed>
$extra
$hasMore
Whether more batches remain to be fetched from the server.
private
bool
$hasMore
$totalCount
Total count of result rows on the server, or null when the query was not created with `count: true`.
private
int|null
$totalCount
Methods
__construct()
public
__construct(Database $database, array<string, mixed> $initialResponse) : mixed
Parameters
- $database : Database
-
Parent database (used to fetch subsequent batches and to close the server-side cursor).
- $initialResponse : array<string, mixed>
-
Decoded body of the initial
POST /_api/cursorresponse.
all()
Eagerly fetches every remaining batch and returns the full result set.
public
all() : array<int, mixed>
Use this for small result sets where streaming is overkill — for
large queries prefer iterating with foreach.
Tags
Return values
array<int, mixed>close()
Closes the server-side cursor immediately (releases its resources).
public
close() : void
Implicit on the last batch — the server cleans up the cursor once it has been fully consumed — so this is only necessary when the caller wants to abandon iteration early.
Tags
count()
Returns the server-side total count of result rows.
public
count() : int
Only available when the query was created with the count: true
option; otherwise throws.
Tags
Return values
intflatMap()
Depletes the cursor by applying `$callback` to each remaining row and concatenating the results into a single flat array.
public
flatMap(callable(mixed, int, self): Array $callback) : array<int, mixed>
The callback receives (mixed $row, int $index, self $cursor)
and may return either a single value (appended to the result) or
an array (spread one level deep into the result). Mirrors
Array.prototype.flatMap() semantics.
Use this to combine a map() and a one-level array_merge() in
one streaming pass — the alternative
(array_merge(...iterator_to_array($cursor->map(...)))) requires
materialising the whole cursor first.
Parameters
- $callback : callable(mixed, int, self): Array
-
Per-row transformation.
Tags
Return values
array<int, mixed> —Flattened result.
forEach()
Depletes the cursor by applying `$callback` to each remaining row.
public
forEach(callable(mixed, int, self): Array $callback) : bool
The callback receives (mixed $row, int $index, self $cursor).
Return false from the callback to abort iteration early —
forEach() then returns false to signal a short-circuit;
otherwise it returns true once the cursor is empty.
Parameters
- $callback : callable(mixed, int, self): Array
-
Per-row callback.
Tags
Return values
bool —true when the cursor was fully consumed, false when the callback returned false and aborted iteration.
getExtra()
Returns the extra metadata sent by the server with the most recent batch (warnings, stats, profile, …).
public
getExtra() : array<string, mixed>
Return values
array<string, mixed>getFullCount()
Returns the total number of result rows that would have been returned had the query been executed without a LIMIT clause.
public
getFullCount() : int
Available only when the request was issued with the fullCount
option set to true — returns 0 otherwise.
Return values
intgetId()
Returns the server-side cursor identifier, or null when no further batch can be fetched.
public
getId() : string|null
Return values
string|nullgetIterator()
Lazy generator: yields each result row exactly once, fetching subsequent batches from the server as needed.
public
getIterator() : Generator<int, mixed>
Tags
Return values
Generator<int, mixed>hasMore()
Returns true when more batches remain to be fetched from the server.
public
hasMore() : bool
Return values
boolmap()
Lazily transforms each row through `$callback` and yields the results one at a time.
public
map(callable(mixed, int, self): mixed $callback) : Generator<int, mixed>
The callback receives (mixed $row, int $index, self $cursor)
and returns the transformed value. The returned Generator
is lazy: nothing is computed until the caller starts iterating,
and batches are pulled from the server only on demand.
Use this to build a streaming pipeline without buffering the
whole cursor in memory. For an eager transformation, materialise
the generator with iterator_to_array(...) — or use
flatMap() when each row produces multiple output values.
Example:
foreach ( $cursor->map( static fn( $row ) => $row[ 'name' ] ) as $name )
{
echo $name ;
}
Parameters
- $callback : callable(mixed, int, self): mixed
-
Per-row transformation.
Tags
Return values
Generator<int, mixed>reduce()
Depletes the cursor by folding it through `$reducer`, returning the accumulated value.
public
reduce(callable(mixed, mixed, int, self): mixed $reducer[, mixed $initial = null ]) : mixed
The reducer receives (mixed $accumulator, mixed $row, int $index, self $cursor)
and returns the new accumulator value. The initial accumulator
defaults to null — pass it explicitly when the reduction starts
from a typed value (0, '', [], …).
Parameters
- $reducer : callable(mixed, mixed, int, self): mixed
-
Folding function.
- $initial : mixed = null
-
Initial accumulator value.
Tags
Return values
mixed —Final accumulator value (equals $initial when the cursor was empty).
fetchNextBatch()
Fetches the next batch from the server and updates the internal state.
private
fetchNextBatch() : void