Report Builder Docs

Appearance

Design Good Field Definitions ​

After this page, you can define fields that are useful for UI and safe for backend execution.

Problem ​

A bad field model creates confusing UI and unsafe query intent.

Prerequisites ​

  • A registered data source
  • Understanding of your model columns

Steps ​

Use these field patterns:

  1. String categorical fields (status, country)
    • usually filterable
  2. Numeric fields (total_amount, quantity)
    • sortable + numeric operators + aggregates
  3. Date/datetime fields (created_at)
    • sortable + range operators
php
Field::string('status')
    ->label('Status')
    ->column('orders.status')
    ->filterable([FilterOperator::Eq, FilterOperator::In]);

Field::decimal('total_amount')
    ->label('Total Amount')
    ->column('orders.total_amount')
    ->sortable()
    ->groupable()
    ->filterable([FilterOperator::Eq, FilterOperator::Gt, FilterOperator::Between])
    ->aggregates([AggregateFunction::Sum, AggregateFunction::Avg]);

Verify ​

Check /report-builder/sources/{source} response and confirm:

  • each field has correct type
  • only valid filter_operators are present
  • aggregates are only enabled where appropriate

Common mistakes ​

  • Using text fields for numeric values.
  • Allowing unsupported operators on date/boolean fields.
  • Adding aggregate functions to non-sense fields.