SessionService

Multiplexed bidirectional session. One long-lived bidirectional stream carries many concurrent operations for a single client. The client fires a batch of requests into the stream; the server executes them concurrently and streams results back as independent cursors, tagged by request id, in completion order rather than send order. An interactive transaction rides the same session as one interleaved sub-thread alongside non-transactional requests. The session is sticky to the serving node for its lifetime. The unary query and transaction RPCs remain the simple default; this stream is their streaming superset.

Proto source

session/session.proto

Methods

Session

Open a session. The client sends a stream of ClientFrames (queries and transaction-control operations); the server returns a stream of ServerFrames (cursor chunks and transaction acknowledgements), each tagged with the originating request_id so responses demultiplex out of order.

Transport: Server-streaming gRPC only (no HTTP transcoding)

Request: stream ClientFrame

Field	Type	Description
request_id	uint64	Client-assigned, session-scoped correlation id. Every ServerFrame produced for this operation carries the same request_id, so a client demultiplexes concurrent responses and cursor chunks that arrive out of order. The client is responsible for keeping request_ids unique within a live session.
execute	Execute	Run a query statement (autonomous or inside a transaction).
begin	Begin	Open an interactive transaction; the server replies with a Begun(txid).
commit	Commit	Commit an interactive transaction by its txid.
rollback	Rollback	Roll back an interactive transaction by its txid.
cancel	Cancel	Abort an in-flight request and close its cursor.

Response: stream ServerFrame

Field	Type	Description
request_id	uint64	request_id of the ClientFrame this event answers.
begun	Begun	Acknowledges Begin and returns the allocated transaction handle.
cursor_open	CursorOpen	Opens a cursor for a query, carrying the column header.
rows	RowBatch	A batch of result rows for an open cursor; many may arrive per request.
cursor_end	CursorEnd	Closes a cursor, carrying final query statistics.
committed	Committed	Acknowledges Commit, carrying the causal applied-index token.
error	SessionError	Reports an error for the request; terminates its cursor.

Types

Begin

Open an interactive transaction.

Field	Type	Description
ordering	Ordering	Statement ordering policy for the transaction.
drain_timeout_ms	uint32	How long (milliseconds) the server's reorder buffer waits for a missing nonce before aborting the transaction, in ORDERING_ORDERED mode. Zero uses the per-session default. Distinct from the idle-reap timeout that closes an untouched transaction.

Begun

Acknowledges Begin.

Field	Type	Description
txid	uint64	Allocated transaction handle, always non-zero. Pass it as Execute.txid and to Commit / Rollback.

Cancel

Abort an in-flight request and close its cursor.

Field	Type	Description
target_request_id	uint64	request_id of the in-flight request to abort.

ClientFrame

One operation sent by the client on the session stream.

Field	Type	Description
request_id	uint64	Client-assigned, session-scoped correlation id. Every ServerFrame produced for this operation carries the same request_id, so a client demultiplexes concurrent responses and cursor chunks that arrive out of order. The client is responsible for keeping request_ids unique within a live session.
execute	Execute	Run a query statement (autonomous or inside a transaction).
begin	Begin	Open an interactive transaction; the server replies with a Begun(txid).
commit	Commit	Commit an interactive transaction by its txid.
rollback	Rollback	Roll back an interactive transaction by its txid.
cancel	Cancel	Abort an in-flight request and close its cursor.

Commit

Commit an interactive transaction.

Field	Type	Description
txid	uint64	Transaction handle from a prior Begun.
last_nonce	uint64	Expected final nonce of the transaction's statement chain, in ORDERING_ORDERED mode, so the server can detect a complete chain before it commits. Zero when unset (UNORDERED transactions, or callers that do not pipeline ahead of the commit).

Committed

Acknowledges Commit.

Field	Type	Description
applied_index	uint64	Raft log index the commit was applied at on the serving node: the causal operationTime token a client passes as after_index on later causal reads. Zero in embedded mode (no Raft cluster).

CursorEnd

Closes a result cursor.

Field	Type	Description
stats	QueryStats	Final query statistics for the request. Reuses the unary query stats so the causal applied-index and write counts decode identically.

CursorOpen

Opens a result cursor.

Field	Type	Description
columns	string[]	Result column names, in result order.

Execute

Execute one query statement.

Field	Type	Description
query	string	Query text in the session's dialect (Cypher today; SQL once the SQL frontend lands). The server selects a query frontend per session or per statement and never inspects the syntax above that frontend.
parameters	map<string, PropertyValue>	Named query parameters bound at execution time. Same shape as the unary ExecuteCypherRequest parameters.
txid	uint64	Interactive transaction handle from a prior Begun. Zero means the statement is autonomous (implicit begin + commit). Non-zero runs the statement inside that transaction: it reads the transaction's pinned snapshot and its writes buffer until Commit.
nonce	uint64	Per-transaction ordering nonce, used only when the transaction was opened with ORDERING_ORDERED. The server applies the transaction's statements in ascending nonce order regardless of wire-arrival order. Ignored for autonomous statements and for ORDERING_UNORDERED transactions.

QueryStats

Field	Type	Description
nodes_created	int64	—
nodes_deleted	int64	—
edges_created	int64	—
edges_deleted	int64	—
properties_set	int64	—
execution_time_ms	int64	—
applied_index	uint64	Raft log index applied on the serving node at query time. Clients use this as after_index in subsequent causal reads (R142). 0 means the node is not part of a Raft cluster (embedded mode).
served_by_leader	bool	True when the read was served by the Raft leader. False for follower reads (read_preference = SECONDARY or NEAREST).

Rollback

Roll back an interactive transaction, discarding all buffered writes.

Field	Type	Description
txid	uint64	Transaction handle from a prior Begun.

Row

Field	Type	Description
values	PropertyValue[]	—

RowBatch

A batch of result rows for an open cursor. Rows reuse the unary query Row message so a session result and a unary result decode identically.

Field	Type	Description
rows	Row[]	Result rows, each a list of property values aligned to CursorOpen.columns.

ServerFrame

One result event sent by the server on the session stream.

Field	Type	Description
request_id	uint64	request_id of the ClientFrame this event answers.
begun	Begun	Acknowledges Begin and returns the allocated transaction handle.
cursor_open	CursorOpen	Opens a cursor for a query, carrying the column header.
rows	RowBatch	A batch of result rows for an open cursor; many may arrive per request.
cursor_end	CursorEnd	Closes a cursor, carrying final query statistics.
committed	Committed	Acknowledges Commit, carrying the causal applied-index token.
error	SessionError	Reports an error for the request; terminates its cursor.

SessionError

Reports an error for a request.

Field	Type	Description
code	uint32	Stable numeric error code (mirrors the gRPC status taxonomy used elsewhere on the server). Lets a client branch on the failure class without parsing the message text.
message	string	Human-readable error detail for logs and diagnostics. Not a stable contract; branch on code, not on this string.

Enums

Ordering

Statement ordering policy for an interactive transaction, fixed at Begin.

Value	Number	Description
ORDERING_UNSPECIFIED	0	Treated as ORDERING_ORDERED.
ORDERING_ORDERED	1	order. A failure at nonce K aborts the transaction.
ORDERING_UNORDERED	2	transaction back.