---
title: `nexyron.feature_history`
url: https://nexyron.tech/docs/cypher/procedures/abstraction-platform/runtime/nexyron-feature-history
description: nexyron.feature history reads stream backed materialized values for one abstraction feature.
---

# `nexyron.feature_history`

## Generic Description

`nexyron.feature_history` reads stream-backed materialized values for one abstraction feature.

```cypher
CALL nexyron.procedures()
YIELD name, description, parameters, output_columns
WHERE name = 'nexyron.feature_history'
RETURN name, description, parameters, output_columns
```

Abstraction-platform runtime procedures build, materialize, refresh, inspect, and execute artifacts derived from registered abstraction contracts.

## Consumer-Level Explanation

Use this procedure when you want the values collected for one abstraction feature over time. It reads the feature stream written by `nexyron.snapshot_materialize`, not a database archive snapshot and not a row-bundle artifact.

Each returned row is intentionally narrow:

-   `feature`
-   `subject_id`
-   `ts`
-   `value`

Pass `subject_id` to read one subject's feature stream. Omit it to read every subject value for that feature in the requested time range. Pass `latest: true` to get the latest collected value at or before `to`; with `subject_id` this returns one subject, and without it this returns one latest row per subject.

When the surrounding query uses `ASOF`, the procedure's effective upper bound is capped to the `ASOF` timestamp. Passing no `to`, or passing a `to` later than the query timestamp, still returns only stream points visible at or before the `ASOF` time.

## Example Contract Prerequisite

The executable Cypher blocks on this page query `nexyron.procedures()` so they work in an empty database and stay synchronized with the live procedure registry. A direct `CALL nexyron.feature_history(...)` requires the named abstraction contracts, artifacts, features, snapshots, datasets, models, or policies referenced by that call to exist first; otherwise the runtime correctly fails with an unknown-contract error rather than inventing state.

## Conceptual Explanation

Materialized snapshots are still useful as contracts: they define which abstraction, grain, scenario, and feature set should be collected. The stored values, however, are feature histories. That means a daily actor snapshot writes one stream point per `(feature, subject_id, day)` instead of forcing readers to discover and open one materialized artifact per day.

This aligns abstraction features with temporal node-property behavior. For one subject, the engine uses the subject-indexed feature stream to retrieve a bounded history or latest value. An all-subject `latest: true` read walks the same subject index and returns only the last eligible point per subject. An all-subject history read uses the timestamp index to scan the requested range for that feature.

## 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 abstraction procedures, the executable examples on these pages intentionally inspect procedure metadata unless the required named artifacts are created in the same example.

## Advanced Example

```cypher
CALL nexyron.procedures()
YIELD name, parameters, output_columns
WHERE name = 'nexyron.feature_history'
RETURN name,
       [p IN parameters | p.name] AS parameter_names,
       output_columns
ORDER BY name
```

For latest-value selector reads, use the abstraction feature expression instead of opening the stream manually:

```cypher
CALL nexyron.procedures()
YIELD name, parameters, output_columns
WHERE name = 'nexyron.feature_history'
RETURN name,
       [p IN parameters | p.name] AS parameter_names,
       output_columns
ORDER BY name
```

Use `nexyron.feature_history` when you need the raw `ts` rows behind that selector.

## Real Use Cases

-   Draw one member's risk, utilization, attendance, or propensity feature over time without issuing one snapshot read per day.
-   Retrieve all values for one feature across a training window before exporting a model dataset or auditing feature drift.
-   Explain the latest value used by `feature_get` or `feature_serve` by reading the same subject's prior stream points.
-   Validate what `actor(Member:'id').param` would have returned at several historical cutoffs.

## Real Limitations And Tradeoffs

-   The stream is populated by materialization. If no snapshot materialization has written a value for a feature and subject, this procedure returns no row rather than recomputing the feature.
-   For all-subject reads, bound the time range when possible. The timestamp index avoids opening per-day snapshot artifacts, but an unbounded all-subject history can still return a large result for high-cardinality features.
-   Scenario and dual-time system cutoffs are separate stream dimensions. Use the same `scenario` and `system_at` values that were used during materialization.
-   `ASOF` caps valid-time history returned by this procedure. It does not change the requested `system_at`; pass `system_at` explicitly when you need dual-time catalog visibility.