Skip to main content

Master-Detail DataSets

A master-detail relationship is configured on the detail dataset. The detail dataset observes the current record of its master and adds the relation values to its effective query.

The adapter does not need a special master-detail protocol. It receives an ordinary query containing the effective filter constraints.

Configure a relation​

final customers = FdcDataSet(
  fields: const [
    FdcIntegerField(name: 'customer_id', isKey: true),
    FdcStringField(name: 'company', size: 120),
  ],
  adapter: customerAdapter,
);

final orders = FdcDataSet(
  fields: const [
    FdcIntegerField(name: 'order_id', isKey: true),
    FdcIntegerField(name: 'customer_id'),
    FdcDateField(name: 'order_date'),
  ],
  adapter: orderAdapter,
  masterDataSet: customers,
  masterRelation: const [
    FdcMasterDetailRelation(
      masterField: 'customer_id',
      detailField: 'customer_id',
    ),
  ],
);

masterDataSet and masterRelation must be configured together. A detail dataset cannot use itself as its master.

Composite relations​

Use multiple relation items for composite keys:

masterRelation: const [
  FdcMasterDetailRelation(
    masterField: 'company_id',
    detailField: 'company_id',
  ),
  FdcMasterDetailRelation(
    masterField: 'customer_id',
    detailField: 'customer_id',
  ),
],

Each detailField mapping must be unique.

Query composition​

Master-detail constraints compose with normal detail-dataset filters. A user filter does not replace the active relation:

await orders.filter.set(const [
  FdcDataSetFilter(
    fieldName: 'status',
    operator: FdcFilterOperator.equals,
    value: 'open',
  ),
]);

The effective query still includes the current master relation values.

Insert behavior​

When a new detail record is inserted, relation values can be propagated from the current master record into the mapped detail fields. This keeps new detail records aligned with the active master context.

Lifecycle​

Open the master dataset before the detail dataset:

await customers.open();
await orders.open();

When the master current record changes, the detail dataset refreshes against the latest relation values. The coordination belongs to the dataset layer, so it works with grids, standalone editors, or custom widgets.