Runtime

Runtime validation confirms whether domain and API decisions behave as expected under real query usage. It is the layer where your model goes from design to execution — and where you catch issues before your consumers do.

Runtime Purpose

The runtime answers practical questions early in your development process:

• Are field shapes predictable and consistent?
• Are relation lookups coherent and correctly nested?
• Do pagination and sorting assumptions hold under real data?
• Do filter expressions match the correct subset of records?
• Are null values handled the way your consumers expect?

By validating these behaviors during modeling — not after implementation — you eliminate an entire category of integration bugs.

rt-01-query-playgroundMissing

Runtime query panel for live behavior checks.

How the Mock Runtime Works

The mock runtime engine is the core of Mockomat. It accepts GraphQL queries and translates them into MongoDB operations through a four-stage pipeline:

1. GraphQL Request Parser

The incoming query string is parsed into an abstract syntax tree (AST). This stage validates query syntax and extracts the requested fields, arguments, and nested selections.

2. Query Planner

The AST is analyzed alongside your model metadata (entity definitions, attribute flags, relation configurations) to create an execution plan. The planner determines:

• Which MongoDB collections to query
• Which fields to project
• What filter and sort operations to apply
• Which relations need to be resolved

3. MongoDB Query Builder

The execution plan is translated into a MongoDB aggregation pipeline. Because MongoDB stores data in flat (denormalized) collections, the query builder simulates relational structure:

• Lookup stages assemble related data across collections
• Match stages apply filter expressions
• Sort stages order results by the requested fields
• Skip and limit stages handle pagination

4. Result Assembler

The raw MongoDB results are reshaped to match the expected GraphQL response structure. Nested relations are assembled into the correct parent-child hierarchy, and field names are mapped to their GraphQL equivalents.

This pipeline runs on every query. What you see in the preview is exactly what external consumers receive from the same endpoint.

rt-01b-runtime-pipelineMissing

Four-stage runtime pipeline: parse → plan → build → assemble.

Query Examples

All queries go to the same endpoint:

POST /mock/{slug}/graphql

List Query

Fetch a paginated collection of records:

query {
  products(offset: 0, limit: 20) {
    id
    name
    price
    category {
      id
      name
    }
  }
}

Detail Query

Fetch a single record by its identifier:

query {
  product(id: "abc-123") {
    id
    name
    price
    description
    category {
      id
      name
    }
  }
}

Query with Filtering

Apply filter expressions to narrow results:

query {
  products(
    filter: {
      filterGroup: {
        operator: AND
        items: [
          { attribute: "price", operator: GE, value: "10" }
          { attribute: "price", operator: LE, value: "50" }
        ]
      }
    }
    limit: 10
  ) {
    id
    name
    price
  }
}

Query with Sorting

Order results by a sortable field:

query {
  products(
    sort: { field: "price", direction: DESC }
    limit: 10
  ) {
    id
    name
    price
  }
}

Query with Nested Relations

Traverse relations to include related data:

query {
  customers(limit: 5) {
    id
    firstName
    lastName
    orders {
      id
      totalAmount
      createdAt
      items {
        id
        productName
        quantity
      }
    }
  }
}

Filtering in Detail

The filter system supports type-safe, composable expressions that can be combined using boolean logic.

Available Operators

Operator	Description	Works With
EQ	Equals	All types
NE	Not equals	All types
LT	Less than	Numbers, Dates
GT	Greater than	Numbers, Dates
LE	Less than or equal	Numbers, Dates
GE	Greater than or equal	Numbers, Dates
LIKE	Contains substring	Strings
IS_NULL	Field is null	All types
IS_NOT_NULL	Field is not null	All types

Combining Filters

Filters use boolean algebra with AND and OR operators. Filter groups can be nested for complex expressions:

filter: {
  filterGroup: {
    operator: OR
    groups: [
      {
        operator: AND
        items: [
          { attribute: "status", operator: EQ, value: "active" }
          { attribute: "price", operator: GT, value: "100" }
        ]
      }
      {
        operator: AND
        items: [
          { attribute: "status", operator: EQ, value: "featured" }
        ]
      }
    ]
  }
}

This example returns products that are either (active AND expensive) OR featured.

Filterable Fields

Only attributes marked as filterable: true in the model can be used in filter expressions. Attempting to filter on a non-filterable field will have no effect. Configure filterable flags in the Tables & Attributes editor.

Pagination

Mockomat uses offset-based pagination:

Parameter	Description	Default
offset	Number of items to skip	0
limit	Number of items to return	20

A typical paginated request:

query {
  products(offset: 40, limit: 20) {
    id
    name
    price
  }
}

This returns items 41-60. To fetch the next page, increment the offset by the limit value.

Sorting

Fields marked as sortable: true in the model can be used for ordering results.

Direction	Meaning
ASC	Ascending (A→Z, 0→9, oldest→newest)
DESC	Descending (Z→A, 9→0, newest→oldest)

