RollupArchiveSnapshot
Namespace: Meshmakers.Octo.Runtime.Contracts.StreamData
Read-only snapshot of the parts of a CkRollupArchive entity the orchestrator and the
lifecycle service need. Extends the data carried by ArchiveSnapshot with rollup-
specific fields. Backend-specific stores translate from their concrete representation to this
record.
public record RollupArchiveSnapshot : IEquatable<RollupArchiveSnapshot>
Inheritance Object → RollupArchiveSnapshot
Implements IEquatable<RollupArchiveSnapshot>
Remarks:
Concept §3 / §5. RollupArchiveSnapshot.LastAggregatedBucketEnd is null before the first orchestrator
run; it is advanced exclusively by the orchestrator (per bucket commit) and by the
rewindRollupWatermark mutation. RollupArchiveSnapshot.FrozenUntil is null when the rollup is not
frozen; once set it is monotonic.
Since System.StreamData 1.8.0 (AB#5157) a rollup declares several time-disjoint
sources via RollupArchiveSnapshot.Sources instead of a single source archive id, so history imported at
a coarser granularity and data ingested natively at a finer granularity end up in one
continuous rollup ladder. The snapshot is always normalised — the deprecated single-id storage
form arrives here as exactly one unbounded RollupSourceReference — so every
engine consumer works on RollupArchiveSnapshot.Sources alone and never on the raw entity fields.
See concept-multi-source-rollups.md.
Properties
RtId
Runtime id of the rollup archive entity.
public OctoObjectId RtId { get; set; }
Property Value
OctoObjectId
TargetCkTypeId
CK type the rollup rows live on — inherited from its sources.
public RtCkId<CkTypeId> TargetCkTypeId { get; set; }
Property Value
RtCkId<CkTypeId>
Status
Current archive lifecycle status.
public CkArchiveStatus Status { get; set; }
Property Value
RtWellKnownName
Optional human-readable name; null falls back to the rtId.
public string RtWellKnownName { get; set; }
Property Value
Sources
The normalised source archives this rollup aggregates from, each with an optional validity span. Never empty for a valid rollup — an empty list means the entity declares no source at all and is rejected at activation. Spans are pairwise disjoint and every bucket lies entirely within one source's span or within none (see RollupArchiveSnapshot.SourceForBucket(DateTime, DateTime)).
public IReadOnlyList<RollupSourceReference> Sources { get; set; }
Property Value
IReadOnlyList<RollupSourceReference>
BucketSize
Bucket width.
public TimeSpan BucketSize { get; set; }
Property Value
WatermarkLag
How long the orchestrator waits after bucket-end before aggregating.
public TimeSpan WatermarkLag { get; set; }
Property Value
LastAggregatedBucketEnd
Exclusive end of the most recently committed bucket; null before the first run.
public Nullable<DateTime> LastAggregatedBucketEnd { get; set; }
Property Value
Aggregations
The rollup's logical aggregation specs (source path + function).
public IReadOnlyList<CkRollupAggregationSpec> Aggregations { get; set; }
Property Value
IReadOnlyList<CkRollupAggregationSpec>
FrozenUntil
When set, no new bucket whose end is at or before this timestamp is produced.
public Nullable<DateTime> FrozenUntil { get; set; }
Property Value
BucketAlignment
Bucket-boundary alignment. BucketAlignment.FixedSize (the default for
entities created before System.StreamData 1.4.0) preserves the legacy
LastAggregatedBucketEnd + BucketSize arithmetic. Calendar / ISO-week variants
derive bucket boundaries from the wall clock so monthly / weekly / yearly rollups become
expressible. Concept-time-range §7.
public BucketAlignment BucketAlignment { get; set; }
Property Value
ReferenceTimeZone
IANA reference time-zone id (e.g. Europe/Vienna) used to align calendar bucket
boundaries (day / week / month / year) to local wall-clock time so they are DST-correct
across countries. null ⇒ UTC calendar boundaries (the pre-AB#4290 behaviour). Only
meaningful for calendar RollupArchiveSnapshot.BucketAlignment variants; ignored for
BucketAlignment.FixedSize. System.StreamData 1.6.4 / decision O6.
public string ReferenceTimeZone { get; set; }
Property Value
CarryLookback
How far before a bucket's start the CkRollupFunction.TimeWeightedAvg
carry-in scan (LOCF opening state) looks for the latest source observation. Bounds the
per-bucket source scan. null ⇒ the engine default of 35 days. Only consulted by
TimeWeightedAvg aggregations; ignored otherwise. System.StreamData 1.6.5 / AB#4336
decision D1.
public Nullable<TimeSpan> CarryLookback { get; set; }
Property Value
HasPersistedColumns
True when the entity carries at least one persisted (ingested, non-computed) column on its
inherited Archive.Columns slot — i.e. the dehydrated
RollupColumnGenerator cache exists. false flags the defect state
produced by ImportRt-seeded records, which arrive with RollupArchiveSnapshot.Aggregations but no
Columns attribute — breaking the non-null columns GraphQL field for the whole
archives list (AB#4771/AB#4772); computed columns alone don't count. When false, callers
holding a write path (orchestrator tick, lifecycle activation) heal via
IRollupArchiveRuntimeStore.TryPersistDerivedColumnsAsync(OctoObjectId).
public bool HasPersistedColumns { get; set; }
Property Value
Remarks:
The rollup read path re-derives the columns from RollupArchiveSnapshot.Aggregations and is therefore
unaffected, but consumers that read the source archive's persisted Columns list — above all
chained-rollup activation, which resolves an aggregation's SourcePath against it —
see nothing. Defaults to true so callers constructing a snapshot without persistence
context (tests, in-memory stores) are not treated as defective.
RecomputeInProgress
True while a recompute job for this rollup is running or swapping. Mirrors
Archive.RecomputeInProgress.
public bool RecomputeInProgress { get; set; }
Property Value
LastRecomputeStartedAt
Start timestamp of the most recent recompute run; null before the first run.
public Nullable<DateTime> LastRecomputeStartedAt { get; set; }
Property Value
LastRecomputeSuccessAt
Finish timestamp of the most recent successfully committed recompute run; null before the first success.
public Nullable<DateTime> LastRecomputeSuccessAt { get; set; }
Property Value
LastRecomputeFailureAt
Timestamp of the most recent failed recompute run; null if the last run succeeded.
public Nullable<DateTime> LastRecomputeFailureAt { get; set; }
Property Value
LastRecomputeFailureReason
Human-readable reason for the most recent recompute failure; null if the last run succeeded.
public string LastRecomputeFailureReason { get; set; }
Property Value
DirtyWindowsPending
Number of dirty windows currently recorded on this archive (Information A — retroactive changes not yet propagated). 0 in the steady state.
public int DirtyWindowsPending { get; set; }
Property Value
PendingRecomputeRanges
Number of pending recompute ranges currently queued on this archive (Information B — the recompute work list the orchestrator still has to drain). 0 in the steady state.
public int PendingRecomputeRanges { get; set; }
Property Value
ConflictingSourceArchiveRtId
The deprecated SourceArchiveRtId scalar the entity still carries when it disagrees
with RollupArchiveSnapshot.Sources — i.e. both storage forms are set and RollupArchiveSnapshot.Sources is
not exactly one unbounded reference to the same archive. null in every other case.
public Nullable<OctoObjectId> ConflictingSourceArchiveRtId { get; set; }
Property Value
Remarks:
Set exclusively by the single normalisation point on the read side (the runtime store's snapshot mapping); RollupArchiveSnapshot.Sources is always kept as the authoritative declaration so enumeration never throws. Activation rejects a snapshot that carries this flag (RollupSourceDeclarationConflictException) instead of silently picking one of the two declarations.
SingleUnboundedSourceRtId
The single source archive id for read surfaces that still expose the deprecated
sourceArchiveRtId field — non-null only when the rollup declares exactly one source
and that source is unbounded. null for every genuinely multi-source rollup, for a
single source carrying a validity span, and for a rollup without sources.
public Nullable<OctoObjectId> SingleUnboundedSourceRtId { get; }
Property Value
Constructors
RollupArchiveSnapshot(OctoObjectId, RtCkId<CkTypeId>, CkArchiveStatus, String, IReadOnlyList<RollupSourceReference>, TimeSpan, TimeSpan, Nullable<DateTime>, IReadOnlyList<CkRollupAggregationSpec>, Nullable<DateTime>)
Read-only snapshot of the parts of a CkRollupArchive entity the orchestrator and the
lifecycle service need. Extends the data carried by ArchiveSnapshot with rollup-
specific fields. Backend-specific stores translate from their concrete representation to this
record.
public RollupArchiveSnapshot(OctoObjectId RtId, RtCkId<CkTypeId> TargetCkTypeId, CkArchiveStatus Status, string RtWellKnownName, IReadOnlyList<RollupSourceReference> Sources, TimeSpan BucketSize, TimeSpan WatermarkLag, Nullable<DateTime> LastAggregatedBucketEnd, IReadOnlyList<CkRollupAggregationSpec> Aggregations, Nullable<DateTime> FrozenUntil)
Parameters
RtId OctoObjectId
Runtime id of the rollup archive entity.
TargetCkTypeId RtCkId<CkTypeId>
CK type the rollup rows live on — inherited from its sources.
Status CkArchiveStatus
Current archive lifecycle status.
RtWellKnownName String
Optional human-readable name; null falls back to the rtId.
Sources IReadOnlyList<RollupSourceReference>
The normalised source archives this rollup aggregates from, each with an optional validity
span. Never empty for a valid rollup — an empty list means the entity declares no source at all
and is rejected at activation. Spans are pairwise disjoint and every bucket lies entirely
within one source's span or within none (see RollupArchiveSnapshot.SourceForBucket(DateTime, DateTime)).
BucketSize TimeSpan
Bucket width.
WatermarkLag TimeSpan
How long the orchestrator waits after bucket-end before aggregating.
LastAggregatedBucketEnd Nullable<DateTime>
Exclusive end of the most recently committed bucket; null before the first run.
Aggregations IReadOnlyList<CkRollupAggregationSpec>
The rollup's logical aggregation specs (source path + function).
FrozenUntil Nullable<DateTime>
When set, no new bucket whose end is at or before this timestamp is produced.
Remarks:
Concept §3 / §5. RollupArchiveSnapshot.LastAggregatedBucketEnd is null before the first orchestrator
run; it is advanced exclusively by the orchestrator (per bucket commit) and by the
rewindRollupWatermark mutation. RollupArchiveSnapshot.FrozenUntil is null when the rollup is not
frozen; once set it is monotonic.
Since System.StreamData 1.8.0 (AB#5157) a rollup declares several time-disjoint
sources via RollupArchiveSnapshot.Sources instead of a single source archive id, so history imported at
a coarser granularity and data ingested natively at a finer granularity end up in one
continuous rollup ladder. The snapshot is always normalised — the deprecated single-id storage
form arrives here as exactly one unbounded RollupSourceReference — so every
engine consumer works on RollupArchiveSnapshot.Sources alone and never on the raw entity fields.
See concept-multi-source-rollups.md.
Methods
SourceForBucket(DateTime, DateTime)
Picks the source that is authoritative for the half-open bucket
[, ) — the first reference
whose validity span contains the bucket entirely. Returns null when no span
covers the bucket; the orchestrator then writes no row for it and advances the watermark.
public RollupSourceReference SourceForBucket(DateTime bucketStart, DateTime bucketEnd)
Parameters
bucketStart DateTime
Inclusive start of the bucket.
bucketEnd DateTime
Exclusive end of the bucket.
Returns
Remarks:
Because the spans are validated as pairwise disjoint and aligned to the rollup's bucket grid, at most one source can ever contain a given bucket — the first match is the only match.
HasSource(OctoObjectId)
True when archiveRtId is one of this rollup's declared sources,
regardless of the validity span it carries. The membership test behind the dependency
graph, the source delete guard and rollupsFor.
public bool HasSource(OctoObjectId archiveRtId)
Parameters
archiveRtId OctoObjectId
Runtime id of the candidate source archive.