advanexus

Operational guide · Version evolution

Evolve a Dataset and report without rewriting their history.

Use this workflow when Dataset-owned SQL, source lineage, schema, columns or column metadata changes and an existing report must decide whether to accept the new contract.

Published
Author
advanexus
Start with the acceptance decision
Decision question

Does Dataset v3 preserve the columns, types, grain and source meaning required by the report—or should Report v5 remain pinned to Dataset v2 until the analytical contract is redesigned?

Objects and controls used

Dataset, DatasetVersion and DatasetColumn carry the base data contract. ReportVersion carries analytical intent and exact DatasetVersion bindings. AnalyticsRun records one execution under current governance.

Acceptance flow

A new DatasetVersion never moves an existing ReportVersion by itself.

Failure and partial paths

A rejected candidate leaves the previous production-facing report version and its historical run bindings unchanged.

Evidence produced

The version comparison, accepted DatasetVersion identity, immutable ReportVersion binding, compilation/config/filter/RLS hashes and later AnalyticsRun provide the recorded chain for the supported change.

Decision question

Does Dataset v3 preserve the columns, types, grain and source meaning required by the report—or should Report v5 remain pinned to Dataset v2 until the analytical contract is redesigned?

Objects and controls used

Dataset, DatasetVersion and DatasetColumn carry the base data contract. ReportVersion carries analytical intent and exact DatasetVersion bindings. AnalyticsRun records one execution under current governance.

Dataset lifecycle and immutable DatasetVersion identity

Normalised SQL, source lineage, columns, types and known profile metadata

Report dimensions, metrics, chart, persistent filters and exact bindings

Server-owned compilation, permission, RLS and preview context

Acceptance flow

A new DatasetVersion never moves an existing ReportVersion by itself.

  1. Create the new DatasetVersion

    Save the changed Dataset-owned SQL/schema/column contract while preserving the stable Dataset identity and all prior versions.

  2. Compare exact versions

    Review normalised SQL diff, source lineage, added/removed/changed columns, types, nullable state and unavailable historical metadata.

  3. Evaluate analytical compatibility

    Confirm the intended grain, dimensions and source fields required by each metric; do not infer compatibility from matching names alone.

  4. Open a new report draft

    Keep the prior ReportVersion immutable and bind the draft to the candidate DatasetVersion.

  5. Validate and compile

    Resolve metadata, validate Query Context and compile server-owned read-only SQL for the current supported dialect path.

  6. Preview under governance

    Execute a bounded preview with current permission and RLS scope and review diagnostics rather than accepting schema validation alone.

  7. Save the accepted ReportVersion

    Persist the new binding only after acceptance; subsequent AnalyticsRuns point to that exact ReportVersion and DatasetVersion pair.

Failure and partial paths

A rejected candidate leaves the previous production-facing report version and its historical run bindings unchanged.

Removed or changed field

Compilation or semantic validation blocks the draft; redesign the dimension or metric instead of changing the old ReportVersion.

Preview differs unexpectedly

Treat live-row drift, source change, filter/RLS scope and contract change as separate hypotheses; a virtual DatasetVersion is not a row snapshot.

Multi-binding is partial

Review each binding diagnostic and preserve the partial state; do not certify the report from only the successful binding.

Evidence produced

The version comparison, accepted DatasetVersion identity, immutable ReportVersion binding, compilation/config/filter/RLS hashes and later AnalyticsRun provide the recorded chain for the supported change.

Report v4 → Dataset v2 · Report v5 → Dataset v2 · Report v6 → Dataset v3

Current boundary

Comparison covers recorded SQL, schema, columns, metadata and lineage; it does not invent universal downstream business impact. Analytics metrics, RLS and report permissions remain outside the base Dataset aggregate, and exact historical rows require an artifact or explicit materialised snapshot contract.

Continue exploring

Governed datasets Turn data definitions into versioned assets with explicit lineage.

Dataset separates exploratory SQL from a reusable data contract. Its stable identity, immutable versions and semantic metadata create a controlled foundation for reports without hiding the source lineage.

 Controlled analytics Pin the data contract. Govern the execution. Explain the result.

Controlled Analytics binds a report to exact DatasetVersions, validates Query Context on the server and retains the permission, RLS, filter, binding and artifact context behind a supported result.

 Operational guide · Data lifecycle From a known input to a governed analytical result.

Use this workflow when a recurring analytical result must retain known input, quality, version, permission and execution context across separate canonical modules.

 Advanexus Assurance Investigate a supported outcome through the available evidence behind it.

Assurance is a permission-aware, read-optimised layer for exploring supported operational evidence. It does not replace the canonical source or manufacture history that was never recorded.

Next step

Review the version boundaries in the product model.

Dataset owns the data contract; Analytics owns report intent, metrics, RLS and execution.

Explore governed datasets