Causality Reference
Every modelling decision in Mockomat propagates through a connected chain of consequences. An entity name chosen on the Modelling Board determines a GraphQL type name at runtime. A flag toggled on an attribute alters the query surface available to consumers. A relation drawn between two tables introduces a lookup stage in the aggregation pipeline.
This page documents those causal chains exhaustively. Understanding them allows you to predict the downstream effects of every configuration change before it reaches your consumers.
Model to API
The domain model is the single source of truth for the generated GraphQL schema. Every structural decision at the modelling layer has a direct, deterministic effect on the API surface.
| Model Decision | API Consequence |
|---|---|
| Entity name | Becomes the GraphQL object type name |
| Attribute name | Becomes the GraphQL field name on that type |
Attribute type (string, number, boolean, date, json) | Determines the GraphQL scalar type (String, Float, Boolean, DateTime, JSON) |
| Required flag enabled | Adds the non-null (!) modifier to the field in the schema |
| Sortable flag enabled | Exposes a sort parameter for the field in list queries |
| Filterable flag enabled | Exposes filter expressions (equality, range, pattern) for the field |
| Searchable flag enabled | Includes the field in full-text search query resolution |
Renaming an entity or attribute changes the corresponding GraphQL identifier. Consumers referencing the old name will receive schema validation errors. Treat names as stable contract identifiers once consumers have integrated.
See Tables & Attributes for the full attribute configuration reference.
Attribute flags on a table and the resulting GraphQL schema fields.
Model to Runtime
The runtime engine translates your domain model into executable MongoDB operations. Structural choices at the model layer determine the shape and cost of every query.
| Model Decision | Runtime Consequence |
|---|---|
| Each entity with an active view | A queryable collection in the mock runtime |
| Each relation between entities | A $lookup stage appended to the aggregation pipeline |
| Relation cardinality (1:1 vs 1:n vs m:n) | Response shape: single nested object vs array of objects |
| Relation direction | Determines which entity exposes the nested data in its queries |
| Missing or misconfigured relation | Empty nested fields at runtime; relation warning hint raised |
Adding relations increases pipeline complexity. A deeply nested query with multiple relation traversals produces a multi-stage aggregation. The runtime executes these stages sequentially, so relation depth has a linear effect on query latency.
See Relations for cardinality and direction configuration. See Runtime for the four-stage pipeline architecture.
Relation drawn on the board and the corresponding lookup stage in the runtime pipeline.
Mapping to Data
Mappings control the origin of field values at runtime. The mapping type is invisible to API consumers — they receive the same response shape regardless of how the data was sourced.
| Mapping Type | Data Consequence |
|---|---|
OFF_FIELD | Value read from the imported dataset in MongoDB; reflects real data |
FAKE | Value generated on-the-fly by Faker; different on each query unless seeded |
CONST | Fixed value returned for every record; identical across all rows |
| No mapping assigned | null returned for the field; preview raises a hint warning |
The distinction matters during modelling. A field mapped to FAKE will return plausible but non-deterministic values, which is useful for prototyping but unreliable for integration testing with expected outputs. A field mapped to OFF_FIELD returns stable, imported data.
Unmapped attributes are the most common source of unexpected null values. The Modelling Runtime Preview surfaces these immediately as configuration hints.
See Data Sources for the full mapping configuration workflow.
Mapping configuration panel showing OFF_FIELD, FAKE, and CONST mappings with their runtime output.
View to Consumer
Views are the decisive layer between your raw domain model and the consumer-facing API response. Without an active view, a table has no runtime representation — it exists in the model but is unreachable by consumers.
| View Decision | Consumer Consequence |
|---|---|
| Column visibility toggled off | Field absent from API response schema entirely |
| Column order rearranged | Field order in API responses follows the configured sequence |
| Pagination default (page size) | Applied when consumer omits pagination parameters |
| Sort default (field and direction) | Applied when consumer omits sort parameters |
| Detail relations enabled | Nested data available in detail (single-record) queries |
| Detail relations disabled | No nested data in detail queries, even if relations exist in the model |
| API binding (list query name) | The GraphQL entry point consumers use for list queries |
| API binding (detail query name) | The GraphQL entry point consumers use for detail queries |
View configuration is the primary mechanism for shaping the consumer experience without altering the underlying domain model. Two views on the same table can expose different subsets of fields, different default orderings, and different relation depths.
See Views for the complete configuration reference.
View column configuration and the resulting API response shape side by side.
API Design to Export
The API Design configuration determines what appears in a generated Export backend. Decisions made in the API design area propagate directly into the structure and content of generated code.
| API Design Decision | Export Consequence |
|---|---|
| Operation enabled (list or detail) | Corresponding resolver and service method generated |
| Operation disabled | No code generated for that operation |
| Custom query name | Resolver method and GraphQL field named accordingly |
| Pagination defaults (page size, max limit) | Default values embedded in the generated service layer |
| Sort defaults | Default ordering applied in generated query methods |
Disabling an operation before export is permanent for that generation run. Re-enabling and re-exporting produces the previously omitted code, but any manual modifications to the first export are not retroactively merged.
See Export for the generation workflow and output structure.
Disabled list operation in API design and the absence of the corresponding resolver in generated code.
Plan to Features
Your account plan determines the feature surface available to your team. Each tier builds on the one below it.
| Plan | Key Consequences |
|---|---|
| Guest | Temporary project bound to browser session; public endpoint; no team; no persistence across sessions |
| Free | Persistent projects; public endpoint; 2 users (Owner + 1 Extern/Reporter); 1,000 requests/day |
| Professional | Private endpoints with API key authentication; up to 10 + 1 Maintainer; 50,000 requests/month |
| Business | Unlimited projects; usage analytics; up to 15 + 3 Maintainers; 250,000 requests/month |
| Enterprise | Custom datasets; SSO (planned); SLAs; on-premise deployment option; configurable limits |
The plan boundary is enforced at the platform level. Attempting to create a private endpoint on the Free plan, for example, will fail with a plan restriction error rather than silently downgrading the endpoint to public.
See Account and Plans for the full tier comparison and upgrade workflow.
Role to Access
Roles govern what each team member can do within a project. Role assignment is per-project — a user can hold different roles across different projects.
| Role | Access Consequences |
|---|---|
| Extern | Read-only access to project data; no comments; no configuration changes |
| Reporter | Read access plus the ability to add comments on entities and views |
| Maintainer | Read, comment, and edit: can modify projects, models, views, API design, and exports; data import restricted on Enterprise plans |
| Owner | Full control: all Maintainer capabilities plus team management, billing, data import, and project deletion |
Role restrictions are enforced at the API level, not merely in the UI. A Maintainer who attempts to delete a project via a direct API call will receive an authorization error.
See Account and Plans for role definitions and team composition rules per plan.
Hint Chains
Mockomat raises configuration hints when a modelling decision produces a predictable problem at runtime. Each hint traces back to a specific causal chain.
| Trigger | Runtime Effect | Hint Raised |
|---|---|---|
| Attribute has no mapping | null values returned for the field | Unmapped attribute hint in preview |
| Relation target entity missing or deleted | Empty nested data in query response | Relation warning hint |
Sortable flag on an incompatible type (e.g., json) | Sort parameter exposed but produces undefined ordering | Configuration mismatch hint |
| No endpoint configured for an entity with a view | Entity not queryable despite having a view | Missing endpoint hint |
| Required flag on an attribute with no mapping | Non-null field returns null, violating schema contract | Required-unmapped conflict hint |
Hints are non-blocking. They do not prevent you from saving or deploying. They exist to surface consequences early — before a consumer encounters unexpected behavior in production.
Preview panel showing multiple configuration hints with their causal explanations.
Cross-Cutting Chains
The chains described above do not operate in isolation. A single user action often triggers a cascade that spans multiple layers. The following end-to-end sequences illustrate the full propagation path.
From Table Creation to API Consumer
- Table created on the Modelling Board — entity registered in project metadata.
- Attributes configured in Tables & Attributes — field names, types, and flags defined.
- Mappings assigned in Data Sources — each attribute linked to a data origin.
- View created in Views — column visibility, ordering, and pagination defaults set.
- API design configured in API Design — query names and enabled operations finalized.
- Schema generated — GraphQL types, fields, and query entry points constructed from the above.
- Consumer queries endpoint — Runtime executes the pipeline and returns shaped data.
Every step in this chain is reversible. Removing a view at step 4 makes the entity unreachable at step 7 without altering steps 1 through 3.
From Relation to Nested Query
- Relation drawn on the Modelling Board — connection established between two entities.
- Cardinality selected (1:1, 1:n, or m:n) — determines whether the nested result is an object or an array.
- Direction set — determines which entity exposes the nested data in its schema.
- Runtime builds lookup stage — a
$lookupaggregation stage is appended to the query pipeline. - Consumer queries nested fields — the GraphQL query includes a selection set on the related type.
- Result assembler constructs response — lookup results are merged into the parent document and shaped per the view configuration.
Changing the cardinality at step 2 after consumers have integrated alters the response shape (object vs array), which is a breaking change.
From Attribute Flag to Query Behavior
- Flag enabled on an attribute (sortable, filterable, or searchable) in Tables & Attributes.
- Schema regenerated — the corresponding query parameter or filter input is added to the GraphQL schema.
- Query parameter available — consumers can now include the parameter in their requests.
- Consumer uses parameter — a sort, filter, or search argument is included in a query.
- Runtime applies operation — the pipeline stage corresponding to the flag is executed against the data.
- Results reflect flag — the response is ordered, filtered, or narrowed according to the parameter.
Disabling a flag at step 1 removes the parameter from the schema at step 2. Consumers who reference the removed parameter will receive a schema validation error.
End-to-end flow diagram from table creation through attribute configuration to consumer query.
Summary
Causality in Mockomat is deterministic and traceable. Every configuration decision has a known, predictable effect on the layers below it. The system does not apply implicit defaults or hidden transformations — what you configure is what your consumers receive.
When evaluating a modelling change, trace the chain forward:
- Will this rename break existing consumer queries? (Model to API)
- Will this new relation increase query latency? (Model to Runtime)
- Will this unmapped field produce nulls? (Mapping to Data)
- Will this hidden column disappear from the schema? (View to Consumer)
- Will this disabled operation remove generated code? (API Design to Export)
If the answer to any of these questions is uncertain, use the Modelling Runtime Preview to validate before committing the change.