Table filters and sorting

Table surfaces can filter and sort by a field reached through a chain of ordinary references. A record type does not need separate Community, District, and Region fields to expose all three controls.

For an AidRecord that stores only Community, a table may expose:

Community
Community / District
Community / District / Region

The complete query path is the target identity. These three targets may coexist because their paths differ, even though they share the same first field. Only an exact duplicate of the complete path is rejected.

When the Table Surface uses Parent Tree View, each root or child sibling set is sorted independently by the server. Search and filters retain visible ancestor context; changing the query reloads roots and branches.

Read supported targets first

Read the installation-provided options before writing configuration:

GET /api/workspace/admin/entity-definitions/{aidRecordDefinitionId}/ui/table-surfaces/configuration/options

FilterTargets[] and SortTargets[] contain human-readable labels, stable technical keys, field metadata, operators, and the complete typed path. Match the desired labels and copy the returned Target or SortTarget object. Do not guess record IDs, field IDs, field keys, or enum values.

A field segment may contain both EntityFieldDefinitionId and EntityFieldKey. When both are supplied, they must identify the same field. Each segment after the first is resolved relative to the entity definition targeted by the preceding reference.

Configure three filters with one root

The following abbreviated request shows the relevant table properties. The IDs are examples; copy the real targets from your options response.

{
  "FilterItems": [
    {
      "Target": {
        "TargetKind": 0,
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" }
        ]
      },
      "Label": "Community",
      "Visible": true,
      "VisibleByDefault": true,
      "ReferenceInputType": 2,
      "ReferenceRendererType": 0,
      "ReferencePath": [],
      "SortOrder": 10
    },
    {
      "Target": {
        "TargetKind": 0,
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" },
          { "EntityFieldDefinitionId": "field-district", "EntityFieldKey": "District" }
        ]
      },
      "Label": "District",
      "Visible": true,
      "VisibleByDefault": true,
      "ReferenceInputType": 2,
      "ReferenceRendererType": 0,
      "ReferencePath": [],
      "SortOrder": 20
    },
    {
      "Target": {
        "TargetKind": 0,
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" },
          { "EntityFieldDefinitionId": "field-district", "EntityFieldKey": "District" },
          { "EntityFieldDefinitionId": "field-region", "EntityFieldKey": "Region" }
        ]
      },
      "Label": "Region",
      "Visible": true,
      "VisibleByDefault": true,
      "ReferenceInputType": 2,
      "ReferenceRendererType": 0,
      "ReferencePath": [],
      "SortOrder": 30
    }
  ],
  "SortItems": [
    {
      "Target": {
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" },
          { "EntityFieldDefinitionId": "field-district", "EntityFieldKey": "District" },
          { "EntityFieldDefinitionId": "field-region", "EntityFieldKey": "Region" }
        ]
      },
      "Label": "Region",
      "Visible": true,
      "SortOrder": 10
    }
  ],
  "DefaultSort": [
    {
      "Target": {
        "Path": [
          { "EntityFieldDefinitionId": "field-community", "EntityFieldKey": "Community" },
          { "EntityFieldDefinitionId": "field-district", "EntityFieldKey": "District" },
          { "EntityFieldDefinitionId": "field-region", "EntityFieldKey": "Region" }
        ]
      },
      "Direction": 0,
      "SortOrder": 10
    }
  ]
}

Use the other required properties from the current table configuration when sending the replace request.

DefaultSort[].SortOrder controls precedence from lowest to highest. An explicit 0 is a valid priority and is preserved on readback, repeated saves, cloning and YAML export/import. If you omit the property, Moltaro assigns 10, 20, and so on from each item’s position in the input array. Equal priorities use a stable target-path tie-breaker; assign different values when precedence matters. Reading existing configuration does not renumber its priorities. The visual Constructor can assign 10, 20, ... when saving its ordered list, while keeping the order shown in the editor.

`Target.Path` is not `ReferencePath`

These properties solve different problems:

Target.Path identifies the terminal field used by the server-side query. In the Region filter above, the picker values are Region record IDs.
ReferencePath controls breadcrumb rendering inside a reference value picker. It never changes which field is filtered.

Changing ReferencePath cannot turn a Community filter into a Region filter. For a related target, copy the full Target.Path from FilterTargets[], then choose ReferencePath independently from that target’s ReferencePathOptions[].

Choice Statement

A Reference filter can offer only the records of the referenced entity that match a Statement. For example, a Case table on a page for one direction can offer only specialists of that direction in its Specialist filter.

Each Reference target in FilterTargets[] lists CandidateStatementOptions[]: the active Statements of the referenced entity that are exposed to clients. Copy one Id into the filter item:

{
  "Target": { "TargetKind": 0, "Path": [{ "EntityFieldKey": "Specialist" }] },
  "Visible": true,
  "VisibleByDefault": true,
  "CandidateStatementId": "<id from CandidateStatementOptions>"
}

Every picker for that filter, including the Reference Eligibility candidate picker, applies the Statement to its candidates. It narrows the choices only and is not an access restriction; the rows the table shows are filtered by the value the user picks. A choice Statement is not available for filters that use Hierarchy input. If the Statement is later deleted or hidden from clients, the filter is reported as unavailable instead of offering every record. Entity Definition YAML carries CandidateStatementId and CandidateStatementName; import resolves the id first and then the technical name in the referenced entity.

In the Constructor, the filter dialog shows this as the choice Statement. The filter and sort lists also offer Delete: a deleted item can be added again, and deleting a sort item removes it from the default sort.

Validation and limits

Filter paths contain 1 to 6 segments.
Sort paths contain 1 to 4 segments.
A request may apply at most 3 sort items.
Every intermediate segment must be a readable, primary-table Reference.
Table and InverseReference are not valid path terminals here.
Statement and object-context-fact targets are root-only.
A related system field is terminal, for example three reference segments followed by { "SystemField": 1 } for the related record’s Display Name.
CandidateStatementId requires a Reference terminal without Hierarchy input and an active, client-exposed Statement of the referenced entity.

The terminal field determines the available operators and value editor. Reference Eq and In operands are IDs of records in the terminal entity definition.

Read back and verify

After PUT, read the table configuration again and confirm all paths:

GET /api/workspace/admin/entity-definitions/{aidRecordDefinitionId}/ui/table-surfaces/{surfaceKey}/configuration

Then open the table as an ordinary user:

Apply District and Region filters and verify rows and total count.
Sort by Region and verify visible order and pagination.
Confirm restricted related fields or records do not become visible through target labels, matches, or counts.
Clear temporary filters and restore the intended default view.

For exact Runtime API payloads, see Entity Instance Query.