---
title: nexyron.global_time_bins
url: https://nexyron.tech/docs/cypher/procedures/temporal-and-streaming/nexyron-global-time-bins
description: Aggregate global timeline activity into fixed width bins for heatmap and overview views.
---

# nexyron.global_time_bins

## Generic Description

Aggregate global timeline activity into fixed-width bins for heatmap and overview views.

Simple example:

```cypher
CALL nexyron.global_time_bins(0, 60000, 'heart_rate', 96)
YIELD bin_index, start_ts, end_ts, weight, contribution_count, subject_ids
RETURN bin_index, start_ts, end_ts, weight, contribution_count, subject_ids
ORDER BY bin_index
```

The time bounds accept canonical `i64` epoch-millisecond integers. For example, `currenttimestamp() - 2592000000` is a valid lower bound for the previous 30 days, and `timestamp()` returns the same integer millisecond format.

## Consumer-Level Explanation

Use `nexyron.global_time_bins` when a UI or analytical query needs the shape of temporal activity, not every concrete timeline contribution. It returns one row per requested time bucket, which keeps the result size predictable for graph overlays, dashboards, and overview panels.

## Conceptual Explanation

`nexyron.global_time_bins` is the aggregate companion to `nexyron.global_time_range`. Both read the same global timeline index, but they answer different questions.

`global_time_range` ranks subjects over one window. `global_time_bins` divides the window into a fixed number of intervals and reports the activity in each interval. Each bin includes:

-   `bin_index`: zero-based bin position
-   `start_ts` and `end_ts`: inclusive epoch millisecond bounds
-   `weight`: total weighted activity in the bin
-   `contribution_count`: number of timeline contributions overlapping the bin
-   `subject_ids`: exact internal subject IDs with activity in the bin, returned as strings to avoid JavaScript integer precision loss

This is the right procedure for a heatmap-style timeline under a graph view because the client can render from a fixed number of rows and intersect `subject_ids` with the currently displayed graph nodes.

When callers pass the full unbounded range `0` to `9223372036854775807`, Nexyron first finds the actual minimum and maximum timestamps among matching timeline entries, then divides that real data extent into bins. That keeps UI heatmaps from collapsing all ordinary epoch-millisecond events into the first bucket of an enormous sentinel range.

## 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

```cypher
CALL nexyron.global_time_bins(0, 9223372036854775807, null, 64)
YIELD bin_index, start_ts, end_ts, weight, contribution_count, subject_ids
WITH bin_index, start_ts, end_ts, weight, contribution_count, size(subject_ids) AS active_subjects
RETURN bin_index, start_ts, end_ts, contribution_count, active_subjects, weight
ORDER BY bin_index
```

## Real Use Cases

-   Draw a full-width timeline heatmap under a graph visualization without transferring every event row.
-   Highlight graph nodes that have temporal activity inside a dragged time window by intersecting bin `subject_ids` with displayed node IDs.
-   Build dashboard sparklines for cross-entity temporal activity where the user needs overview density before drilling into exact events.
-   Compare activity bursts across telemetry, event streams, and temporal-property contributions without first choosing one entity.

## Real Limitations And Tradeoffs

-   This procedure is for overview and interaction. Use `nexyron.entity_time_range` when the user drills into exact events for a small selected entity set.
-   `subject_ids` can still be large in a bin if a very large number of entities have activity in the same interval. The query size stays fixed, but the response size follows the actual bin activity.
-   Bins are fixed-width over the requested range. If the range is very large, short spikes may be compressed into one bucket; ask for more bins or a narrower range when inspection matters.
-   Duration-like contributions can overlap multiple bins, so the sum of `contribution_count` across bins can be higher than the number of distinct source events.