Preview & Hints
Preview is the feedback loop that keeps your model honest. It should be part of every modelling iteration, not reserved as a final validation step. When you open a preview, Mockomat generates a GraphQL schema from the current model state, executes a sample query against your mapped data, and returns results alongside readiness hints that identify gaps requiring attention.
This page covers how previewing works, the types of hints the system produces, and the iteration workflow that connects model changes to actionable feedback.
Preview panel showing data results and readiness hints side by side.
How Preview Works
Every preview execution follows a deterministic pipeline:
- Schema generation — Mockomat reads your current model (tables, attributes, relations, views) and produces a GraphQL schema. This schema reflects the exact state of the model at the moment of invocation.
- Sample query execution — a query is executed against the generated schema, resolving fields through the configured data mappings (OFF_FIELD, FAKE, or CONST) and relation definitions.
- Hint calculation — the system analyses the model for completeness, consistency, and configuration correctness. Every gap or mismatch produces a typed hint.
- Result presentation — the data response and the hint list are displayed together, giving you both the output and the diagnosis in a single view.
The preview always reflects the current model state. If you change an attribute, add a relation, or modify a mapping, the next preview invocation incorporates that change immediately.
Preview pipeline: schema generation, query execution, hint calculation, result presentation.
Opening the Preview
There are two entry points for launching a preview:
From the Modelling Board
Every table card on the Modelling Board has a play button in its header area. Clicking it opens the preview for that table.
- If a view already exists for the table, the preview opens in edit mode with all existing configuration loaded.
- If no view exists, the preview opens with default settings and a Create button to save the configuration as a new view record.
From the Records Page
On the records page, each table row has a play button in its action column. This behaves identically to the board entry point.
Both paths open the Modelling Runtime Preview panel, which combines view configuration, live data preview, and relation detail in a single interface.
Play button locations on the modelling board table card and records page row.
Hint Types
Hints are actionable signals derived from model completeness analysis. Each hint identifies a specific gap or inconsistency and points toward the corrective action. Hints are recalculated on every preview invocation.
| Hint | Meaning | Action |
|---|---|---|
| Unmapped attribute | A field has no data source configured. The field exists in the schema but cannot resolve to any value. | Assign an OFF_FIELD, FAKE, or CONST mapping in the attribute configuration. See Data Sources. |
| Missing endpoint metadata | A query or operation lacks required configuration such as a query name or pagination defaults. | Open the API Design view and complete the endpoint setup for the affected table. |
| Configuration mismatch | A field is marked with a flag (sortable, filterable, searchable) that is incompatible with its data type or mapping. | Review the attribute type and flag combination in the Tables & Attributes editor. |
| Relation warning | A relation references a target entity or linking column that does not exist or is misconfigured. | Check the relation definition in the table editor. See Relations for guidance on cardinality and direction. |
Hint Severity
Not all hints carry equal weight. The system distinguishes between:
- Errors — the model cannot produce valid runtime output until this issue is resolved. Example: an unmapped attribute that is required.
- Warnings — the model functions but with degraded behaviour. Example: a sortable flag on a field whose mapping does not support ordering.
- Informational — suggestions for improvement that do not affect runtime correctness. Example: a table with no relations defined.
Hint list showing error, warning, and informational severity levels.
The Iteration Workflow
The most productive modelling workflow follows a tight loop between model changes and preview feedback. The goal is to keep the cycle short — seconds, not minutes.
Recommended Sequence
- Make a model change — add a table, modify an attribute, create a relation, or adjust a mapping.
- Open preview — run a query and inspect the results.
- Review hints — address any errors or warnings surfaced by the hint system.
- Update API design — adjust query names, operation exposure, or pagination defaults if needed. See API Design.
- Repeat — continue until the model is stable and the preview returns a clean hint list.
Each pass through this loop refines the model incrementally. Short cycles surface problems early, before they compound into structural issues that are harder to resolve.
Diagram of the iteration workflow: model change, preview, hints, API update, repeat.
Why Short Cycles Matter
Delayed validation is the primary source of modelling rework. When you build ten tables before previewing, any structural issue in the first table may have propagated through relations and views. Previewing after each meaningful change keeps the blast radius small and the corrective effort minimal.
What to Validate in Preview
When inspecting preview results, focus on these aspects:
| Validation Area | What to Check | Related Page |
|---|---|---|
| Field readability | Are field names consistent? Use camelCase, avoid abbreviations. | Tables & Attributes |
| Data shape consistency | Do fields return the expected types (string, number, boolean, date)? | Tables & Attributes |
| Relation behaviour | Does a 1:n relation return an array? Does a 1:1 relation return an object? | Relations |
| Mapping completeness | Do all attributes have a configured data source? Are there unmapped-attribute hints? | Data Sources |
| Filter and sort behaviour | Do fields marked as filterable and sortable respond to operations in the query? | Tables & Attributes |
| Null handling | Do optional fields correctly return null when no data is available? | Tables & Attributes |
Preview result inspection showing field types, relation nesting, and null handling.
Common Preview Issues
The following table summarises frequently encountered issues during preview and their resolutions.
| Issue | Likely Cause | Fix |
|---|---|---|
Field returns null unexpectedly | No data mapping configured for the attribute | Assign an OFF_FIELD, FAKE, or CONST mapping in the attribute editor |
| Relation returns an empty array | Relation not properly defined — wrong direction, missing foreign key, or target entity does not exist | Review the relation definition. See Relations |
| Sort has no effect on query results | The field is not marked as sortable | Enable the sortable flag in the attribute configuration |
| Filter returns all records | The field is not marked as filterable | Enable the filterable flag in the attribute configuration |
| Query name not found | Endpoint metadata is incomplete | Open API Design and configure the query name for the table |
| Nested query returns incorrect data | Linking columns in the relation are misconfigured | Verify that the source and target columns in the relation editor match the actual data structure |
Causality: Model State, Hints, and Required Actions
Understanding the causal relationship between model state and hints is essential for efficient modelling.
How Hints Are Derived
Every model change triggers hint recalculation during the next preview. The system evaluates:
- Attribute completeness — does every attribute have a type, a name, and a data mapping?
- Relation integrity — does every relation reference a valid target entity and valid linking columns on both sides?
- Endpoint readiness — does every exposed query have a name, pagination defaults, and at least one resolvable field?
- Flag consistency — are attribute flags (sortable, filterable, searchable) compatible with the attribute type and mapping?
What a Clean Hint List Means
When the preview returns no errors or warnings, the model satisfies all structural and configuration requirements. This means:
- Every attribute resolves to a data value.
- Every relation produces correctly nested output.
- Every exposed query is fully configured and executable.
- The mock API endpoint is ready for consumer use.
What Unresolved Hints Mean
Unresolved hints indicate gaps that will affect runtime behaviour. An unmapped attribute returns null. A misconfigured relation returns empty results. A missing query name prevents consumers from discovering the endpoint. Hints are not cosmetic — they correspond directly to runtime defects.
Causality diagram: model state determines hints, hints guide required actions, resolved hints indicate readiness.
Related Pages
- Modelling Runtime Preview — the combined preview panel with view configuration, live data, and relation detail
- Tables & Attributes — attribute configuration, data mappings, and field flags
- Relations — relation types, linking columns, and cardinality
- Data Sources — available datasets and data object selection
- API Design — query naming, operation exposure, and pagination defaults
- Modelling Board — the visual canvas where domain entities are created and arranged