CypherService

OpenCypher-compatible query execution service.

Proto source

Transport

All methods are available via:

gRPC on port 7080 — native high-performance API
REST/JSON on port 7081 — HTTP/JSON transcoding via embedded structured-proxy

Query Parameters (REST)

Named parameters are passed in the parameters map. Each value is a JSON object with a single key matching the PropertyValue proto field name:

json

{
  "query": "MATCH (n:Concept {name: $name}) RETURN n",
  "parameters": {
    "name":            { "stringValue": "machine learning" },
    "limit":           { "intValue": "10" },
    "threshold":       { "floatValue": 0.4 },
    "active":          { "boolValue": true },
    "question_vector": { "vectorValue": { "values": [0.1, 0.2, 0.3] } },
    "tags":            { "listValue": { "values": [{"stringValue": "ml"}, {"stringValue": "ai"}] } }
  }
}

Available parameter types:

JSON key	Proto field	Example
`stringValue`	`string`	`{ "stringValue": "alice" }`
`intValue`	`int64`	`{ "intValue": "42" }`
`floatValue`	`double`	`{ "floatValue": 0.95 }`
`boolValue`	`bool`	`{ "boolValue": true }`
`vectorValue`	`Vector`	`{ "vectorValue": { "values": [0.1, 0.2] } }`
`listValue`	`PropertyList`	`{ "listValue": { "values": [...] } }`
`bytesValue`	`bytes`	`{ "bytesValue": "<base64>" }`

Vector parameters: use vectorValue, not listValue. vectorValue maps to the dedicated Vector proto type and enables vector index pushdown in the query planner.

Methods

ExecuteCypher

Execute an OpenCypher query and return results.

HTTP: POST /v1/query/cypher

Request: ExecuteCypherRequest

Field	Type	Description
`query`	`string`	OpenCypher query string.
`parameters`	`map<string, PropertyValue>`	Named query parameters bound at execution time.
`read_preference`	`ReadPreference`	Which cluster node may serve this read. UNSPECIFIED defaults to PRIMARY (leader-only reads). Use SECONDARY_PREFERRED for read scale-out in 3-node CE cluster.
`read_concern`	`ReadConcern`	Data consistency guarantee for this read. UNSPECIFIED defaults to LOCAL (return whatever this node has applied). Use MAJORITY for reads that must not see rolled-back data. Use LINEARIZABLE for strictest freshness (leader only, adds ~1 RTT).
`write_concern`	`WriteConcern`	Durability guarantee for write statements (CREATE / MERGE / SET / DELETE). UNSPECIFIED / omitted defaults to W1 (leader-acknowledged, not replicated). Use MAJORITY for production writes that must survive a single node failure. Causal sessions (read_concern.after_index > 0) require write_concern.level >= MAJORITY. The server rejects writes with lower durability in causal sessions because a non-majority write may never be replicated: if the leader crashes before drain, the returned applied_index becomes a dangling causal dependency that can never be satisfied by a follower read. Read-only queries ignore this field.

Response: ExecuteCypherResponse

Field	Type	Description
`columns`	`string[]`	—
`rows`	`Row[]`	—
`stats`	`QueryStats`	—

ExplainCypher

Explain an OpenCypher query plan without executing.

HTTP: POST /v1/query/cypher/explain

Request: ExplainCypherRequest

Field	Type	Description
`query`	`string`	—
`parameters`	`map<string, PropertyValue>`	—

Response: ExplainCypherResponse

Field	Type	Description
`plan`	`QueryPlan`	—

Types

ExecuteCypherRequest

Field	Type	Description
`query`	`string`	OpenCypher query string.
`parameters`	`map<string, PropertyValue>`	Named query parameters bound at execution time.
`read_preference`	`ReadPreference`	Which cluster node may serve this read. UNSPECIFIED defaults to PRIMARY (leader-only reads). Use SECONDARY_PREFERRED for read scale-out in 3-node CE cluster.
`read_concern`	`ReadConcern`	Data consistency guarantee for this read. UNSPECIFIED defaults to LOCAL (return whatever this node has applied). Use MAJORITY for reads that must not see rolled-back data. Use LINEARIZABLE for strictest freshness (leader only, adds ~1 RTT).
`write_concern`	`WriteConcern`	Durability guarantee for write statements (CREATE / MERGE / SET / DELETE). UNSPECIFIED / omitted defaults to W1 (leader-acknowledged, not replicated). Use MAJORITY for production writes that must survive a single node failure. Causal sessions (read_concern.after_index > 0) require write_concern.level >= MAJORITY. The server rejects writes with lower durability in causal sessions because a non-majority write may never be replicated: if the leader crashes before drain, the returned applied_index becomes a dangling causal dependency that can never be satisfied by a follower read. Read-only queries ignore this field.

ExecuteCypherResponse

Field	Type	Description
`columns`	`string[]`	—
`rows`	`Row[]`	—
`stats`	`QueryStats`	—