Only one sort field can be applied per query. If no sort is specified, results are returned in their natural storage order.

Relation Traversal

One of the runtime's most powerful features is its ability to simulate relational data from flat MongoDB collections.

How It Works

MongoDB stores data in denormalized collections — each record is a flat document without foreign key joins. The runtime simulates relational structure by:

1. Reading the relation definition from your model (source entity, target entity, cardinality).
2. Building lookup stages in the MongoDB aggregation pipeline that join related collections.
3. Assembling nested results that match the GraphQL response shape.

This means your GraphQL queries behave as if they are running against a fully relational database, even though the underlying storage is document-based.

What to Validate

When testing relation traversal:

• 1:1 relations should return a single nested object (or null if no match).
• 1:n relations should return an array of nested objects.
• Empty relations should return an empty array [], not null.
• Deeply nested relations (e.g., Customer → Order → OrderItem) should resolve correctly at each level.

Query Behavior Checklist

For each key entity in your model, validate:

• List query stability — does the same query return consistent structure across repeated calls?
• Single-item consistency — does a detail query return all expected fields?
• Null and missing-field behavior — are optional fields correctly represented as null?
• Relation traversal — do nested objects resolve with the correct cardinality?
• Filter accuracy — do filter expressions match the expected subset?
• Sort correctness — does sorting produce a predictable, stable order?
• Pagination boundaries — do offset and limit produce clean page slices without duplicates?

rt-02-filter-sort-paginationMissing

Filter, sort, and pagination behavior validation.

Runtime Inspection and Debugging

When behavior looks wrong, inspect in this order. For a comprehensive diagnostic guide covering all common issues and their resolutions, see the Troubleshooting reference.

1. Check Table and Attribute Definitions

The most common cause of unexpected behavior is a misconfigured attribute:

• Is the field type correct? (A price stored as string won't sort numerically.)
• Is the field marked as sortable/filterable/searchable?
• Does the field have a mapping configured?

2. Check Endpoint and Query Metadata

Verify that the query is configured correctly in the API design view:

• Is the query enabled?
• Are the query name and parameters correct?
• Is the pagination configuration appropriate?

3. Check Source Mapping State

If fields return null or unexpected values:

• Is the mapping type correct (OFF_FIELD, FAKE, CONST)?
• For OFF_FIELD mappings, does the source dataset contain the expected data?
• For FAKE mappings, is the Faker generator configured for the right data type?

4. Check Relation Policies

If nested data is missing or incorrect:

• Is the relation direction correct (source → target)?
• Is the cardinality right (1:1 vs 1:n)?
• Does the target entity exist and have mapped data?
• Are the linking columns correctly specified?

Common Issues and Resolutions

Symptom	Likely Cause	Resolution
Empty response	No data imported for this collection	Check that the data import has been completed
Fields return null	No mapping configured	Add OFF_FIELD, FAKE, or CONST mapping
Nested relation empty	Relation misconfigured	Verify direction, target entity, and linking columns
Sort not working	Field not marked sortable	Enable sortable flag in table editor
Filter returns everything	Field not marked filterable	Enable filterable flag in table editor
Wrong data types	Mapping type mismatch	Check that mapping produces the expected type
Pagination skips items	Offset calculation error	Verify offset increments by limit value

rt-03-runtime-inspectionMissing

Runtime inspection flow and debug checkpoints.

Validation Before Export

Runtime should confirm readiness before you move to backend code generation. A model that passes runtime validation is far more likely to produce a clean, functional generated backend.

Readiness Criteria

Before exporting, confirm that:

• Required fields are stable — all required attributes have consistent, non-null values.
• Operation surface is intentional — only the queries you want to expose are enabled.
• Relation behavior is explainable — every nested query resolves correctly and the cardinality matches your business rules.
• Filter and sort behavior is predictable — consumers can rely on these operations working as documented.
• No unresolved hints — the preview shows no warnings about unmapped attributes or missing configuration.

Pre-Export Validation Workflow

1. Run list queries for every entity — check structure and data quality.
2. Run detail queries for key entities — check field completeness.
3. Test all configured filters — verify correct subsetting.
4. Test sort on every sortable field — verify ordering.
5. Test pagination boundaries — verify clean page transitions.
6. Test nested relation queries — verify correct assembly at every level.

rt-04-runtime-validationMissing

Pre-export runtime validation summary view.

Integrator tip

Developer / Integrator

Use runtime validation as a contract check before integrating frontend or downstream consumers. The runtime endpoint serves the same data to preview and external consumers, so what you validate in the workspace is exactly what your application will receive. This reduces integration churn significantly.

Enterprise runtime expectations

Enterprise User

Enterprise teams should treat runtime validation as a formal quality gate. Define validation criteria per entity (required fields, relation depth, filter coverage) and include runtime checks in your review process before promoting models to production use.