 |
VOOZH | about |
|
VOOZH | about |
This document describes the Bolt protocol messages used to retrieve or discard result data from executed queries. After a query is submitted via the RUN message (see Query Execution Messages), the client must use streaming messages to consume the result set. The protocol provides two categories of streaming messages: PULL messages to retrieve data and DISCARD messages to skip data.
The streaming message architecture differs significantly between protocol versions:
PULL_ALL and DISCARD_ALLpull(n, qid) and discard(n, qid)For transaction control messages, see Transaction Control Messages. For session state management, see Session Management Messages.
Result streaming in Bolt follows a request-response pattern where the client must explicitly request data after executing a query. This design enables pipelining (sending multiple messages before consuming responses) and allows control over memory usage by fetching results in batches.
Sources: src/protocol/v1/PullAllMessage.php1-36 src/protocol/v4/PullMessage.php1-46 README.md76-80
The PULL_ALL message retrieves all remaining results from an executed query in a single streaming operation. This message is available in Bolt protocol versions 1 through 3.
| Property | Value | Description |
|---|---|---|
| Signature | 0x3F | Message identifier |
| Parameters | None | No arguments supported |
| Response | Multiple | SUCCESS (RUN), RECORD(s), SUCCESS (PULL_ALL) |
The PullAllMessage trait implements this message using a simple streaming loop that continues until the server stops sending RECORD responses:
Sources: src/protocol/v1/PullAllMessage.php1-36
The message is sent at src/protocol/v1/PullAllMessage.php18-23:
Response handling occurs at src/protocol/v1/PullAllMessage.php29-35:
Sources: README.md172-202 tests/BoltTest.php78-90
The PULL message in Bolt V4+ extends PULL_ALL with parameterized control over batch size and query identification. This enables streaming large result sets in manageable chunks.
| Property | Value | Description |
|---|---|---|
| Signature | 0x3F | Same as PULL_ALL (backward compatibility) |
| Parameters | {n: Integer, qid: Integer} | Batch size and query ID |
| Response | Multiple | SUCCESS/RECORD with has_more flag |
| Parameter | Type | Default | Description |
|---|---|---|---|
n | Integer | -1 | Number of records to fetch (-1 = all) |
qid | Integer | -1 | Query ID for multi-query scenarios |
The V4+ implementation introduces the has_more flag and openStreams counter for managing partial result streaming:
Sources: src/protocol/v4/PullMessage.php1-46
The message is sent at src/protocol/v4/PullMessage.php19-26:
Response handling with stream management at src/protocol/v4/PullMessage.php33-45:
n ParameterThe n parameter controls how many records to fetch per PULL request:
| n Value | Behavior |
|---|---|
-1 | Fetch all remaining records (default) |
0 | Fetch no records (metadata only) |
> 0 | Fetch exactly n records (or fewer if end reached) |
When the server has more records than requested, it sets has_more: true in the SUCCESS response. The client must send another PULL message to continue streaming.
Sources: src/protocol/v4/PullMessage.php1-46 README.md103
The DISCARD_ALL message instructs the server to discard all remaining results from an executed query without transmitting them to the client. This is useful when only the query's side effects (writes) are needed, not the result data.
| Property | Value | Description |
|---|---|---|
| Signature | 0x2F | Message identifier |
| Parameters | None | No arguments supported |
| Response | SUCCESS | Single response with summary |
The message is implemented at src/protocol/v1/DiscardAllMessage.php1-23:
Unlike PULL_ALL, DISCARD_ALL generates only a single SUCCESS response since no data records are transmitted.
Sources: src/protocol/v1/DiscardAllMessage.php1-23 tests/BoltTest.php95-105
The V4+ DISCARD message extends DISCARD_ALL with the same parameterization as PULL, allowing partial result discarding.
| Property | Value | Description |
|---|---|---|
| Signature | 0x2F | Same as DISCARD_ALL |
| Parameters | {n: Integer, qid: Integer} | Number to discard and query ID |
| Response | SUCCESS | With has_more flag if applicable |
The implementation mirrors PULL with stream management:
Sources: src/protocol/v4/DiscardMessage.php1-41
Message sending at src/protocol/v4/DiscardMessage.php20-27:
Response handling at src/protocol/v4/DiscardMessage.php34-40:
Sources: src/protocol/v4/DiscardMessage.php1-41
All streaming messages return their results through the getResponses() method, which yields Response objects in sequence.
| Order | Message Type | Signature | Content |
|---|---|---|---|
| 1 | RUN | SUCCESS | {fields: [...], t_first: ms} |
| 2..n | PULL/PULL_ALL | RECORD | [value1, value2, ...] |
| n+1 | PULL/PULL_ALL | SUCCESS | {has_more?: bool, ...stats} |
| Order | Message Type | Signature | Content |
|---|---|---|---|
| 1 | RUN | SUCCESS | {fields: [...], t_first: ms} |
| 2 | DISCARD/DISCARD_ALL | SUCCESS | {has_more?: bool, ...stats} |
Sources: tests/BoltTest.php78-90 tests/NornicDBTest.php47-71
The has_more flag in V4+ enables efficient streaming of large result sets by allowing the client to fetch data in controllable batches.
The openStreams property tracks how many active result streams exist, which is critical for transaction state management:
has_more: false)Sources: src/protocol/v4/PullMessage.php36-42 src/protocol/v4/DiscardMessage.php36-38
Sources: README.md190-201 tests/BoltTest.php78-105 tests/NornicDBTest.php47-71
| Method | V1 | V2 | V3 | V4+ |
|---|---|---|---|---|
pullAll() | ✓ | ✓ | ✓ | ✓ (alias) |
discardAll() | ✓ | ✓ | ✓ | ✓ (alias) |
pull(array) | ✗ | ✗ | ✗ | ✓ |
discard(array) | ✗ | ✗ | ✗ | ✓ |
Both V1-V3 and V4+ use the same message signatures (0x3F for pull, 0x2F for discard), with V4+ extending the protocol by adding a parameters dictionary. This maintains backward compatibility at the binary level.
Sources: src/protocol/v1/PullAllMessage.php20 src/protocol/v4/PullMessage.php23 src/protocol/v1/DiscardAllMessage.php19 src/protocol/v4/DiscardMessage.php24
The qid parameter in V4+ enables multiplexed query execution, though this feature is rarely used in practice. When specified, it allows the server to differentiate between multiple concurrent queries on the same connection.
For large result sets, the generator-based response iteration (getResponses()) ensures that results are processed one at a time without loading the entire result set into memory. This is particularly important when combined with V4+ batch streaming (n parameter).
Within explicit transactions (BEGIN...COMMIT), all result streams must be fully consumed or discarded before the transaction can be committed or rolled back. The openStreams counter enforces this constraint by preventing transaction closure while streams remain open.
Sources: src/protocol/v4/PullMessage.php36-42 src/protocol/v4/DiscardMessage.php36-38 tests/BoltTest.php111-143
Refresh this wiki