ExplainCypherRequest

Field	Type	Description
`query`	`string`	—
`parameters`	`map<string, PropertyValue>`	—

ExplainCypherResponse

Field	Type	Description
`plan`	`QueryPlan`	—

QueryPlan

Field	Type	Description
`operator`	`string`	—
`details`	`map<string, string>`	—
`children`	`QueryPlan[]`	—
`estimated_rows`	`double`	—

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).

ReadConcern

Read concern configuration.

Field	Type	Description
`level`	`ReadConcernLevel`	Consistency level for this read. UNSPECIFIED defaults to LOCAL.
`after_index`	`uint64`	Causal fence: wait until the serving node has applied log entries up to at least this Raft log index before executing the read. Set to the `QueryStats.applied_index` value from a prior write response to guarantee read-your-writes: the read is guaranteed to observe all mutations up to and including that write. 0 = no fence (default). Only valid with level = MAJORITY or SNAPSHOT; returns FAILED_PRECONDITION if level = LOCAL or LINEARIZABLE. Has no effect in standalone (non-Raft) mode — all writes are immediately visible. The returned applied_index will always be 0 in standalone mode, so clients should not set after_index unless operating in cluster mode.
`at_timestamp`	`uint64`	Snapshot pin: read the database as of this HLC timestamp (microseconds since Unix epoch, leader-assigned). Only valid with level = SNAPSHOT. Setting this with any other level returns FAILED_PRECONDITION. 0 = no pin (latest snapshot of the chosen level applies). Typical use: time-travel reads ("what did this query return at 2026-05-15 12:00:00?"). The timestamp must be within the MVCC retention window — older snapshots are GC'd. Reads beyond retention return UNAVAILABLE. Distinct from `after_index`: `after_index` is a fence (wait until at least this index is applied), `at_timestamp` is a pin (read exactly this version, no waiting).

Row

Field	Type	Description
`values`	`PropertyValue[]`	—

WriteConcern

Write concern configuration.

Field	Type	Description
`level`	`WriteConcernLevel`	—
`journal`	`bool`	Require WAL fsync before acknowledgement.
`timeout_ms`	`uint32`	Timeout in milliseconds (0 = no timeout).

Enums

ReadConcernLevel

Read concern levels.

Value	Number	Description
`READ_CONCERN_LEVEL_UNSPECIFIED`	`0`	—
`READ_CONCERN_LEVEL_LOCAL`	`1`	Read from local replica (may be stale).
`READ_CONCERN_LEVEL_MAJORITY`	`2`	Read data committed by majority.
`READ_CONCERN_LEVEL_LINEARIZABLE`	`3`	Linearizable read (strongest guarantee).
`READ_CONCERN_LEVEL_SNAPSHOT`	`4`	Read from a consistent MVCC snapshot.

ReadPreference

Read preference for routing read operations.

Value	Number	Description
`READ_PREFERENCE_UNSPECIFIED`	`0`	—
`READ_PREFERENCE_PRIMARY`	`1`	—
`READ_PREFERENCE_PRIMARY_PREFERRED`	`2`	—
`READ_PREFERENCE_SECONDARY`	`3`	—
`READ_PREFERENCE_SECONDARY_PREFERRED`	`4`	—
`READ_PREFERENCE_NEAREST`	`5`	—

WriteConcernLevel

Write concern levels. Write durability levels, ordered W0 < MEMORY < CACHE < W1 < MAJORITY. Selecting a level below W1 trades durability for latency: MEMORY and CACHE acknowledge the client before the write is replicated through Raft, with the drain thread batching them into proposals asynchronously. A leader crash before drain loses every in-flight MEMORY/CACHE write. Use only for telemetry, hot counters, session state — never for source-of-truth data.

Value	Number	Description
`WRITE_CONCERN_LEVEL_UNSPECIFIED`	`0`	—
`WRITE_CONCERN_LEVEL_W0`	`1`	use only for non-critical metrics.
`WRITE_CONCERN_LEVEL_W1`	`2`	mode and the lowest level safe to default for typical applications.
`WRITE_CONCERN_LEVEL_MAJORITY`	`3`	before Linearizable read concerns; safe under single-node failure.
`WRITE_CONCERN_LEVEL_MEMORY`	`4`	Lost on process crash before drain.
`WRITE_CONCERN_LEVEL_CACHE`	`5`	crash but not power failure before drain. Background drain to Raft.

CypherService ​

Query Parameters (REST) ​

Methods ​

ExecuteCypher ​

ExplainCypher ​

Types ​

ExecuteCypherRequest ​

ExecuteCypherResponse ​

ExplainCypherRequest ​

ExplainCypherResponse ​

QueryPlan ​

QueryStats ​

ReadConcern ​

Row ​

WriteConcern ​

Enums ​

ReadConcernLevel ​

ReadPreference ​

WriteConcernLevel ​