Design Good Field Definitions

After this page, you can define fields that are clear for UI builders and safe for report 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

Use for values like status, city, country, and names.

Field::string('status')
    ->label('Status')
    ->column('orders.status')
    ->sortable()
    ->filterable([FilterOperator::Equals, FilterOperator::In, FilterOperator::Like]);

2) Numeric fields

Use for amount, quantity, and score fields.

Field::integer('item_count')
    ->label('Item Count')
    ->column('orders.item_count')
    ->sortable()
    ->filterable([
        FilterOperator::Equals,
        FilterOperator::GreaterThan,
        FilterOperator::LessThanOrEqual,
        FilterOperator::Between,
    ]);

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

3) Boolean fields

Use for true/false states.

Field::boolean('is_refunded')
    ->label('Refunded')
    ->column('orders.is_refunded')
    ->filterable([FilterOperator::Equals, FilterOperator::NotEquals]);

4) Date and datetime fields

Use for event timestamps and reporting windows.

Field::date('ordered_on')
    ->label('Order Date')
    ->column('orders.ordered_on')
    ->sortable()
    ->filterable([
        FilterOperator::DateEquals,
        FilterOperator::DateBefore,
        FilterOperator::DateAfter,
        FilterOperator::Between,
        FilterOperator::ThisMonth,
        FilterOperator::LastNDays,
    ]);

Field::dateTime('created_at')
    ->label('Created At')
    ->column('orders.created_at')
    ->sortable()
    ->filterable([
        FilterOperator::DateAfter,
        FilterOperator::DateBefore,
        FilterOperator::ThisWeek,
    ]);

5) Formatting and key mapping

Use a stable public key, then map it to trusted DB columns.

Field::decimal('net_revenue')
    ->label('Net Revenue')
    ->column('orders.total_amount')
    ->format('currency')
    ->sortable();

net_revenue is your public report key. orders.total_amount is your trusted backend column.

Verify

Run a preview and confirm:

• selected columns return in stable order
• numeric fields can be sorted and aggregated
• invalid operators are rejected by validation

Common mistakes

• Using text fields for numeric values.
• Using old enum names like Eq or Gt.
• Allowing unsupported operators on date/boolean fields.
• Adding aggregate functions to fields that are not meaningful to aggregate.
• Using unstable keys that change over time and break saved definitions.