nexyron.temporal_history

Generic Description

Read the hidden timestamped history for one declared temporal property on one known subject node.

Simple example:

MATCH (u:User {id: 'user-17'})
CALL nexyron.temporal_history(element_id(u), 'weight', null, null)
YIELD node_id, property, ts, value
RETURN node_id, property, ts, value
ORDER BY ts

Temporal and streaming procedures inspect registered temporal history, rollups, time ranges, and global event timelines.

Consumer-Level Explanation

Use nexyron.temporal_history when you already know the subject node and property name and want the raw recorded values behind that property.

This is the direct procedure-level read path for temporal properties. It returns the actual history records, not a rollup and not a graph-visible event family.

Temporal histories do not float independently from graph entities. The subject node must exist when history is appended, and deleting that node removes its hidden temporal history and timeline contributions.

The first argument is a node key. It accepts either the internal integer id(node) or the public node element id string from element_id(node), for example n:180098582026649600. Feature contracts whose abstraction subject_id is already a node element id can pass $subject_id directly; contracts backed by business keys should first match the owner node and pass element_id(owner) or id(owner).

The optional time-window arguments accept canonical i64 epoch-millisecond integers. timestamp(), currenttimestamp(), current_timestamp(), now(), and datetime(...) all return that same format, and plus/minus integer arithmetic shifts by milliseconds.

When the surrounding query uses ASOF, nexyron.temporal_history is capped by that point-in-time context. Passing null as to means "up to the ASOF timestamp", and passing a later explicit to is treated as min(to, ASOF). The procedure still returns raw timestamped rows; use normal property access such as u.weight or u.profile_state under ASOF when you only need the latest scalar or object value at that point.

Conceptual Explanation

Temporal properties keep a hidden append-only history under an ordinary node property such as User.weight, Device.battery_pct, or Account.status.

nexyron.temporal_history reads that hidden history directly:

That makes it the right tool when you need the full recorded sequence and plan to run downstream sequence analytics such as lag, lead, diff, changes, or custom list processing.

For object-valued temporal properties, the value column contains the recorded object for each returned row. It does not automatically unwrap one field; project fields from value only after confirming the declared index_paths or the actual object shape.

More Detailed Explanation

In practical queries, start by deciding the row grain you want after the call: one row per node, one row per path, one row per registry object, one row per artifact, or one row per summary. Then keep that grain explicit with YIELD and named projections. That is the difference between a useful planner-facing example and a vague call that downstream tooling cannot safely compose. For contract-driven procedures, the executable examples on these pages intentionally inspect procedure metadata unless the required named artifacts are created in the same example.

Advanced Example

MATCH (u:User {id: 'user-17'})
WITH element_id(u) AS user_id
CALL nexyron.temporal_history(user_id, 'workplace', currenttimestamp() - 30 * 24 * 60 * 60 * 1000, null)
YIELD ts, value
RETURN ts, value
ORDER BY ts

Resolve the owning node from a temporal row:

MATCH (u:User {id: 'user-17'})
WITH element_id(u) AS user_id
CALL nexyron.temporal_history(user_id, 'workplace', null, null)
YIELD node_id, ts, value
WITH node_id AS temporal_owner_key, ts, value
MATCH (owner)
WHERE id(owner) = temporal_owner_key
RETURN owner, id(owner) AS owner_id, ts, value
ORDER BY ts

Real Use Cases

Real Limitations And Tradeoffs