Holistics dashboard report failed: model relationship error missing join fix

TL;DR

Define the relationship in the Holistics data model first, matching the join keys and the relationship type to how the tables actually relate, then rerun the report. Holistics builds report SQL from declared model relationships, so two models with no declared join cannot be combined no matter how the report is arranged. Adding the correct relationship fixes the report and every future report over the same pair.

Holistics dashboard report failed: model relationship error missing join fix

Use this when

• A report fails only when fields from two models are combined.
• Each model previews correctly on its own in the modelling layer.
• A schema change renamed a join key used between the models.

Not for this skill when

• A single-model report fails with a field or permission error. Fix that model directly.
• The report runs but double counts rows. That is a cardinality problem to remodel, related but not this missing join error.

Steps

1. Open the failing report and list the models its fields come from, then reproduce the error by adding one field from the second model. Verify: the error appears exactly when the second model joins the report
2. Open the data modelling layer and check for a declared relationship between the two models. Verify: no relationship exists, or the existing one references a renamed key field
3. Confirm the real join keys by inspecting both underlying tables and sampling matching values. Verify: the key columns share values and data types on both sides
4. Create or correct the relationship with the proper join condition and relationship type, then save and deploy the model change. Verify: the relationship appears in the model diagram between the two models
5. Rerun the report and compare a known aggregate against a hand written join query on the source tables. Verify: the report total matches the hand written result
6. Check other reports that combine the same model pair so the new relationship did not change their results unexpectedly. Verify: spot checked reports return their previous totals

Why it happens

Declared relationships are the contract reports rely on, so a missing declaration is a modelling gap, not a report bug. Renamed keys break the contract silently until a report exercises the pair. Modelling teams that review relationship changes alongside table changes, and that test one combined report per model pair, catch the gap before report viewers do.

Holistics separates the modelling layer from reports. Reports drag fields from models, and the engine generates joins only from relationships declared in the model definitions, including the join condition and the cardinality. A report that mixes models whose relationship was never declared, or whose join keys were renamed in the underlying tables, fails with a relationship error at run time even though each model queries fine on its own.

Field notes for Holistics specifically. The modelling layer is the system of record, so the model diagram, the relationship definitions, and the deploy history are the evidence to start from, ahead of the failing report itself. Because reports inherit behaviour from models, a report level fix that contradicts the model will be overwritten by the next person who edits in the modelling layer. Capture the intended relationship or definition in the model, deploy it, and let the report heal as a consequence, which also fixes every other report over the same models.

Holistics teams should review model changes with the same care as schema changes, because downstream report count is usually invisible to the person editing. A lightweight practice is to keep a short list of the highest audience reports per model pair and to run one after any relationship change. The tool rewards teams that model deliberately and punishes, politely but firmly, teams that treat the modelling layer as a drawing exercise. Most relationship incidents are discovered by viewers precisely because nobody ran the pair test after the change.

Variants and edge cases

Holistics relationship missing join two models report error

The two-model phrasing matching the failure signature.

Holistics model relationship error after schema change

The schema-change variant where a key rename broke the join.

Holistics define relationship join condition fix report

The fix-first phrasing naming where the repair lives.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_uWZjN-C6tgtSt00cOA0p-Q